2026/9/1 9:01:18
FEATURED · 精选文章 
简介面向银河麒麟ARM64平台上的Qt应用开发者这份Qt5.14.2产物提供了完整的C头文件集解决了在国产操作系统上编译Qt程序时缺少接口声明的痛点。资源共2000个文件其中1991个为.h头文件覆盖QtCore、QtGui、QtWidgets、QtNetwork、QtWebEngine等主要模块9个txt说明文件可用于快速了解模块划分与版本信息整个压缩包480.02MB适合作为离线参考或构建依赖。已有720人学习下载对于正从x86向ARM64迁移的企业级项目很有参考价值。解压后可直接将头文件路径加入工程配合对应版本的Qt库即可完成源码编译与调试其中还包含QtWebEngine、QtOpenGL、Qt3D等扩展模块头文件便于在麒麟系统中集成现代Web渲染能力和3D图形界面有效缩短国产化适配周期。 前段时间接了一个适配交付的活一个用Qt5.14.2开发的桌面应用要跑在银河麒麟V10ARM64的机器上。刚接到需求的时候我下意识觉得这事不大——Qt本身就是跨平台的重新编译一下再拷贝过去不就完了实际做下来才发现架构迁移、系统差异、依赖库、图形插件、输入法中文字体每一个环节都可能让程序在那边无声无息地挂掉。这篇文章就把我从编译到部署再到排障的完整过程梳理一遍重点讲ARM64麒麟环境下的环境搭建、Qt产物部署方式以及几个坑的定位思路。如果你也正在做Qt应用往麒麟系统的迁移或者手头有x86编译好的Qt程序要跑到ARM64设备上看完这篇应该能少走不少弯路。1. 这套组合到底在解决什么问题先别急着敲命令想清楚场景。Qt5.14.2是很多现存项目在用的稳定版本尤其是在工业、嵌入式、办公软件这几个领域5.14.2属于改了没好处、不改也够用的保守选择。银河麒麟V10则是现阶段大量终端设备预装的操作系统飞腾、鲲鹏这类ARM64处理器在整机里非常常见。把两者放一起就是典型的老工程跑新平台的迁移场景。这个场景里有三层挑战架构差异x86的二进制不能直接跑在ARM64上必须重新编译。这一点大家都有共识但容易忽略的是——不仅主程序要重编所有依赖的第三方动态库也得是ARM64版本包括Qt自身的库。系统差异银河麒麟V10虽然基于Debian/Ubuntu系但还是有一些自带组件的路径、版本跟标准Ubuntu不完全一致。尤其是桌面环境、显示服务、输入法框架细节处理不好程序会活着但没界面。交付方式差异在x86开发机上我们习惯直接把编译出来的可执行文件发过去依赖动态库都不打全靠目标机自己去撞。但在ARM64嵌入式或专用终端上环境更干净缺库是常态不带库过去往往就是直接崩。这三个问题决定了后面的所有步骤。我在实际项目里的做法是先搭一套能用的编译环境再编译出ARM64产物最后把运行所需的最小依赖集合整明白一起交付。下面按这个顺序展开。1.1 我对Qt5.14.2的看法Qt5.14.2是Qt5时代比较稳的一个版本。它没有Qt6那么新的架构变化但LTS风格的支持让它在4K屏、XCB、Wayland等基础能力上表现都够用。从兼容性角度讲5.14.2和5.12的代码迁移成本很低很多老工程只要改改.pro文件里的模块名就能编译过。如果你的工程恰好也是5.14.x系列那这套适配思路可以直接照用。1.2 我对银河麒麟ARM64环境的判断银河麒麟V10目前常见的版本是基于Ubuntu的所以APT生态基本无缝。这个点很关键意味着大部分依赖库可以直接apt装不用从源码造轮子。ARM64架构本身在Linux生态里也早就不是稀罕事镜像源里的二进制包都有aarch64版本。真正让人头疼的往往不是装不上而是装错版本或者装漏了某个小库。2. 动手前先确认三件事架构、系统、Qt来源到了目标机器上我习惯先跑三条命令把底细摸清楚uname -m cat /etc/os-release lscpu | grep Architectureuname -m输出aarch64说明就是ARM64/etc/os-release里能看到系统版本号lscpu能看到更详细的CPU型号。这三条命令加起来用不了10秒但能帮你确认两件事能不能用APT装软件基于Ubuntu就能用以及下载第三方二进制时该选哪个架构aarch64还是arm64叫法不同指代一样。这套确认做完接着就要决定Qt5.14.2从哪里来。我总结了三条路各有适用场景获取方式优点缺点适用场景APT仓库直接安装方便、依赖自动解决版本可能不是5.14.2工程没用特殊模块、不卡版本Qt官方ARM64安装包版本精确、组件可选下载慢、可能要注册需要精确匹配Qt版本源码编译完全可控、可裁剪耗时长、依赖多对Qt版本有强锁定要求的产线我在这次项目里选了APT路线原因很简单目标机的系统仓库里有5.12.5虽然不是5.14.2但工程编译下来没有遇到不兼容的地方。如果你遇到系统仓库的Qt版本跟开发机不一致这情况先别慌试试把工程在系统Qt版本下编译一遍。大多数只用了Widgets、Network、Sql模块的应用都能直接编译过连.pro都不用改。2.1 怎么看系统里是否已经有Qt有时候目标机出厂时已经预置了Qt库但版本很旧或只装了运行时没装开发包。可以用下面命令检查qmake --version dpkg -l | grep qt5如果qmake找不到先sudo apt install qtbase5-dev把开发包装上。如果qtbase5-dev已经装过但版本不对我个人不建议强行改系统Qt版本——那会牵连系统其它组件。更好的做法是装一个独立的Qt到/opt下然后通过 PATH 和 CMAKE_PREFIX_PATH 隔离使用。3. 编译产物生成推荐apt路线除非你对版本有强迫症确认完环境接下来就是在开发机上把工程编译成ARM64可执行文件。这里有个前提要想清楚你开发机本身是不是ARM64机器如果是直接本地编译即可如果不是就必须用交叉编译工具链。现实里很多团队手里只有x86开发机目标机是ARM64麒麟这两者的配合方式我单独说。3.1 直接在ARM64机器上原生编译如果手里有ARM64的开发机最省事的做法是直接在机器上装好Qt开发环境然后编译。sudo apt update sudo apt install build-essential qtbase5-dev qtbase5-dev-tools然后进入工程目录mkdir build cd build qmake ../your_project.pro make -j$(nproc)编译完后用file看一眼产物file your_app # 期望输出ELF 64-bit LSB executable, ARM aarch64, ...看到aarch64就说明批次对了。这里有个经验编译时最好再加个-j2限制一下因为ARM64机器有时内存不大全核心并行编译容易把内存耗尽。宁可编译慢10分钟也别让机器在链接阶段OOM。3.2 交叉编译没有ARM64开发机时的备选如果手上全是x86开发机那就只能用交叉编译工具链。银河麒麟ARM64的交叉编译链是aarch64-linux-gnu-gcc在x86的Linux上可以直接装sudo apt install gcc-aarch64-linux-gnu g-aarch64-linux-gnuQt工程交叉编译时需要一份ARM64版本的Qt库。安装路径建议选/opt/qt-aarch64。编译时在.pro或 CMakeLists 里指定交叉编译器QMAKE_CC aarch64-linux-gnu-gcc QMAKE_CXX aarch64-linux-gnu-g QMAKE_LINK aarch64-linux-gnu-g交叉编译最大的坑在于依赖库如果你的工程依赖第三方库如OpenSSL、SQLite这些库也必须提供ARM64版本。很多工程就是这一步被卡住的——依赖库在ARM64上没有现成的二进制包还得自己交叉编译。所以我的建议很直接只要项目不是只交付一次就配一台ARM64的编译机器别在交叉编译里耗。3.3 编译常见错误与处理编译阶段最常遇到的报错有两类找不到头文件比如fatal error: QNetworkAccessManager: No such file or directory。这是缺某个Qt模块的开发包对应补装即可比如sudo apt install libqt5network5或qtdeclarative5-dev。链接失败ld returned 1 exit status。大概率是库版本不一致或者qmake缓存没清干净。删掉build目录重新来一遍比反复make干净得多。还有一个容易忽略的.pro文件里如果写了类似windows { ... }的分平台条件跨平台编译时要注意这些分支是否干扰了Linux路径。我见过一个工程里unix:!macx后面跟了一串Windows库路径结果在Linux上编译直接报找不到库文件。4. 部署是把双刃剑库依赖与运行环境编译只是第一步真正让多少人在深夜崩溃的是部署环节。Qt程序的部署任务可以概括为让目标机器上找不到的东西全都找得到。4.1 用ldd扫描依赖拿到ARM64可执行文件后先把依赖库列表导出来ldd your_app | tee ldd_deploy.txt重点看两行一行是输出里带not found的直接缺失另一行是Qt库的路径要判断你依赖的是系统装的那套Qt还是自带的隔离Qt。如果not found很多说明目标机缺基础库可以先在目标机上把通用依赖补齐sudo apt install libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-image0 libxcb-shm0 libxcb-render-util0 libegl1 libgl1-mesa-glx这套 XCB 相关的库是Qt xcb平台插件在桌面上运行的地基。很多人遇到could not find or load the Qt platform plugin xcb就是这个环节出了问题。4.2 关于Qt库的两种分发方式如果你用的是系统Qt目标机器上的运行时依赖大概率已经在了部署时只要保证目标机器的Qt版本和开发机上一致。如果你像我这次一样开发机Qt版本和目标机系统仓库版本不同那就要么在目标机上再装一份5.14.2要么干脆把开发机编译时使用的Qt库整个打包带过去用LD_LIBRARY_PATH隔离。我这次选了后者理由很简单目标机上装第二套Qt容易污染系统环境一旦多个应用依赖不同Qt版本互相干扰起来很难查。打包Qt库的方式是在开发机上找到Qt安装目录下lib里的libQt5Core.so.5、libQt5Gui.so.5、libQt5Widgets.so.5等核心库把lib/和plugins/platforms/两个目录一起拷贝到目标机的/opt/your_app_qt/下在启动脚本里用LD_LIBRARY_PATH和QT_QPA_PLATFORM_PLUGIN_PATH指过去。这样目标机系统就算完全不认识Qt你的程序也能独立跑起来。代价是打包体积大一点——几个so加起来约30到50MB但换来的隔离性很值。4.3 启动脚本是终极大法终端里手动执行没问题不代表桌面双击也能跑。Qt程序交付给用户最稳的还是提供一个启动脚本#!/bin/bash # run_qt_app.sh BASEDIR$(dirname $0) export LD_LIBRARY_PATH$BASEDIR/qt/lib:$LD_LIBRARY_PATH export QT_QPA_PLATFORMxcb export QT_QPA_PLATFORM_PLUGIN_PATH$BASEDIR/qt/plugins/platforms export QT_QPA_FONTDIR/usr/share/fonts exec $BASEDIR/your_app $注意BASEDIR$(dirname $0)这个技巧它可以让你把整个应用目录随便挪位置脚本永远能找到自己所在目录下的运行时。这是很多新手容易漏的一环——写死绝对路径换个目录就崩。脚本记得chmod x run_qt_app.sh不然双击还是起不来。5. 从双击没反应到稳定运行的排查记录部署完第一次双击大概率不会一帆风顺。我把自己真实遇到的排查过程梳理成一条链路你可以照着走一遍。5.1 第一步确认进程是否活着双击没反应先看进程ps aux | grep your_app如果进程存在说明程序启动了问题在窗口显示。如果进程不存在说明程序启动就退出了接下来去终端跑一次故障信息基本都会打到终端上。5.2 第二步终端运行看错误输出cd /opt/your_app_qt ./run_qt_app.sh常见输出和对应的解决方向报错信息原因解决could not find or load the Qt platform plugin xcbplugins/platforms 路径不对设置QT_QPA_PLATFORM_PLUGIN_PATH指向实际目录error while loading shared libraries: libQt5Core.so.5LD_LIBRARY_PATH 没生效检查启动脚本里的库路径qt.qpa.xcb: could not connect to displayDISPLAY 环境变量为空export DISPLAY:0确认X服务在跑QFontDatabase: Cannot find font directory字体目录找不到设置QT_QPA_FONTDIR/usr/share/fonts5.3 第三步字体乱码和输入法问题程序跑起来之后最容易翻车的是中文字体。麒麟系统虽然自带一些字体但如果版本比较精简中文字体可能缺失界面上全是方块。优先装字体sudo apt install fonts-noto-cjk fonts-wqy-microhei输入法的问题也不少。Qt5.14.2配合麒麟自带的fcitx4通常没问题但如果系统换了fcitx5会出现能打字但不进输入框或者光标闪烁但无输入的情况。解决方向是确认QT_IM_MODULEexport QT_IM_MODULEfcitx或者反其道行之临时把输入法模块设为空看是不是它在捣乱export QT_IM_MODULE5.4 第四步黑屏、花屏、GPU相关如果界面出来但黑屏或闪烁常见原因是图形渲染和GPU驱动适配问题。在ARM64麒麟上GPU驱动不一定完美。可以先试着强制使用软件渲染export QT_OPENGLsoftware export LIBGL_ALWAYS_SOFTWARE1如果还不行把QPA插件从xcb换到offscreen验证一下程序逻辑是否正常offscreen不显示窗口但能证明程序没崩QT_QPA_PLATFORMoffscreen ./your_app桌面环境下不建议一上来就用linuxfb或eglfs这两个插件是为嵌入式场景设计的在桌面会缺失鼠标、窗口管理等一系列能力。同理如果遇到程序启动后界面卡在某个画面不动也建议先软渲染排查别急着怀疑业务代码。6. 几个值得记住的取舍最后说几个我自己的判断不一定适合所有项目但可以给你参考。第一要不要为了5.14.2这个精确版本去折腾源码编译我的答案是大可不必除非你的工程依赖了Qt 5.14.2某个独有的行为或者补丁。对绝大多数应用来说系统仓库里的Qt都能编译运行。版本号爱好者在团队协作里通常只会带来更多麻烦。第二交叉编译还是原生编译如果你需要长期在这个平台上迭代建议配一台ARM64开发机做原生编译。交叉编译省了硬件成本但每次调依赖库都是一场持久战。短期交付一个产物的话交叉编译可以长期项目原生编译省心太多。第三部署时到底是打全依赖还是靠系统库如果目标机器环境干净、可控最好把运行所需的最小依赖库一起带走。如果目标机器是一个通用桌面环境则优先用系统自带的Qt和XCB组件少带库、少冲突。最后一个小技巧交付前一定要在干净的虚拟机里验证一遍。有些问题只有在全新环境里才会暴露出来比如漏带某个so、路径写死、权限不对。我带过一次漏了libQt5DBus.so.5在开发机上一切正常交付到目标机之后才发现——跑起来就崩查了大半个下午。从那以后交付前先虚拟机走一遍成了我的固定动作。这些细节才是Qt应用在麒麟ARM64上真正稳的关键。本文还有配套的精品资源点击获取
Qt5.14.2应用迁移至银河麒麟ARM64：编译、部署与排障全指南
简介面向银河麒麟ARM64平台上的Qt应用开发者这份Qt5.14.2产物提供了完整的C头文件集解决了在国产操作系统上编译Qt程序时缺少接口声明的痛点。资源共2000个文件其中1991个为.h头文件覆盖QtCore、QtGui、QtWidgets、QtNetwork、QtWebEngine等主要模块9个txt说明文件可用于快速了解模块划分与版本信息整个压缩包480.02MB适合作为离线参考或构建依赖。已有720人学习下载对于正从x86向ARM64迁移的企业级项目很有参考价值。解压后可直接将头文件路径加入工程配合对应版本的Qt库即可完成源码编译与调试其中还包含QtWebEngine、QtOpenGL、Qt3D等扩展模块头文件便于在麒麟系统中集成现代Web渲染能力和3D图形界面有效缩短国产化适配周期。 前段时间接了一个适配交付的活一个用Qt5.14.2开发的桌面应用要跑在银河麒麟V10ARM64的机器上。刚接到需求的时候我下意识觉得这事不大——Qt本身就是跨平台的重新编译一下再拷贝过去不就完了实际做下来才发现架构迁移、系统差异、依赖库、图形插件、输入法中文字体每一个环节都可能让程序在那边无声无息地挂掉。这篇文章就把我从编译到部署再到排障的完整过程梳理一遍重点讲ARM64麒麟环境下的环境搭建、Qt产物部署方式以及几个坑的定位思路。如果你也正在做Qt应用往麒麟系统的迁移或者手头有x86编译好的Qt程序要跑到ARM64设备上看完这篇应该能少走不少弯路。1. 这套组合到底在解决什么问题先别急着敲命令想清楚场景。Qt5.14.2是很多现存项目在用的稳定版本尤其是在工业、嵌入式、办公软件这几个领域5.14.2属于改了没好处、不改也够用的保守选择。银河麒麟V10则是现阶段大量终端设备预装的操作系统飞腾、鲲鹏这类ARM64处理器在整机里非常常见。把两者放一起就是典型的老工程跑新平台的迁移场景。这个场景里有三层挑战架构差异x86的二进制不能直接跑在ARM64上必须重新编译。这一点大家都有共识但容易忽略的是——不仅主程序要重编所有依赖的第三方动态库也得是ARM64版本包括Qt自身的库。系统差异银河麒麟V10虽然基于Debian/Ubuntu系但还是有一些自带组件的路径、版本跟标准Ubuntu不完全一致。尤其是桌面环境、显示服务、输入法框架细节处理不好程序会活着但没界面。交付方式差异在x86开发机上我们习惯直接把编译出来的可执行文件发过去依赖动态库都不打全靠目标机自己去撞。但在ARM64嵌入式或专用终端上环境更干净缺库是常态不带库过去往往就是直接崩。这三个问题决定了后面的所有步骤。我在实际项目里的做法是先搭一套能用的编译环境再编译出ARM64产物最后把运行所需的最小依赖集合整明白一起交付。下面按这个顺序展开。1.1 我对Qt5.14.2的看法Qt5.14.2是Qt5时代比较稳的一个版本。它没有Qt6那么新的架构变化但LTS风格的支持让它在4K屏、XCB、Wayland等基础能力上表现都够用。从兼容性角度讲5.14.2和5.12的代码迁移成本很低很多老工程只要改改.pro文件里的模块名就能编译过。如果你的工程恰好也是5.14.x系列那这套适配思路可以直接照用。1.2 我对银河麒麟ARM64环境的判断银河麒麟V10目前常见的版本是基于Ubuntu的所以APT生态基本无缝。这个点很关键意味着大部分依赖库可以直接apt装不用从源码造轮子。ARM64架构本身在Linux生态里也早就不是稀罕事镜像源里的二进制包都有aarch64版本。真正让人头疼的往往不是装不上而是装错版本或者装漏了某个小库。2. 动手前先确认三件事架构、系统、Qt来源到了目标机器上我习惯先跑三条命令把底细摸清楚uname -m cat /etc/os-release lscpu | grep Architectureuname -m输出aarch64说明就是ARM64/etc/os-release里能看到系统版本号lscpu能看到更详细的CPU型号。这三条命令加起来用不了10秒但能帮你确认两件事能不能用APT装软件基于Ubuntu就能用以及下载第三方二进制时该选哪个架构aarch64还是arm64叫法不同指代一样。这套确认做完接着就要决定Qt5.14.2从哪里来。我总结了三条路各有适用场景获取方式优点缺点适用场景APT仓库直接安装方便、依赖自动解决版本可能不是5.14.2工程没用特殊模块、不卡版本Qt官方ARM64安装包版本精确、组件可选下载慢、可能要注册需要精确匹配Qt版本源码编译完全可控、可裁剪耗时长、依赖多对Qt版本有强锁定要求的产线我在这次项目里选了APT路线原因很简单目标机的系统仓库里有5.12.5虽然不是5.14.2但工程编译下来没有遇到不兼容的地方。如果你遇到系统仓库的Qt版本跟开发机不一致这情况先别慌试试把工程在系统Qt版本下编译一遍。大多数只用了Widgets、Network、Sql模块的应用都能直接编译过连.pro都不用改。2.1 怎么看系统里是否已经有Qt有时候目标机出厂时已经预置了Qt库但版本很旧或只装了运行时没装开发包。可以用下面命令检查qmake --version dpkg -l | grep qt5如果qmake找不到先sudo apt install qtbase5-dev把开发包装上。如果qtbase5-dev已经装过但版本不对我个人不建议强行改系统Qt版本——那会牵连系统其它组件。更好的做法是装一个独立的Qt到/opt下然后通过 PATH 和 CMAKE_PREFIX_PATH 隔离使用。3. 编译产物生成推荐apt路线除非你对版本有强迫症确认完环境接下来就是在开发机上把工程编译成ARM64可执行文件。这里有个前提要想清楚你开发机本身是不是ARM64机器如果是直接本地编译即可如果不是就必须用交叉编译工具链。现实里很多团队手里只有x86开发机目标机是ARM64麒麟这两者的配合方式我单独说。3.1 直接在ARM64机器上原生编译如果手里有ARM64的开发机最省事的做法是直接在机器上装好Qt开发环境然后编译。sudo apt update sudo apt install build-essential qtbase5-dev qtbase5-dev-tools然后进入工程目录mkdir build cd build qmake ../your_project.pro make -j$(nproc)编译完后用file看一眼产物file your_app # 期望输出ELF 64-bit LSB executable, ARM aarch64, ...看到aarch64就说明批次对了。这里有个经验编译时最好再加个-j2限制一下因为ARM64机器有时内存不大全核心并行编译容易把内存耗尽。宁可编译慢10分钟也别让机器在链接阶段OOM。3.2 交叉编译没有ARM64开发机时的备选如果手上全是x86开发机那就只能用交叉编译工具链。银河麒麟ARM64的交叉编译链是aarch64-linux-gnu-gcc在x86的Linux上可以直接装sudo apt install gcc-aarch64-linux-gnu g-aarch64-linux-gnuQt工程交叉编译时需要一份ARM64版本的Qt库。安装路径建议选/opt/qt-aarch64。编译时在.pro或 CMakeLists 里指定交叉编译器QMAKE_CC aarch64-linux-gnu-gcc QMAKE_CXX aarch64-linux-gnu-g QMAKE_LINK aarch64-linux-gnu-g交叉编译最大的坑在于依赖库如果你的工程依赖第三方库如OpenSSL、SQLite这些库也必须提供ARM64版本。很多工程就是这一步被卡住的——依赖库在ARM64上没有现成的二进制包还得自己交叉编译。所以我的建议很直接只要项目不是只交付一次就配一台ARM64的编译机器别在交叉编译里耗。3.3 编译常见错误与处理编译阶段最常遇到的报错有两类找不到头文件比如fatal error: QNetworkAccessManager: No such file or directory。这是缺某个Qt模块的开发包对应补装即可比如sudo apt install libqt5network5或qtdeclarative5-dev。链接失败ld returned 1 exit status。大概率是库版本不一致或者qmake缓存没清干净。删掉build目录重新来一遍比反复make干净得多。还有一个容易忽略的.pro文件里如果写了类似windows { ... }的分平台条件跨平台编译时要注意这些分支是否干扰了Linux路径。我见过一个工程里unix:!macx后面跟了一串Windows库路径结果在Linux上编译直接报找不到库文件。4. 部署是把双刃剑库依赖与运行环境编译只是第一步真正让多少人在深夜崩溃的是部署环节。Qt程序的部署任务可以概括为让目标机器上找不到的东西全都找得到。4.1 用ldd扫描依赖拿到ARM64可执行文件后先把依赖库列表导出来ldd your_app | tee ldd_deploy.txt重点看两行一行是输出里带not found的直接缺失另一行是Qt库的路径要判断你依赖的是系统装的那套Qt还是自带的隔离Qt。如果not found很多说明目标机缺基础库可以先在目标机上把通用依赖补齐sudo apt install libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-image0 libxcb-shm0 libxcb-render-util0 libegl1 libgl1-mesa-glx这套 XCB 相关的库是Qt xcb平台插件在桌面上运行的地基。很多人遇到could not find or load the Qt platform plugin xcb就是这个环节出了问题。4.2 关于Qt库的两种分发方式如果你用的是系统Qt目标机器上的运行时依赖大概率已经在了部署时只要保证目标机器的Qt版本和开发机上一致。如果你像我这次一样开发机Qt版本和目标机系统仓库版本不同那就要么在目标机上再装一份5.14.2要么干脆把开发机编译时使用的Qt库整个打包带过去用LD_LIBRARY_PATH隔离。我这次选了后者理由很简单目标机上装第二套Qt容易污染系统环境一旦多个应用依赖不同Qt版本互相干扰起来很难查。打包Qt库的方式是在开发机上找到Qt安装目录下lib里的libQt5Core.so.5、libQt5Gui.so.5、libQt5Widgets.so.5等核心库把lib/和plugins/platforms/两个目录一起拷贝到目标机的/opt/your_app_qt/下在启动脚本里用LD_LIBRARY_PATH和QT_QPA_PLATFORM_PLUGIN_PATH指过去。这样目标机系统就算完全不认识Qt你的程序也能独立跑起来。代价是打包体积大一点——几个so加起来约30到50MB但换来的隔离性很值。4.3 启动脚本是终极大法终端里手动执行没问题不代表桌面双击也能跑。Qt程序交付给用户最稳的还是提供一个启动脚本#!/bin/bash # run_qt_app.sh BASEDIR$(dirname $0) export LD_LIBRARY_PATH$BASEDIR/qt/lib:$LD_LIBRARY_PATH export QT_QPA_PLATFORMxcb export QT_QPA_PLATFORM_PLUGIN_PATH$BASEDIR/qt/plugins/platforms export QT_QPA_FONTDIR/usr/share/fonts exec $BASEDIR/your_app $注意BASEDIR$(dirname $0)这个技巧它可以让你把整个应用目录随便挪位置脚本永远能找到自己所在目录下的运行时。这是很多新手容易漏的一环——写死绝对路径换个目录就崩。脚本记得chmod x run_qt_app.sh不然双击还是起不来。5. 从双击没反应到稳定运行的排查记录部署完第一次双击大概率不会一帆风顺。我把自己真实遇到的排查过程梳理成一条链路你可以照着走一遍。5.1 第一步确认进程是否活着双击没反应先看进程ps aux | grep your_app如果进程存在说明程序启动了问题在窗口显示。如果进程不存在说明程序启动就退出了接下来去终端跑一次故障信息基本都会打到终端上。5.2 第二步终端运行看错误输出cd /opt/your_app_qt ./run_qt_app.sh常见输出和对应的解决方向报错信息原因解决could not find or load the Qt platform plugin xcbplugins/platforms 路径不对设置QT_QPA_PLATFORM_PLUGIN_PATH指向实际目录error while loading shared libraries: libQt5Core.so.5LD_LIBRARY_PATH 没生效检查启动脚本里的库路径qt.qpa.xcb: could not connect to displayDISPLAY 环境变量为空export DISPLAY:0确认X服务在跑QFontDatabase: Cannot find font directory字体目录找不到设置QT_QPA_FONTDIR/usr/share/fonts5.3 第三步字体乱码和输入法问题程序跑起来之后最容易翻车的是中文字体。麒麟系统虽然自带一些字体但如果版本比较精简中文字体可能缺失界面上全是方块。优先装字体sudo apt install fonts-noto-cjk fonts-wqy-microhei输入法的问题也不少。Qt5.14.2配合麒麟自带的fcitx4通常没问题但如果系统换了fcitx5会出现能打字但不进输入框或者光标闪烁但无输入的情况。解决方向是确认QT_IM_MODULEexport QT_IM_MODULEfcitx或者反其道行之临时把输入法模块设为空看是不是它在捣乱export QT_IM_MODULE5.4 第四步黑屏、花屏、GPU相关如果界面出来但黑屏或闪烁常见原因是图形渲染和GPU驱动适配问题。在ARM64麒麟上GPU驱动不一定完美。可以先试着强制使用软件渲染export QT_OPENGLsoftware export LIBGL_ALWAYS_SOFTWARE1如果还不行把QPA插件从xcb换到offscreen验证一下程序逻辑是否正常offscreen不显示窗口但能证明程序没崩QT_QPA_PLATFORMoffscreen ./your_app桌面环境下不建议一上来就用linuxfb或eglfs这两个插件是为嵌入式场景设计的在桌面会缺失鼠标、窗口管理等一系列能力。同理如果遇到程序启动后界面卡在某个画面不动也建议先软渲染排查别急着怀疑业务代码。6. 几个值得记住的取舍最后说几个我自己的判断不一定适合所有项目但可以给你参考。第一要不要为了5.14.2这个精确版本去折腾源码编译我的答案是大可不必除非你的工程依赖了Qt 5.14.2某个独有的行为或者补丁。对绝大多数应用来说系统仓库里的Qt都能编译运行。版本号爱好者在团队协作里通常只会带来更多麻烦。第二交叉编译还是原生编译如果你需要长期在这个平台上迭代建议配一台ARM64开发机做原生编译。交叉编译省了硬件成本但每次调依赖库都是一场持久战。短期交付一个产物的话交叉编译可以长期项目原生编译省心太多。第三部署时到底是打全依赖还是靠系统库如果目标机器环境干净、可控最好把运行所需的最小依赖库一起带走。如果目标机器是一个通用桌面环境则优先用系统自带的Qt和XCB组件少带库、少冲突。最后一个小技巧交付前一定要在干净的虚拟机里验证一遍。有些问题只有在全新环境里才会暴露出来比如漏带某个so、路径写死、权限不对。我带过一次漏了libQt5DBus.so.5在开发机上一切正常交付到目标机之后才发现——跑起来就崩查了大半个下午。从那以后交付前先虚拟机走一遍成了我的固定动作。这些细节才是Qt应用在麒麟ARM64上真正稳的关键。本文还有配套的精品资源点击获取 
ClamAV 并配置邮件告警操作指南)
