简介Qt5.14.2产物-银河麒麟-ARM64 是一套面向国产银河麒麟操作系统ARM64 架构的 Qt5.14.2 开发头文件包主要解决 Qt 在信创/国产化环境下重新编译耗时、依赖难配置的问题适合需要在麒麟系统上原生编译 Qt 应用、集成 QtWebEngineChromium 内核或使用 QML/Quick 构建界面的中高级开发者。压缩包共 2000 个文件包含 1991 个 C/C 头文件和 9 个 txt 说明覆盖 OpenGL、网络、GUI、Qt3D、QtQuickControls、QtWebEngine 等模块的接口声明整体约 480MB可直接引入工程作为离线头文件库免去从源码交叉编译的繁琐步骤还能辅助排查缺少头文件导致的编译错误。资源已有 720 人学习下载借助 Qt5.14.2 在 QML 性能、HTTP/2、Unicode 12.1 等方面的增强开发者可在银河麒麟上打造体验更流畅、网络通信效率更高的应用QtWebEngine 相关头文件支持应用内基于 Chromium 呈现现代网页满足复杂交互需求。对需要深入理解 Qt 类层次或定制模块的工程师这份头文件集合也是一份便于检索的代码级参考资料。 最近在搞一个Qt应用的国产化适配应用本身是公司内部的工业数据采集工具用Qt5.14.2写了不少年头界面、网络、数据库模块全在里面。客户那边要求跑在银河麒麟V10 SP1系统上CPU是飞腾D2000ARM64架构。最开始我把x86 Ubuntu上编译好的程序直接拷过去结果就是文件格式不识别——这倒不算意外但后面的麻烦才刚开始要在ARM64上重新编译Qt5.14.2、补齐各种依赖库、处理平台插件最后让程序在麒麟桌面上稳稳跑起来每一步都有坑要踩。这篇博文就把我整个实操过程记录下来从编译Qt5.14.2到部署应用再到常见问题排查给同样在做Qt跨平台适配、尤其是面向国产化平台的兄弟一个参考。1. 背景与整体思路1.1 为什么是Qt5.14.2这个版本项目从2019年就用Qt了期间一直锁在5.14系列。5.14.2是5.14分支的最后一个补丁版本修复了一批内存和渲染方面的老问题对旧代码的兼容性比5.15还稳。5.15虽然是LTS但商用用官方安装包要许可团队也不想折腾Qt6对老工程改动太大QWidget和QML代码一套翻下来成本太高。所以Qt5.14.2在信创项目里非常常见很多团队拿到的基线就是这个版本。从编译角度看5.14.2对编译器版本的要求相对宽松银河麒麟V10系统自带的GCC版本一般是9.x就能直接编译过不需要额外升级工具链。这个特性在实际项目里很关键因为国产平台上有时候升级工具链比编译Qt本身还麻烦。1.2 麒麟V10和ARM64架构的前置认知银河麒麟V10是目前国产化环境里装机量很大的系统不是简单套壳Linux。桌面版基于Debian系自带apt包管理工具服务器版有yum仓库。我客户这台机器是飞腾D2000aarch64架构所以装的是ARM64版本的麒麟桌面系统。这里必须提醒一句部署任何软件前先确认架构不要看系统属性里写了个64位就以为通吃。终端执行uname -m输出aarch64就是ARM64输出x86_64是Intel/AMD的64位。这两个指令集完全不通用二进制格式不识别后面所有编译、拷贝、打包都围绕架构来选型。网上经常看到有人问银河麒麟怎么安装软件、软件包用什么命令其实和Ubuntu基本一致apt或yum就能搞定。真正麻烦的是架构和依赖这两件事包管理器反而不是重点。1.3 部署方案的取舍做ARM64平台适配摆在我面前的常规路径有三条直接拿x86二进制显然不行、交叉编译、在目标机上源码编译。我最终选了第三条在真机上源码编译Qt再用这个Qt编译应用。交叉编译看起来省时间实际坑很多。Qt的交叉编译环境要自己搭sysroot里的库版本必须和目标机严格一致否则编译出来的程序跑到客户机器上冒出一个GLIBC_2.28 not found就够折腾好几天。我在这个项目里果断放弃交叉编译因为有现成ARM64真机直接编译虽然耗时但最稳妥依赖天然匹配。方案优点缺点适用场景直接用x86产物完全不折腾ARM64不识别不可行交叉编译不占用目标机资源速度快工具链和sysroot配置复杂依赖容易不一致团队熟悉交叉编译、有统一CI目标机源码编译依赖天然匹配排查问题方便编译耗时长需要真机资源项目时间不紧张推荐整体路线定下来先摸清系统架构和包管理方式装好编译依赖在麒麟机器上把Qt5.14.2编译出来再用这个Qt编译应用最后用ldd检查并补齐运行时库。2. 编译前的准备别急着敲./configure2.1 先花十分钟摸清系统环境拿到机器后不要上来就解压源码先把系统信息看一遍。我这次依次执行了以下命令uname -m cat /etc/os-release nproc free -huname -m确认是aarch64/etc/os-release看到是V10 SP1版本nproc显示8核CPUfree -h显示16G内存。这些数据决定后面的编译并行度内存8G以下建议make -j216G内存配合8核用make -j8问题不大。还要确认桌面环境是否存在。Qt程序带界面的话依赖X11或Wayland麒麟V10桌面版默认走X11。如果拿到的是没有桌面的服务器版带界面程序会直接运行不起来需要先装好桌面组件或者程序本身只做无界面服务。2.2 把编译依赖一次装齐麒麟V10桌面版用apt管理软件包这方便了依赖安装。编译Qt5.14.2需要一组基础依赖包括编译器、OpenGL开发库、fontconfig、dbus、xcb扩展库。其中libgl1-mesa-dev尤其重要Qt的OpenGL模块编译离不开它libxkbcommon-x11-dev对应X11键盘扩展缺失的话后面运行时报xcb平台插件加载失败的概率极高。我在机器上实际执行的安装命令如下sudo apt update sudo apt install -y build-essential libgl1-mesa-dev libfontconfig1-dev \ libdbus-1-dev libxkbcommon-x11-dev libxcb-xinerama0-dev \ libxcb-cursor0 libxcb-cursor-dev libssl-dev libicu-dev \ libpcre2-dev libjpeg62-turbo-dev libpng-dev这里说一个常见问题麒麟系统的软件源有时候因为网络原因更新不成功apt update超时。可以把/etc/apt/sources.list里的源地址换成国内镜像源速度稳定很多。如果项目在内网离线环境下面单独说。2.3 离线环境下的依赖处理不少国产化项目在物理隔离的内网里没有外部网络源。这种情况下装依赖要提前准备好离线包。我在有网的同版本麒麟机器上用apt download把需要的deb包下载到U盘然后拷贝到目标机执行dpkg -i安装。注意一个细节libgl1-mesa-dev的依赖链比较长离线打包时要把所有依赖deb一起下载不然dpkg -i会卡在未满足的依赖关系上。检查依赖可以临时联网安装一次观察apt实际抓了哪些包再按清单逐一下载。这个步骤虽然繁琐但一次做对能省不少时间。3. 在ARM64上编译Qt5.14.23.1 源码获取Qt5.14.2源码建议直接用单包qt-everywhere-src-5.14.2一次性拿到全部模块避免分模块下载的混乱。可以从官方archive下载也可以走清华镜像速度快很多。单包大约300MB解压到工作目录即可。wget https://mirrors.tuna.tsinghua.edu.cn/qt/archive/qt/5.14/5.14.2/single/qt-everywhere-src-5.14.2.tar.xz tar -xf qt-everywhere-src-5.14.2.tar.xz cd qt-everywhere-src-5.14.23.2 configure参数要点configure这一步决定整个编译的走向。我用的配置如下mkdir build cd build ../configure -prefix /opt/Qt5.14.2-arm64 \ -opensource \ -confirm-license \ -release \ -skip qtwebengine \ -skip qtdoc \ -nomake examples \ -nomake tests \ -no-opengl几个关键参数说明一下防止盲目照抄翻车-prefix指定安装目录所有Qt库和工具会装进这里。建议用独立目录不要污染系统自带库。-skip qtwebengine跳过WebEngine内核模块。这东西编译时间极长、第三方依赖极多一般业务程序用不到QWebEngineView就不需要。-no-opengl在没有GPU或不需要OpenGL硬件加速的机器上加上可以少掉一批麻烦。但如果程序用了QOpenGLWidget或QML的场景图OpenGL不能关这个参数要自己判断。-nomake examples -nomake tests不编译示例和测试大幅缩短整体编译时间。configure执行完会打印一份配置汇总重点看Platfore识别结果和OpenGL状态。ARM64平台一般能自动识别为linux-g我编译时没有额外指定-platform参数。3.3 make编译与安装配置通过后直接开编make -j8飞腾D2000虽然是国产ARM CPU但8核对编译任务完全够用。全量编译Qt5.14.2在这颗CPU上大概需要两个半小时到三个小时。编译过程中如果参数里没有跳干净qtwebengine那个模块会让编译时间直接翻倍所以前面-skip必须确认生效。如果中途失败绝大多数是configure阶段漏装了某个-dev包回到第2节补上依赖再重新configure。编译成功后在prefix目录下会看到一批libQt5Core、libQt5Gui、libQt5Widgets等库文件。最后执行安装make install3.4 配置环境变量安装完成后把Qt相关路径写进~/.bashrcexport PATH/opt/Qt5.14.2-arm64/bin:$PATH export LD_LIBRARY_PATH/opt/Qt5.14.2-arm64/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH/opt/Qt5.14.2-arm64/plugins export QML2_IMPORT_PATH/opt/Qt5.14.2-arm64/qmlQT_PLUGIN_PATH很重要Qt运行时靠它找平台插件后面部署阶段还会用到。如果程序用了QMLQML2_IMPORT_PATH也必须有。4. 编译你的应用并部署到目标机器4.1 用新Qt重新编译应用拿到编译好的Qt之后项目源代码也要用它重新编译。如果是qmake工程mkdir -p build cd build /opt/Qt5.14.2-arm64/bin/qmake ../你的工程.pro make -j8如果项目是CMake管理则指定Qt的安装前缀cmake .. -DCMAKE_PREFIX_PATH/opt/Qt5.14.2-arm64 make -j8这里有个容易踩的坑团队工程文件里经常把Qt路径写死比如/home/user/Qt/5.14.2/gcc_64之类。换到ARM64机器上要全局搜索.pro文件和CMakeLists.txt里的硬编码路径全部改成新的prefix目录。漏改一处编译到一半就会报各种找不到库的错误。编译过程中如果报GL/gl.h: No such file or directory说明系统的OpenGL头文件还是没装全回头补libgl1-mesa-dev即可。报xcb相关错误则继续补xcb开发库。4.2 用ldd定位缺失的动态库编译成功只是第一步。直接双击运行大概率起不来因为系统找不到Qt的共享库。用ldd查一下就知道缺什么ldd ./MyApp | grep not found输出会列出一堆libQt5Core.so.5 not found。解决方案是把应用依赖的Qt库拷贝到应用自己目录下做成随行库。我用的是全量拷贝方式mkdir -p MyApp/libs cp -P /opt/Qt5.14.2-arm64/lib/libQt5*.so* MyApp/libs/全量拷贝会比挑着拷贝多占几百MB磁盘但省去了一个个查依赖的时间后续排错也方便很多。如果应用还依赖其他第三方.so同样方式拷贝到libs目录。4.3 平台插件和启动脚本Qt程序运行时需要加载platform plugin最常见的是xcb插件负责X11窗口环境。如果插件目录没拷贝或者路径没指对启动时就会报qt.qpa.plugin: Could not find the Qt platform plugin xcb in 这也是很多程序在本地编译机正常、拷到别的机器却起不来的经典原因。解决方案是把整个plugins目录一起拷过去cp -r /opt/Qt5.14.2-arm64/plugins MyApp/plugins然后写一个启动脚本把环境变量设好再执行程序#!/bin/bash APP_DIR$(cd $(dirname $0) pwd) export LD_LIBRARY_PATH$APP_DIR/libs:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$APP_DIR/plugins exec $APP_DIR/MyApp $这个脚本是良心推荐比每次手动export方便得多。注意QT_PLUGIN_PATH指向的是包含platforms子目录的那个plugins目录路径别搞错。运行脚本如果程序能弹窗部署基本成功。如果用的是Wayland会话可能需要额外设置QT_QPA_PLATFORMwayland-egl或显式切到xcb不过麒麟V10桌面默认是X11一般不会遇到。5. 常见运行问题与排查心得5.1 问题速查表把调试过程中遇到和收集到的高频问题整理成表方便对照现象可能原因排查/解决Exec format error架构不匹配拿了x86二进制uname -m确认架构重新编译ARM64版找不到libGL.so缺OpenGL运行库安装libgl1-mesa-dev或软链接libGL.so文件Could not find platform plugin xcbplugins目录没拷贝或路径不对拷贝plugins目录设置QT_PLUGIN_PATHQML module not foundqml目录缺失拷贝qml目录设置QML2_IMPORT_PATH中文显示为方块中文字体缺失fc-list检查安装fonts-noto-cjk或文泉驿字体数据库驱动QMYSQL not loaded没有编译MySQL插件编译Qt时指定MySQL模块或单独构建qsqlmysql插件程序启动后画面全黑OpenGL驱动问题尝试QT_QUICK_BACKENDsoftware或禁用GPU加速5.2 几个踩得比较深的坑第一个坑是编译内存。最开始我直接make -j8结果内存占用冲到很高加上桌面日常使用整机卡到无响应。后来改成make -j4编译时间多花半小时但全程稳定。如果你的机器内存只有8G建议j4而不是j8。第二个坑是qmake路径搞混。系统里原本装过一个旧版Qt如果直接执行qmake -vPATH顺序不对会显示旧版本编译出的应用一连串链接错误。解决办法是用绝对路径调用新编译的qmake或者把新Qt的bin目录放在PATH的最前面。第三个坑是离线依赖。客户内网机器无法连接外部源我提前在有网的同版本麒麟机器上apt download相关包U盘拷过去dpkg -i。如果遇到依赖版本冲突可以用aptitude调整但更稳妥的办法是在同版本备用机上先做一次完整依赖导出避免临时抓瞎。5.3 输入法和字体的问题Qt程序在麒麟上有时无法调出中文输入法表现和浏览器里打不了字类似。需要在启动脚本里加上export QT_IM_MODULEfcitx麒麟默认的搜狗输入法用的是fcitx框架。如果设置了还不行检查系统是否装了fcitx-frontend-qt5没装就补上。这个库在麒麟系统里有时不自带Qt程序独立打包时经常漏掉算是比较隐蔽的一个坑。字体方面如果程序界面出现方块先执行fc-list看系统里有没有中文字体。没有的话装fonts-noto-cjk或文泉驿正黑apt install就能解决。6. 打包交付的几点建议6.1 目录拷贝和deb包程序调通后怎么交付给客户是一个值得提前想的问题。如果只是内部工具直接拷贝整个应用目录加启动脚本就够了客户拿过去改下路径就能用。如果要正式交付我建议打成deb安装包。麒麟V10基于Debian系deb包安装方便还能定制桌面快捷方式和启动菜单装上就能用体验好很多。打deb包时把libs、plugins、qml和应用本身都放进/opt/YourApp/写一个postinst脚本处理权限和桌面图标depends字段里把系统级依赖写上比如libgl1-mesa-dev那一串。6.2 关于AppImage也可以考虑AppImage格式麒麟系统对AppImage支持不错而且它把运行环境打包到一个文件里客户无需解压安装。但注意AppImage工具链要选aarch64对应版本不要拿x86的工具去打ARM的包打出来的AppImage必须在ARM机器上运行。实践下来相对简单直接的交付方式还是deb包因为麒麟的软件商店对deb支持最成熟分发路径最短。最后说几点实在的体会这次适配花了我们团队三天半时间如果一开始就按目标机源码编译这条路走能省掉不少冤枉路。Qt在ARM Linux上的成熟度比想象中高5.14.2编译出来跑起来都很稳没有特别离谱的性能问题。关键是别急着动手先确认架构和系统版本装齐依赖再开始编译每一步都走得扎实。部署环节遇到的问题九成是环境变量和库路径问题第一时间用ldd检查比反复重启程序有效得多。还有一个小技巧每次修改启动脚本后用ldd ./MyApp | grep not found重新核对一次确认没有新的缺失再继续。后面如果客户机器数量多强烈建议搭一套ARM64的CI编译环境真机上编译一次分发到同架构机器上都通用省得每台都重新过一遍编译流程。本文还有配套的精品资源点击获取
