麒麟ARM系统离线安装Qt环境全攻略：依赖处理与避坑指南

1. 麒麟ARM系统离线安装Qt环境的核心挑战与整体思路在国产化替代的大背景下银河麒麟操作系统搭配ARM架构处理器比如飞腾、鲲鹏等平台的软硬件组合越来越常见。很多做Qt开发的朋友从x86的Windows或Ubuntu环境迁移过来第一反应就是打开终端敲一句sudo apt install qt5-default结果发现要么源里根本没有对应的ARM包要么目标机器压根连不上外网。这时候“离线安装”就成了绕不开的坎。我自己在麒麟V10 SP1的飞腾FT-2000/4平台上完整走过一遍Qt 5.15.2的离线部署中间踩的坑比想象中多得多。这篇文章就把整个流程拆开揉碎讲清楚从怎么在联网机器上把依赖包扒全到怎么在离线机器上按正确顺序安装再到那些报错信息背后的真实原因。不管你是刚接触麒麟系统的新手还是已经用过一段时间但被依赖问题折磨过的老手应该都能从里面找到能直接抄作业的东西。核心难点其实就三个依赖关系复杂、ARM架构包源不统一、Qt自身模块拆分细。x86上装Qtapt自动帮你把依赖算好了离线环境下你得自己当那个“apt”把一棵依赖树完整地搬过去。而且ARM平台的deb包不像x86那么全有些包得从特定源或者特定版本的麒麟仓库里找。Qt本身又分qtbase、qtdeclarative、qtmultimedia等一大堆模块少一个就是“Unknown module in Qt: serialport”这种让人抓狂的报错。所以整体思路很明确先在联网的麒麟ARM机器上模拟安装用工具把完整依赖链导出来再打包搬到离线机器上按序安装。下面我分几个部分详细说。2. 离线安装前的环境确认与依赖包获取策略2.1 确认系统版本与架构信息动手之前先把目标机器的底细摸清楚这一步偷懒后面一定出问题。在离线机器上执行cat /etc/kylin-release uname -m dpkg --print-architecture麒麟V10 SP1的输出一般长这样Kylin Linux Advanced Server release V10 (Sword) aarch64 arm64注意uname -m返回的是aarch64而dpkg --print-architecture返回的是arm64这两个是同一个东西的不同叫法别被搞混了。后面找deb包的时候包名里带arm64的就是对的。还要确认一下系统的glibc版本因为Qt 5.15.2对glibc有最低要求ldd --version麒麟V10 SP1一般带的是glibc 2.28跑Qt 5.15.2没问题。如果你的是更老的麒麟版本比如V10早期版本glibc可能是2.17那就得考虑用Qt 5.12或者5.9了。提示一定要在联网机器和离线机器上分别执行上述命令确保两边系统版本和架构完全一致。我见过有人拿x86的包往ARM机器上装折腾半天才发现架构不对。2.2 联网机器上模拟安装并导出依赖找一台和离线机器系统版本、架构完全相同的联网麒麟ARM机器虚拟机也行在上面做依赖导出。核心工具是apt-get配合--print-uris参数或者用apt-offline这个专门做离线包管理的工具。我习惯用apt-get install --print-uris的方式因为它最直接# 先更新源索引 sudo apt-get update # 模拟安装Qt5核心开发包打印所有需要下载的包URI sudo apt-get install --print-uris -y qtbase5-dev qtdeclarative5-dev \ qtmultimedia5-dev libqt5serialport5-dev qtcreator | \ grep ^ | awk -F {print $2} qt_uris.txt这个命令会把所有需要下载的deb包URL列出来。但要注意--print-uris只列出直接依赖有些间接依赖可能不会全部显示。更稳妥的做法是用apt-get download配合apt-rdepends# 安装apt-rdepends工具 sudo apt-get install apt-rdepends # 递归列出所有依赖 apt-rdepends qtbase5-dev qtdeclarative5-dev qtmultimedia5-dev \ libqt5serialport5-dev qtcreator | grep -v ^ | sort -u qt_deps.txt然后根据这个列表逐个下载mkdir -p /tmp/qt_offline_packages cd /tmp/qt_offline_packages while read pkg; do apt-get download $pkg 2/dev/null done qt_deps.txt下载完成后目录里应该有一堆.deb文件。我实测下来Qt 5.15.2完整开发环境大概需要120到150个deb包总体积在800MB到1.2GB之间取决于你装多少模块。2.3 用apt-offline做更可靠的依赖收集如果你觉得手动递归依赖太麻烦apt-offline是更好的选择。它的工作方式是在离线机器上生成一个签名文件描述需要安装什么拿到联网机器上它会自动解析所有依赖并下载最后把包搬回离线机器安装。在离线机器上# 安装apt-offline如果离线机器上还没有需要先手动装这个工具的deb包 sudo apt-offline set --install-packages qtbase5-dev qtdeclarative5-dev \ qtmultimedia5-dev libqt5serialport5-dev qtcreator \ --update --upgrade /tmp/qt_offline.sig把/tmp/qt_offline.sig拷到联网机器上sudo apt-offline get /tmp/qt_offline.sig --bundle /tmp/qt_bundle.zip然后把qt_bundle.zip拷回离线机器sudo apt-offline install /tmp/qt_bundle.zip这种方式的好处是apt-offline会自动处理依赖关系和安装顺序省心很多。但前提是离线机器上得先有apt-offline本身这又是个鸡生蛋的问题。我的做法是先用apt-get download apt-offline在联网机器上下载这个工具的deb包手动装到离线机器上然后再用apt-offline做后续操作。注意apt-offline生成的签名文件里包含了系统当前的包状态信息所以联网机器和离线机器的系统版本必须一致否则解析出来的依赖可能对不上。3. Qt离线包的手动下载与依赖树梳理3.1 从麒麟官方源和Qt官方获取安装包麒麟V10的官方源里其实是有Qt5的包的但版本可能不是最新的5.15.2。你可以通过以下命令查看源里有哪些Qt相关包apt-cache search qt5 | grep -E ^(qtbase|qtdeclarative|qtmultimedia|libqt5)如果源里的版本满足需求直接用apt-offline的方式最省事。如果需要特定版本比如5.15.2而源里只有5.12那就得从Qt官方下载离线安装包。Qt官方从5.15开始不再提供独立的离线安装包下载链接需要商业账号但开源版本可以通过在线安装器qt-unified-linux-x64-online.run来安装。问题是这个安装器需要联网在离线ARM机器上跑不了。替代方案是直接从Qt的镜像站下载源码编译或者找第三方维护的ARM64 deb包。源码编译Qt 5.15.2在飞腾FT-2000/4上大概需要4到6个小时而且需要先装好一堆编译依赖cmake、ninja、gcc、g、libgl-dev等这些依赖本身也得离线搞定。我的建议是优先用麒麟官方源里的Qt版本。麒麟V10 SP1的源里Qt版本是5.12.8虽然比5.15.2老一点但胜在依赖完整、安装简单。如果项目确实需要5.15.2的特性再考虑源码编译。3.2 依赖树梳理与安装顺序规划不管用哪种方式获取包安装顺序都很关键。dpkg不会自动处理依赖你得手动按顺序装。基本原则是先装底层库再装上层应用先装被依赖的再装依赖别人的。可以用dpkg -I查看每个包的依赖信息dpkg -I qtbase5-dev_5.12.8dfsg-0kylin1_arm64.deb | grep Depends输出类似Depends: libqt5core5a ( 5.12.8dfsg-0kylin1), libqt5gui5 ( 5.12.8dfsg-0kylin1), ...根据依赖关系一个典型的安装顺序是这样的顺序包类别示例包名说明1基础C库libc6, libgcc1系统已有一般不用管2图形底层库libgl1, libegl1, libx11-6Qt GUI的基础3Qt核心库libqt5core5a, libqt5dbus5Qt运行时核心4Qt GUI库libqt5gui5, libqt5widgets5界面相关5Qt网络/多媒体libqt5network5, libqt5multimedia5功能模块6Qt开发包qtbase5-dev, qtdeclarative5-dev头文件和工具7Qt CreatorqtcreatorIDE可选实际操作中不用这么死板可以用一个循环脚本按字母顺序尝试安装失败的跳过多跑几轮直到全部装完cd /tmp/qt_offline_packages for i in $(seq 1 5); do echo Round $i for deb in *.deb; do sudo dpkg -i $deb 2/dev/null || true done done这个方法看起来笨但实测很有效。dpkg安装失败的包往往是因为依赖还没装下一轮再试就成功了。跑个三四轮基本能装完90%以上。3.3 处理“Unknown module in Qt: serialport”类报错这个报错太常见了单独拿出来说。出现这个提示说明你的Qt工程里用到了QT serialport但系统里没有安装对应的Qt SerialPort模块。在联网环境下sudo apt install libqt5serialport5-dev就解决了。离线环境下你需要确保下载了以下两个包libqt5serialport5_*.deb运行时库libqt5serialport5-dev_*.deb开发头文件和cmake配置装完之后还需要确认Qt的mkspecs目录里有对应的模块配置文件ls /usr/lib/aarch64-linux-gnu/qt5/mkspecs/modules/ | grep serialport应该能看到qt_lib_serialport.pri这个文件。如果没有说明dev包没装好qmake找不到模块定义。类似的还有Unknown module in Qt: multimedia、Unknown module in Qt: webengine等处理思路完全一样找到对应的libqt5模块名5-dev包离线安装即可。4. 离线安装实操全流程与关键步骤4.1 打包与传输离线包把联网机器上下载好的所有deb包打包cd /tmp tar czvf qt_offline_packages.tar.gz qt_offline_packages/如果包比较多可以分卷压缩方便传输tar czvf - qt_offline_packages/ | split -b 500M - qt_offline_part_传输方式根据实际环境选择U盘、移动硬盘、内网scp都行。传到离线机器后解压tar xzvf qt_offline_packages.tar.gz -C /tmp/4.2 批量安装与依赖修复进入解压后的目录先尝试一次性安装所有包cd /tmp/qt_offline_packages sudo dpkg -i *.deb大概率会看到一堆依赖错误。别慌这是正常的。接下来用apt-get install -f尝试自动修复sudo apt-get install -f但离线环境下apt-get找不到源这个命令会失败。所以还是得用前面说的循环dpkg的方式for round in 1 2 3 4 5; do echo Installation Round $round failed0 for deb in *.deb; do if ! sudo dpkg -i $deb /dev/null 21; then failed$((failed 1)) fi done echo Failed packages in this round: $failed if [ $failed -eq 0 ]; then echo All packages installed successfully! break fi done跑完之后检查一下还有哪些包没装好sudo dpkg -l | grep -E ^i[^i] | grep qtii表示正常安装iU表示解包但未配置iF表示配置失败。如果有iU或iF状态的包单独拿出来看报错sudo dpkg -i --force-all 问题包名.deb实操心得我遇到过libqt5core5a安装时报“trying to overwrite file that is also in package”的错误原因是系统里已经有一个旧版本的Qt库。解决办法是先卸载旧版本sudo dpkg -r --force-depends libqt5core5a再装新版本。但要注意卸载旧版本可能导致依赖它的其他程序暂时不可用最好在干净的系统上操作。4.3 配置Qt环境变量与验证安装包装完之后还需要配置环境变量让qmake和Qt Creator能找到正确的路径。编辑~/.bashrc或/etc/profile.d/qt.shexport QT_DIR/usr/lib/aarch64-linux-gnu/qt5 export PATH$QT_DIR/bin:$PATH export LD_LIBRARY_PATH$QT_DIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QT_DIR/plugins export QML2_IMPORT_PATH$QT_DIR/qml然后source一下source ~/.bashrc验证qmake是否可用qmake --version正常输出应该是QMake version 3.1 Using Qt version 5.12.8 in /usr/lib/aarch64-linux-gnu再验证一下Qt Creator能不能启动qtcreator --version如果报错说找不到某个库用ldd检查ldd $(which qtcreator) | grep not found把缺失的库对应的deb包找出来装上就行。4.4 编译一个测试工程验证环境完整性光看版本号还不够最好编译一个用到多个模块的小工程确认serialport、network、multimedia这些都能正常链接。创建一个测试目录mkdir -p ~/qt_test cd ~/qt_test写一个简单的.pro文件QT core gui widgets network serialport multimedia TARGET qt_test TEMPLATE app SOURCES main.cppmain.cpp内容#include QApplication #include QLabel #include QSerialPort #include QNetworkAccessManager #include QMediaPlayer int main(int argc, char *argv[]) { QApplication app(argc, argv); QSerialPort serial; QNetworkAccessManager manager; QMediaPlayer player; QLabel label(Qt offline install OK!); label.show(); return app.exec(); }编译qmake qt_test.pro make -j4如果一切顺利会生成qt_test可执行文件。运行一下./qt_test弹出一个窗口显示“Qt offline install OK!”说明环境完全正常。如果编译时报“Unknown module in Qt: serialport”回到3.3节检查serialport模块的安装情况。5. 常见问题排查与避坑经验实录5.1 依赖包版本冲突与降级处理麒麟系统的源里可能同时存在多个版本的Qt库比如系统预装了5.9你又装了5.12这时候容易出现版本冲突。典型报错是dpkg: error processing archive libqt5core5a_5.12.8_arm64.deb (--install): trying to overwrite /usr/lib/aarch64-linux-gnu/libQt5Core.so.5.12.8, which is also in package libqt5core5a 5.9.5解决办法有两种一是先卸载旧版本再装新版本二是用--force-overwrite强制覆盖。我推荐第一种更干净sudo dpkg -r --force-depends libqt5core5a libqt5gui5 libqt5widgets5 sudo dpkg -i libqt5core5a_5.12.8_arm64.deb libqt5gui5_5.12.8_arm64.deb ...但要注意卸载系统预装的Qt库可能导致依赖它的桌面组件出问题。操作前最好做个系统快照或者备份。5.2 qmake找不到模块的排查路径当你看到Unknown module(s) in QT: xxx时按以下顺序排查确认对应的dev包是否安装dpkg -l | grep libqt5xxx5-dev确认mkspecs模块文件是否存在ls /usr/lib/aarch64-linux-gnu/qt5/mkspecs/modules/ | grep xxx确认qmake的模块路径是否正确qmake -query QT_INSTALL_LIBS检查.pro文件里的模块名拼写是否正确比如是serialport不是serial_port常见模块与包名对照表Qt模块名运行时包开发包corelibqt5core5aqtbase5-devguilibqt5gui5qtbase5-devwidgetslibqt5widgets5qtbase5-devnetworklibqt5network5qtbase5-devserialportlibqt5serialport5libqt5serialport5-devmultimedialibqt5multimedia5qtmultimedia5-devsqllibqt5sql5qtbase5-devwebenginelibqt5webengine5qtwebengine5-dev5.3 图形界面相关库缺失导致Qt Creator无法启动Qt Creator在ARM麒麟上启动时可能报“cannot open shared object file: libxcb-xinerama.so.0”之类的错误。这是因为缺少X11相关的库。需要补装sudo dpkg -i libxcb-xinerama0_*.deb libxcb-icccm4_*.deb \ libxcb-image0_*.deb libxcb-keysyms1_*.deb libxcb-render-util0_*.deb \ libxcb-shape0_*.deb libxcb-xkb1_*.deb libxkbcommon-x11-0_*.deb这些包在麒麟源里都有用apt-offline一起下载就行。如果离线机器上完全没有图形环境纯命令行Qt Creator跑不起来但qmake和make可以正常工作编译命令行工程没问题。5.4 离线安装Qt Creator的插件依赖问题Qt Creator本身依赖一些插件比如libqt5svg5、libqt5help5等。如果只装了qtcreator主包而没装这些依赖启动时会报插件加载失败。建议把以下包一起下载libqt5svg5, libqt5svg5-devlibqt5help5, libqt5help5-devlibqt5clucene5libqt5designer5, libqt5designercomponents5qttools5-dev-tools这些包加起来大概200MB左右但能省去很多“为什么Qt Creator打不开”的排查时间。5.5 常见问题速查表问题现象可能原因解决方法Unknown module in Qt: serialport缺少libqt5serialport5-dev离线安装对应dev包qmake: command not foundqtbase5-dev-tools未安装安装qtbase5-dev-tools包Qt Creator启动报libxcb错误缺少X11相关库补装libxcb系列包dpkg依赖错误循环安装顺序不对用循环dpkg脚本多轮安装编译时报找不到QApplicationqtbase5-dev未装或qmake路径不对检查QT_DIR和PATH环境变量运行时找不到libQt5Core.so.5LD_LIBRARY_PATH未设置添加Qt库路径到LD_LIBRARY_PATH版本冲突overwrite错误系统已有旧版Qt先卸载旧版再装新版6. 离线环境下的持续开发与维护建议6.1 建立本地离线包仓库一次离线安装搞定之后建议把所有的deb包整理归档建一个本地仓库。以后需要装其他Qt模块或者重装系统时直接从这个仓库取包不用再从头下载。目录结构可以这样组织/opt/offline_repo/ ├── qt5/ │ ├── base/ │ ├── declarative/ │ ├── multimedia/ │ └── serialport/ ├── x11_deps/ ├── build_tools/ └── README.md在/etc/apt/sources.list.d/local.list里添加本地源deb [trustedyes] file:///opt/offline_repo ./然后sudo apt-get update之后就可以像在线一样用apt-get安装本地仓库里的包了。这个方式比手动dpkg优雅得多依赖关系apt会自动处理。6.2 用dpkg-scanpackages生成仓库索引本地仓库需要生成Packages索引文件apt才能识别。用dpkg-scanpackages工具cd /opt/offline_repo dpkg-scanpackages . /dev/null | gzip -9c Packages.gz如果提示找不到dpkg-scanpackages需要安装dpkg-dev包。这个工具在麒麟源里有提前下载好。生成索引后apt-get就能从本地源安装包了sudo apt-get install qtbase5-devapt会自动从本地仓库解析依赖并安装体验和在线几乎一样。6.3 版本升级与模块扩展的离线处理项目开发过程中可能需要新增Qt模块比如一开始没装webengine后来要用。这时候在联网机器上用同样的方法下载新模块及其依赖放到本地仓库重新生成索引然后在离线机器上apt-get install即可。如果是要升级Qt版本比如从5.12升到5.15建议先在测试环境验证兼容性。Qt 5.15和5.12在API层面基本兼容但有些废弃的接口被移除了编译时可能会报warning或error。升级前把项目里的.pro文件检查一遍把QT xxx里用不到的模块去掉减少依赖。个人体会离线环境最怕的不是装不上而是装了一半卡住不知道缺什么。我的经验是每次操作前先dpkg -l | grep qt before.txt操作后再导出一份after.txt用diff对比就能清楚看到哪些包装上了、哪些没装上。这个笨办法帮我省了很多排查时间。6.4 交叉编译环境的离线搭建思路有些场景下你需要在x86开发机上交叉编译ARM程序然后把可执行文件放到麒麟ARM机器上运行。这时候需要ARM交叉编译工具链和对应的Qt交叉编译版本。交叉编译工具链可以从麒麟官方或者Linaro获取下载对应的gcc-aarch64-linux-gnu包。Qt的交叉编译版本需要自己从源码编译配置时指定交叉编译器的路径./configure -prefix /opt/qt5-arm \ -xplatform linux-aarch64-gnu-g \ -no-opengl \ -nomake examples \ -nomake tests编译完成后把/opt/qt5-arm目录整体打包搬到离线机器上配置好环境变量就能用。交叉编译的Qt库和本机编译的Qt库可以共存通过QT_DIR环境变量切换。这个方案适合团队开发场景一台x86编译服务器负责编译多台ARM麒麟机器负责运行和测试。编译服务器需要联网下载工具链和源码运行机器完全离线。6.5 日常开发中的依赖管理习惯最后分享几个我在离线麒麟环境下养成的习惯能省不少事每次装新包之前先dpkg -l | grep 包名确认是否已安装避免重复安装导致冲突把常用的deb包按功能分类存放比如qt_base、qt_extra、x11_libs、build_tools找起来快在本地仓库的README里记录每个包的版本和用途时间长了容易忘定期用dpkg --audit检查系统里有没有半安装状态的包及时清理如果条件允许在虚拟机里保留一个和离线机器同版本的麒麟ARM环境用来做安装测试这套流程我在三个不同的麒麟ARM项目里都用过从FT-2000/4到鲲鹏920基本都能顺利跑通。唯一需要根据实际情况调整的是Qt版本和具体模块列表核心方法是一样的。