先把话说在前面这篇文章写的是在银河麒麟V10 ARM版上不通外网、没法直接 apt update 的环境里从零把Qt5、gcc、Qt Creator全部装好并且把**构建套件Kit**配到能跑最小程序的完整流程。它解决的痛点很明确你已经拿到一台飞腾或者鲲鹏处理器的麒麟系统机器系统里连编译链都不全软件源全是镜像站快照装个 gcc 都要看运气更别提装完 qtcreator 之后还要处理一堆依赖缺失。我前前后后在麒麟 ARM 版上装过不下五套 Qt5 环境从坑里爬出来的经验是离线安装这事真正的难点不在于“装 Qt”而在于“把依赖关系理顺”。只要依赖链判断得准装出来的开发环境能用很多年要是稀里糊涂地乱装装完跑起来就是各种cannot find -lGL、qt.qpa.plugin: Could not find the Qt platform plugin xcb、Kit 里找不到编译器心态直接爆炸。这篇文章适合谁看两类人一类是单位内网、项目现场拿到麒麟 ARM 机器、手里只有安装包没有网络的实施工程师另一类是拿 orangepi、飞腾开发板折腾 Qt5但觉得交叉编译太麻烦、想直接在板子上原生编译的程序员。下面这套流程基本是我现场排错后沉淀下来的标准操作照着走能省一整天时间。1. 动手前的准备先把系统“家底”摸清离线安装最忌讳的就是不看系统直接开搞。同一个“银河麒麟V10”的称呼下实际系统可能完全是两套底层装错方向后面每一步都在还债。1.1 确认发行版与包管理器桌面版和服务器版是两套逻辑银河麒麟V10分成两个大系桌面版底层走的是 Debian 那一套包管理器是apt/dpkg服务器版底层走的是 Red Hat 那一套对应的是yum/dnf。刚接触麒麟系统的人最容易在这里翻车——拿着yum install的思路在桌面版上硬敲或者下载一堆.rpm包想在桌面版上装系统直接给你吐一行红色报错。上机第一步用下面三条命令把“家底”摸清楚# 查看系统大致信息 cat /etc/os-release # 确认架构ARM版一般输出 aarch64 uname -m # 看包管理器可用状态 which apt dpkg yum dnf rpm如果输出里有apt那后面所有离线包都按.deb思路来如果只有yum和rpm就去准备.rpm包。本文下面的实操主要以.deb体系为例因为桌面版在项目里碰到得最多但对应思路放到 rpm 体系完全可以平移只是命令从dpkg -i换成rpm -ivh。1.2 确认CPU架构与已有工具链在 ARM 机器上执行uname -m正常情况下是aarch64偶尔能看到armv8l。这两个都不会影响太大真正要留意的是下载安装包时千万别抓成armhf32位软浮点或者x86_64的包。架构搞错是离线安装里最隐蔽的坑因为在安装阶段不一定立刻报错等到编译 Qt 程序时报一堆奇怪的 “cannot find -lxxx” 你根本想不到是架构问题。接着看看已有工具链是什么状态gcc --version g --version make --version cmake --version银河麒麟V10 ARM 桌面版原装系统通常会带一个老版本的 gcc但 g 和 cmake 可能就是空的需要单独补。没有任何编译链的情况下想用源码编译 Qt5 几乎不可能所以第一步拿到离线包之前必须先把 gcc/g 装上。1.3 离线安装包的“搬运”思路离线环境不管再怎么复杂核心思路只有一条找一台和离线机同架构、同系统的在线机器把需要的软件和依赖全部下载成安装包然后拷贝过去安装。具体到 Qt5 这件事推荐三种搬运方式按省事程度排序方式一在线机apt-get download拉取指定包。比如我需要qtbase5-dev直接在在线机上apt-get download qtbase5-dev它会把.deb装进当前目录。方式二用apt-cache depends递归找全依赖。先查依赖列表再逐个apt-get download或者写个 for 循环批量拉取。方式三在在线机上把整个软件包缓存目录打包。Debian/Ubuntu 系的/var/cache/apt/archives里会保留所有已经下载过的.deb直接把整个目录拷到离线机再dpkg -i *.deb也可以应急。我个人最常用的是方式二因为目标明确、不拖泥带水。后面讲到 Qt5 库安装时我会把递归拉依赖的具体命令放出来。2. GCC工具链安装与版本管理Qt5编译的第一块地基很多人在“离线装 Qt”这件事上栽跟头根本不是 Qt 的问题而是 gcc 没装好就直接编译编译到一半报错又回头补环境。这一节先把编译链焊死。2.1 系统自带gcc为什么总是不够用银河麒麟V10 ARM 桌面版原装环境我见过比较多的是 gcc 7.5 或 gcc 9.3。这个版本对 Qt 5.12 和 Qt 5.15 来说基本够用但有两个现实问题一是系统只带了gccg缺失而 Qt 程序编译核心是用 g二是缺少make、cmake这些构建工具没有它们连 qmake 生成出来的 Makefile 都跑不动。所以不要天真地以为“系统有 gcc 就能编译 Qt 程序”亲测第一步就该执行sudo apt-get update sudo apt-get install -y gcc g make cmake在线环境一条命令就完事了。离线环境就得先把这四个依赖的.deb包准备好。2.2 用deb包离线升级gcc的完整动作假设你需要把 gcc 升到更高版本或者是系统只装了老 gcc 想补 g操作流程是这样先在一台能够联网、并且系统尽量匹配的 ARM 在线机器上执行依赖拉取。这里有个小技巧不要只apt-get download gcc g这俩包的依赖关系比较复杂建议直接拉build-essential它会连带把 gcc、g、make、libc-dev 等关键组件都拉下来mkdir /tmp/debs cd /tmp/debs # 先清空推荐、建议让 apt 只按硬依赖走 apt-get download $(apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances build-essential | grep ^\w | sort -u)注意apt-cache depends里--no-recommends之类的参数很重要不然会把一堆用不上的依赖一起拉到包体积直接翻倍。拉完后把/tmp/debs目录打包传给离线机。离线机上操作# 全部丢到一个目录然后安装 mkdir -p /tmp/kylin_debs # 把拷贝过来的 deb 包放进这个目录 dpkg -i /tmp/kylin_debs/*.deb如果提示缺依赖一般是被裁剪过的桌面系统少了某个libc6-dev或者libisl去在线机单独下载对应包再传过来补上即可。这里教大家一个判断缺什么的最快方式dpkg -i /tmp/kylin_debs/*.deb 21 | grep dependency输出的“dependency problems”里会直接写清楚缺哪个包照名字重新拉一次就行不用瞎猜。2.3 “gcc升级完还是旧版本”的真实原因以及怎么避坑热词里有一条很扎心的gcc升级后为啥还是旧版本。这个我太有感触了。绝大多数情况不是没装上而是装完的路径和当前 PATH 下生效的不是同一个第一种情况新系统里可能同时存在/usr/bin/gcc-9、/usr/bin/gcc-10但/usr/bin/gcc这个软链接还指向老的/usr/bin/gcc-9。解决方式就是改软链ls -l /usr/bin/gcc* sudo rm /usr/bin/gcc sudo ln -s /usr/bin/gcc-10 /usr/bin/gcc sudo rm /usr/bin/g sudo ln -s /usr/bin/g-10 /usr/bin/g第二种情况shell 里把命令路径缓存了。装完新 gcc 后which gcc显示的路径还是旧的/usr/bin/gcc实际是 hash 缓存执行hash -r刷新一下就好。第三种情况你手动编译安装的 gcc 装到了/usr/local/bin而系统默认 PATH 是/usr/bin优先。这种情况需要确认/usr/local/bin/gcc是否比/usr/bin/gcc靠前实在不行就同样用软链接把/usr/local/bin/gcc指到新版本或者直接把新版本的gcc软链到/usr/bin/gcc。这些“装完还不生效”的问题十有八九是软链接没改。改完之后记得验证三段which gcc gcc --version g --version2.4 make/CMake/gdb这些配套别落下gcc/g 只是编译器Qt 项目的自动化构建靠的是 make 和 cmake调试靠的是 gdbQt Creator 的 Kit 里每一项都要填上。离线机器上一般很少预装建议一次性拉齐。在线机器下载时就执行apt-get download make cmake gdb pkg-config libgl1-mesa-dev libxkbcommon-dev这里面有几个不是直接编译必须、但在 Qt Creator 配置 Kit 时一定会用的pkg-configQt 的.pc文件查找依赖时要用没有它很多目标平台的库路径解析不出来libgl1-mesa-dev提供 OpenGL 开发头文件和-lGL库Qt 的 OpenGL 相关模块离不开它libxkbcommon-dev处理键盘输入Qt 的 xcb 平台插件依赖这个库。补齐这一步之后就可以说编译链已经“焊死”了。我在这里还想多说一句每次装完工具链先编译一个 hello world不要直接上大工程cat /tmp/test.cpp EOF #include iostream int main() { std::cout hello aarch64 std::endl; return 0; } EOF g /tmp/test.cpp -o /tmp/test /tmp/test这一步能跑出hello aarch64再往下的 Qt 安装才安全。3. Qt5运行库离线安装真正的体力活和排错现场gcc 工具链是地基Qt 运行库就是主体结构这部分是离线安装里最容易出问题的一环。3.1 优先选系统仓库里的Qt5还是源码编译我选前者在 ARM 麒麟机器上装 Qt5市面上大致两条路路线A直接用系统仓库的qtbase5-dev、qtcreator等 deb 包。路线B下载 Qt 官方离线源码包qt-everywhere-src自己 configure make。只要系统仓库里能翻到 Qt5 包我无条件推荐路线A。理由很现实路线B 在 ARM 机器上源码编译 Qt5动不动就是 2 到 4 个小时而且要提前准备一大串构建依赖比如libfontconfig1-dev、libdbus-1-dev、libx11-dev、libxext-dev、libxfixes-dev、libxcb-xinerama0-dev等离线环境想配齐这些简直是噩梦。路线A直接用麒麟源里打包好的 Qt 5.11/5.12/5.15依赖关系在包管理器里已经写清楚了虽然版本不一定最新但胜在稳定、省时间。如果应用必须用特定版本比如要求 Qt 5.15.2那就考虑从官方下载qt-opensource-linux-arm64对应的.run离线安装器。这种安装器自带整个 Qt 框架但问题是它也会依赖一些系统库比如libxcb-xinerama0、libxkbcommon-x11-0装完如果跑 xcb 平台插件失败还得回头补这些。3.2 从在线ARM机器上抓整棵依赖树如果你采用路线A最稳的做法是在线机器上把qtbase5-dev及依赖全部抓下来。这里建议把整个qt5-default或者qtbase5-dev装进下载计划mkdir -p /tmp/qtdeps cd /tmp/qtdeps # 递归拉取 qtbase5-dev 的依赖 apt-get download $(apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances qtbase5-dev | grep ^\w | sort -u)这条命令拉下来的包数量可能超过 60 个因为里面包含了 Qt 的 QtCore、QtGui、QtWidgets、QtNetwork、QtSql 等基础模块以及一堆 xcb 相关依赖。这也是离线安装 Qt5 最核心的一次搬运。有一点提醒一下如果你的程序会用到 Qt 的 SerialPort、Multimedia 等模块记得追加libqt5serialport5-dev、libqt5multimedia5-dev之类的包否则后面程序里#include QtSerialPort/QSerialPort直接找不到头文件。搬运完成后离线机统一安装dpkg -i /tmp/qtdeps/*.deb同样会碰上缺失依赖的情况用21 | grep dependency排查即可。没有报错的话直接在终端里跑一个常规检查which qmake qmake --version输出类似QMake version 3.1且对应的 Qt 版本号出现了就说明 Qt5 核心库已经就位。3.3 安装后第一时间做“链接自检”很多人装完 Qt 运行库就急着打开 Qt Creator 建项目然后遇到一个经典的链接错误cannot find -lGL这个错误我在不同机器上见过不下十次。原因很简单Qt 的 GUI 模块在编译时会链接 OpenGL 库但系统里没有libGL.so的符号链接。Debian 系机器上需要libgl1-mesa-dev包来提供可默认安装的往往只是一个运行时库libgl1-mesa-dri没有开发软链接。所以装完 Qt 后直接用一行命令自检ls -l /usr/lib/aarch64-linux-gnu/libGL.so如果没有输出或提示不存在就去在线机补拉libgl1-mesa-dev或者临时做一个软链接不推荐长期用sudo ln -s /usr/lib/aarch64-linux-gnu/libGL.so.1 /usr/lib/aarch64-linux-gnu/libGL.so链接自检通过后再写一个小型 Qt 程序验证编译。不用打开 IDE直接命令行编译更能快速暴露依赖缺漏。3.4 信号槽传递结构体这种“小怪”顺手就清了排错排到能正常编译 GUI 程序后还有一类“运行期才炸”的问题尤其适合在离线环境下提前补课。最典型的就是交叉线程里通过信号槽传递结构体。默认情况下Qt 的信号槽传递QString、int这类内置类型没问题但如果信号参数是一个自定义结构体并且连接方式是跨线程的队列连接运行时你会看到QObject::connect: Cannot queue arguments of type MyStruct解决办法是在使用这个类型之前加上元类型注册Q_DECLARE_METATYPE(MyStruct) ... qRegisterMetaTypeMyStruct(MyStruct);这段经验其实和离线安装没直接关系但它属于“Qt 开发环境装好后最容易踩的坎”。在这个环节一起提醒是因为很多人装完环境、编译第一个完整业务工程时十有八九会碰到它提前知道能少查两小时。4. Qt Creator安装与构建套件Kit配置让IDE认对工具链Qt 库装完剩最后一公里把 Qt Creator 装好并配置 Kit。这一步要是没人指路新手能在“构建套件”这个界面卡很久。4.1 Qt Creator与Qt版本的匹配关系别搞反热词里有一条是qtcreator对应qt版本这里说清楚Qt Creator 是一个独立的 IDE它本身不绑定 Qt 版本理论上 Qt Creator 4.x 可以配合 Qt 5.12也可以配合 Qt 5.15。真正决定项目能不能编的是 Kit 里指定的qmake 版本和编译器版本而不是 Qt Creator 自己的版本。所以离线安装有两种选择选择A直接用系统仓库里的qtcreatordeb 包。它一般和源里的 Qt 版本配套装上就能用最省心选择B从 Qt 官网下载qt-creator-opensource-linux-x86_64或 arm64 的.run安装包手动装到/opt/qtcreator。对离线环境我建议优先用麒麟源里的qtcreator因为依赖少、版本匹配好。如果项目组统一要求某个 Qt Creator 版本再考虑.run包。.run包执行前记得先chmod x然后安装到/optsudo chmod x qt-creator-opensource-linux-x86_64-*.run sudo ./qt-creator-opensource-linux-x86_64-*.run要注意Qt 官方包名里的linux-x86_64是针对主机架构的如果这台麒麟机器本身是 aarch64要找linux-arm64的安装包。4.2 手动添加qmake、编译器、调试器的实操安装完成后第一次打开 Qt Creator进入“工具 → 选项 → Kits → 编译器”界面如果里面是空的不要慌手动添加三步第一步加编译器在“编译器”标签页点“添加 → GCC → C”“名称”填GCC aarch64“编译器路径”选/usr/bin/g“平台”选aarch64-linux-generic注意别选成 x86 的不然识别不了。第二步加调试器切到“调试器”标签页点“添加”名称填GDB aarch64路径选/usr/bin/gdb版本类型一般会自动检测英文版界面显示 “GDB” 就行。第三步加 qmake切到“Qt Versions”标签页点“添加”路径选/usr/bin/qmake系统会自动识别出 Qt 版本号比如Qt 5.12.8 (qtbase5-dev)。这三步做完回到“Kits”标签页点“添加”名字填Kylin ARM Qt5然后分别在下拉框里选刚才建好的“编译器 C”“编译器 C”“调试器”“Qt 版本”保存。这样 Kit 才算是配齐了。4.3 新建Kit后先跑最小验证别直接开大项目每次配完 Kit先建一个最小 QWidget 工程跑通再打开真实项目。这不是磨叽而是为了把“环境问题”和“业务代码问题”隔离。新建工程的模板选“Qt Widgets Application”一路默认。在“构建套件”选择界面确认已经勾选Kylin ARM Qt5。然后直接点左下角的绿色运行按钮等它弹出一个小窗口界面就算通了。如果编译时提示No suitable kits found检查顺序编译器是否识别成功、Qt Version 是否识别成功、Kit 里是否保存成功。这三个缺一不可。4.4 拖拽文件失效多半是平台插件依赖缺了热词里的qt5无法拖拽文件我提一下最常见的现场。Qt 应用在 Linux 桌面上拖拽文件进来底层依赖的是 xcb 平台插件的 XDND 支持而这又依赖libxcb-util1、libxcb-xinerama0、libxkbcommon-x11-0这些运行库。麒麟系统如果精简过图形依赖Qt Creator 本身能开但拖拽功能就是静默失效非常隐蔽。解决方式很直白把下面几个包装进去apt-get download libxcb-util1 libxcb-xinerama0 libxkbcommon-x11-0 libxcb-icccm4 libxcb-keysyms1 libxcb-render-util0 libxcb-image0然后离线机dpkg -i安装。装完要彻底退出 Qt Creator 再重开拖拽立刻恢复。这个经验我不止一次在项目现场用过属于那种“问题不大但特别折磨人”的坑提前装好心情舒畅很多。5. 扩展话题同一套离线思路能不能干交叉编译很多人搜到这个标题其实背景并不是“麒麟机器上开发”而是“我在 x86 电脑上要交叉编译给 ARM 盒子跑”。热词里的orangepi cm5安装qt5 交叉编译就是这种需求。这里顺手讲一下免得大家方向走偏。5.1 什么时候需要交叉编译什么时候不必如果目标机是一台完整的 ARM 麒麟电脑而且性能能接受直接在上面装 gcc 和 Qt 库然后原生编译是最省事的。交叉编译是在目标机上编译太慢比如开发板、便携 ARM 盒子或者目标机没有完整桌面环境时才值得考虑的方案。交叉编译需要准备的东西比原生编译多一层交叉编译器比如aarch64-linux-gnu-gcc、目标机器的 sysroot包含目标架构的 libc、库文件、目标架构的 Qt 库。5.2 交叉编译Qt5的三个关键注意点第一交叉编译器版本与目标机器的库版本要匹配。假设目标麒麟机器 glibc 是 2.28交叉工具链里自带的 glibc 也得保持对应的 ABI 兼容否则编出来的二进制拷过去直接Segmentation fault。第二Qt 库必须是目标架构的。不能拿 x86 麒麟机器上的/usr/lib/x86_64-linux-gnu/libQt5Core.so去链必须在交叉环境下单独编译一份 ARM 版 Qt或者从目标机器的软件源里拉取目标架构的 deb 包解包成 sysroot。第三qmake也必须用交叉版。一般在源代码编译 Qt 时会用./configure -xplatform linux-aarch64-gnu-g -prefix /opt/qt5-arm生成交叉版 qmake然后 Qt Creator 里添加一个新的 Qt Version 指向这个 qmake再添加aarch64-linux-gnu-g为新的编译器组成一个独立的交叉 Kit。交叉编译这个话题本身能写一整篇但在离线安装的语境下我建议先把前面的原生安装吃透再碰交叉。因为交叉编译的报错信息里经常同时混着“工具链不对”“库架构不对”“qmake 不对”三种原因没有原生编译经验打底排错基本靠猜。6. 高频报错与排查速查表下面这个表是我现场安装中最常遇到的报错整理每个都对应“银河麒麟 ARM 版 Qt5 离线环境”的实际场景可以直接当速查表用。报错现象根本原因处理方式qmake: command not foundQt 开发包没装或 Qt5 的 bin 目录没进 PATH安装qtbase5-dev或qt5-qmake再执行which qmakecannot find -lGL缺少 OpenGL 开发软链接安装libgl1-mesa-dev或检查/usr/lib/aarch64-linux-gnu/libGL.soCould not find the Qt platform plugin xcbxcb 相关运行库缺失补装libxcb-xinerama0、libxkbcommon-x11-0、libxcb-util1等项目里 Kit 显示无效黄色感叹号编译器、qmake、调试器中某路径失效重新进 Kits 添加编译器路径/usr/bin/g、qmake/usr/bin/qmake、调试器/usr/bin/gdbNo suitable kits foundQt Version 或编译器没识别成功先确认“Qt Versions”里有版本号“编译器”里识别出 aarch64 GCC再重新建 KitCannot queue arguments of type MyStruct自定义结构体没注册到 Qt 元类型系统加Q_DECLARE_METATYPE(MyStruct)并用qRegisterMetaType注册gcc: error: unrecognized command line option -stdc11gcc 版本过老按 2.3 节方法升级 gcc并核对/usr/bin/gcc软链接dpkg: dependency problems prevent configuration离线包依赖缺个包用dpkg -i *.deb 21 | grep dependency找到缺失包名回在线机补拉还有一个高频但不是报错的问题麒麟系统下 Qt Creator 生成的桌面快捷方式经常没有执行权限直接双击没反应。解决办法是右键属性里勾选允许执行或者在终端启动/usr/bin/qtcreator如果从终端能启动但桌面上不行检查快捷方式的Exec路径与真实安装路径是否一致。这类问题看起来跟“开发环境”没关系但现场演示时非常容易手忙脚乱我建议提前把这一条也记到部署文档里。最后再分享一个小技巧是我在实际项目里总结出来的每次离线装完环境不要急着收工先用tar把/usr/lib/aarch64-linux-gnu/下与 Qt 相关的库、/usr/lib/aarch64-linux-gnu/cmake下的 CMake 模块目录、/usr/bin/qmake和 Qt Creator 的版本信息都记录成一个文本清单。dpkg -l | grep -i qt /opt/qt5_install_record.txt dpkg -l | grep -i gcc /opt/qt5_install_record.txt这个文件在以后重复部署同型号机器时能省掉一半的试错时间——直接照着清单抓包就行不用每次都在线机上重新过滤依赖。我后来给好几台同批次机器装环境都是靠这样一份记录把单台安装时间从四个小时压缩到了四十分钟。说到底离线安装的“避坑”不光是踩了坑要会填更要把踩坑的经验沉淀成可复用的清单这才是工程化部署真正的价值。