做嵌入式Qt开发最怕听到的话是什么板子环境太简陋装不了Qt。早年我在x86上写得好好的程序一放到ARM板子上就各种崩缺库、版本不对、平台插件找不到光排查环境问题就耗掉一半时间。后来我干脆把方案从动态部署换成静态交叉编译一个可执行文件拷过去就能跑省心得多。这篇手册整理的是我用Qt 5.14.2在x86主机上交叉编译aarch64静态库、最终把Qt程序部署到ARM Linux目标板的全过程。内容覆盖工具链搭建、Qt源码配置、编译参数解释、实际部署验证以及我踩过的一系列坑。适合三类人看一是嵌入式工程师需要在瘦身系统上跑Qt界面二是做国产化适配、手里拿着飞腾/鲲鹏这类ARM平台板子的开发者三是被动态库依赖折磨过、想彻底摆脱运行时依赖的Qt开发者。全文按实操顺序来每个步骤都能照着抄。1. 项目背景与整体思路拆解1.1 为什么非要用aarch64静态交叉编译这个问题得分两半看交叉编译为什么必要静态编译为什么必要。交叉编译的必要性很好理解。ARM板子性能再好跟桌面级的x86主机比还是有明显差距。我在一块四核A55的板子上编译过Qt源码光是qtbase这一个模块就跑了三个多小时如果再把qtdeclarative、qtwebengine这些重模块编一遍一天可能都不够。放到8核16线程的x86主机上用交叉编译的方式编完整个Qt源码包也就是四十分钟到一个小时的事。效率差距不是一个量级。静态编译的必要性则来自目标环境的残酷现实。很多嵌入式产品的rootfs是裁剪过的为了压缩存储和内存占用里面根本没装X11、libxcb、fontconfig这些桌面环境依赖更不可能帮你预装Qt运行库。如果拿着一个动态链接Qt的程序往这种板子上部署光是补齐运行依赖就能让你怀疑人生。静态编译直接把所有Qt库代码全部链接进可执行文件生成一个自包含的二进制不依赖目标板上有没有Qt极大地降低了部署成本。实际项目里还有一个更痛的点批量部署。如果项目要交付到几十上百台配置不完全一致的ARM设备上动态库方案的噩梦就来了——有的设备glibc版本低有的设备缺某个.so有的设备内核新一点但库是老的。静态编译方案下只要目标板的内核版本和Linux ABI没变一个二进制通吃省掉的现场维护时间非常可观。提示静态编译不是银弹它带来的体积和内存开销必须纳入设计考量。但如果你和我一样面对的是系统精简、环境混乱、没有网络、不能现场编译的场景静态交叉编译几乎是唯一能让你按时交付的方案。1.2 静态编译与动态编译怎么选动手之前先把这个基本问题讲透。Qt程序的部署方式本质上只有两条路动态链接和静态链接。两者差异我会用一个表格列出来。维度动态编译静态编译产物体积小单个.so几MB大可执行文件通常10~30MB运行依赖目标板必须有匹配的Qt库和QPA插件只需系统基础库无需Qt部署复杂度需要搬运.so、插件目录、配置平台路径一个二进制拷贝过去直接跑升级维护替换.so即可二进制不变改一行代码都要重新编译整个程序磁盘和内存多个程序共享同一套Qt库省资源每个程序都背着全量Qt浪费资源调试排查可用系统库替换定位问题容易出了问题可调试信息少排查成本高程序体积增长增量小每加一个Qt模块都会膨胀选型建议很明确如果你的目标板rootfs有几百MB的余量并且你能把动态库和插件目录完整部署到位动态编译没毛病但如果你面对的是50MB级别的精简文件系统或者你的程序需要拷贝到各种不同环境的机器上都能跑那静态编译是更稳妥的选择。还有一个技术细节常被忽略Qt的插件体系。动态编译时QPA平台插件比如libqlinuxfb.so是独立的.so文件部署时如果不放在指定路径、不设置QT_QPA_PLATFORM环境变量程序直接就起不来。静态编译时Qt的插件代码会被整体链接进可执行文件不再有插件找不到这种问题。这一点对现场交付来说省下了大量沟通成本。1.3 版本选型停留在5.14.2是务实选择很多朋友问过我既然Qt 6都出来好几年了为什么还要用5.14.2做新项目我的回答是嵌入式场景下稳定和可控比尝鲜重要得多。5.14.2是Qt 5.14系列最后一个补丁版本在5.14系列里属于稳定成熟的LTS分支。它在嵌入式领域的生态非常庞大很多ARM厂商SDK、评估板BSP默认提供的Qt版本就是5.14.x社区上你遇到的绝大多数坑都已经有人趟过搜索解决方案非常容易。相比之下Qt 6在构建体系上做了很大调整CMake全面替代qmake插件机制和模块划分也有变化交叉编译的mkspec配置方法跟着变了。如果你的团队之前没有Qt 6的交叉编译经验短期内想要跑通全流程是有学习成本的。5.14.2则可以直接复用老经验qmake体系成熟linux-aarch64-gnu-g这个mkspec是官方原生支持的省掉很多定制工作。注意如果你确定要上Qt 6这篇手册的大部分环境搭建思路依然有效但configure参数、mkspec写法、模块列表都需要对应更新。这里我只保证5.14.2的内容都是实测可用的。2. 环境准备与工具链搭建2.1 主机系统与基础依赖安装我用的主机系统是Ubuntu 20.04 x86_64这也是目前嵌入式交叉编译最常用的发行版。Debian 10/11、Deepin、UOS的x86版本理论上都一样只要apt源能装到aarch64交叉工具链就行。先更新索引然后安装编译工具链。Ubuntu 20.04仓库里自带gcc-aarch64-linux-gnu和g-aarch64-linux-gnu版本是gcc 9.3编译Qt 5.14.2完全足够没必要手动折腾更高版本的工具链。sudo apt update sudo apt install -y build-essential gcc-aarch64-linux-gnu g-aarch64-linux-gnu \ libc6-dev-arm64-cross pkg-config python3 perl flex bison这里解释一下每个包的作用build-essential主机侧的编译基础包括make、gcc、g等交叉编译Qt时会用到主机侧的工具来生成一些辅助程序。gcc-aarch64-linux-gnu / g-aarch64-linux-gnu交叉编译的核心编译器产出aarch64架构的目标代码。libc6-dev-arm64-cross目标板的C标准库头文件和静态/动态库编译器找头文件和库时要用到。perl / python3Qt的configure脚本和构建脚本依赖这两个解释器。flex / bison编译某些Qt模块或第三方依赖时可能用到装上不亏。装完以后验证一下工具链aarch64-linux-gnu-gcc --version能正常输出版本号就说明基础工具链已经就绪。2.2 交叉工具链验证与sysroot检查工具链装完先别急着编Qt写一个最简单的C程序验证交叉编译链路是通的。#include stdio.h int main(void) { printf(hello aarch64\n); return 0; }保存为test.c用交叉编译器编译aarch64-linux-gnu-gcc test.c -o test_arm file test_arm如果输出里包含ELF 64-bit LSB executable, ARM aarch64说明交叉编译正常。此时还可以顺手检查一下工具链自带的sysrootaarch64-linux-gnu-gcc -print-sysroot通常工具链在安装时会把自己的libc头文件和库放在某个目录下这个目录就是编译器的默认sysroot。如果没有额外指定编译器会优先在这里找头文件和库。搞清楚这个路径对后面排查头文件错乱问题非常重要。如果你的板子有自己的rootfs里面有完整库文件建议用rsync把板子上的根文件系统同步到主机上作为Qt编译时的自定义sysroot。这样Qt在编译时用到的头文件和库版本能跟目标板真实环境保持一致避免出现编译通过但上板运行崩溃的惨剧。2.3 sysroot与目标板根文件系统准备sysroot这个概念第一次接触的人容易懵可以把它理解为编译器眼中的目标系统根目录。你交叉编译时编译器默认去/usr/include找头文件、去/usr/lib找库但那是x86主机自己的路径。当你指定了sysroot之后编译器会跑去/你的sysroot目录/usr/include和/你的sysroot目录/usr/lib里面找这样拿到的头文件和库才是ARM架构的。准备sysroot有两种常规做法。第一种直接从目标板同步完整rootfs。先确保板子上有rsync和sshd然后在主机上执行mkdir -p /opt/rootfs rsync -avz root目标板IP:/ /opt/rootfs/同步完成后检查 /opt/rootfs/usr/lib 下是否有aarch64架构的libc.so.6file /opt/rootfs/usr/lib/aarch64-linux-gnu/libc.so.6第二种用debootstrap构建一个干净的arm64基础系统sudo debootstrap --archarm64 focal /opt/rootfsdebootstrap会自动从Ubuntu源拉取arm64的基础包构建一个标准的目录结构。这个方式不需要你手上正好有一块能开机、能联网的板子纯粹在主机上就能完成。sysroot准备好之后在configure Qt时用-sysroot参数指定它。同时建议把交叉编译器的路径加入PATH免得每次敲一长串export SYSROOT/opt/rootfs export PATH/usr/bin:$PATH注意sysroot里的libc版本必须和你要部署的目标板环境匹配。如果目标板是Debian系的用debootstrap构建版本选同一个major/minor就好如果是厂商裁剪过的系统源码包里通常有说明直接按说明来。3. Qt源码配置与关键参数解析3.1 源码获取与校验Qt 5.14.2的完整源码包叫qt-everywhere-src-5.14.2.tar.xz这个包包含了所有官方模块。国内用户直接从清华、中科大的镜像站下载速度很快不需要折腾其他渠道。wget https://mirrors.tuna.tsinghua.edu.cn/qt/official_releases/qt/5.14/5.14.2/qt-everywhere-src-5.14.2.tar.xz下载完建议先校验一下MD5避免下载损坏导致的编译怪问题md5sum qt-everywhere-src-5.14.2.tar.xz官方公布的MD5值在release notes里能找到对不上就重新下载。然后解压tar -xJf qt-everywhere-src-5.14.2.tar.xz cd qt-everywhere-src-5.14.2这里要提醒一个细节如果你是在Windows上下载再拷到Linux主机解压后记得给configure加执行权限chmod x configure我见过有人因为少了这一步执行./configure时报Permission denied白白排查了半天。3.2 configure关键参数逐个拆解Qt的configure是整个编译过程里技术含量最高、也最容易出错的一步。参数选对了后面make一气呵成参数漏了或者选错轻则编译失败重则编译出来的库部署到板子上根本跑不起来。下面给出我实测可用的完整配置命令然后逐个解释./configure \ -prefix /opt/Qt/5.14.2/aarch64-static \ -static \ -release \ -opensource \ -confirm-license \ -xplatform linux-aarch64-gnu-g \ -sysroot /opt/rootfs \ -no-opengl \ -no-xcb \ -no-xkbcommon \ -linuxfb \ -no-feature-vnc \ -nomake examples \ -nomake tests \ -skip qtwebengine \ -skip qtdeclarative \ -no-pch \ -optimize-size \ -strip \ -qt-zlib \ -qt-libpng \ -qt-libjpeg \ -no-gif逐项说明-prefix /opt/Qt/5.14.2/aarch64-static指定Qt库安装路径。后面qmake也在这里面编译业务程序时需要它。-static核心开关让Qt编译静态库.a文件这是整个静态编译的关键。-release只编译release版节省时间避免debug库带来的体积膨胀。-opensource -confirm-license接受开源协议。如果是商业授权用户改成商业版对应参数。-xplatform linux-aarch64-gnu-g指定交叉编译目标平台。5.14.2源码包自带这个mkspec官方支持不用自己写。-sysroot /opt/rootfs指定目标板根文件系统路径编译器会优先从这里找ARM架构的头文件与库。-no-opengl大多数嵌入式板子的GPU支持有限Qt OpenGL相关模块依赖一套完整的EGL/GLES环境没有的话先关掉。后面要上OpenGL再单独补。-no-xcb目标板没有X11环境关掉XCB支持。如果板子上跑的是X11服务器这里要改成不关。-no-xkbcommon键盘映射相关没有X11也同样不需要。-linuxfb启用Linux Framebuffer平台插件。让Qt直接写/dev/fb0不依赖显示服务器这是嵌入式Qt最常见的显示方案。-no-feature-vncQt内置VNC服务端功能用不上就关掉能省一点空间。-nomake examples -nomake tests不编译示例和测试代码省时间也省空间。-skip qtwebengineWebEngine模块是编译耗时大户依赖Chromium交叉编译极其痛苦。没有浏览器需求就明确跳过。-skip qtdeclarative如果你不需要QML/QtQuick界面可以跳过。我这里做的传统Widgets界面所以跳过。-no-pch禁用预编译头。预编译头能加快编译速度但交叉编译时偶尔会触发一些兼容性问题。为了保证稳定我宁可多花一点编译时间。-optimize-size让编译器优化体积而不是优化速度静态编译场景下非常实用。-strip编译完成后自动strip剥掉符号表。能省可执行文件体积但这步我后来发现最好谨慎点因为遇到段错误想调试时没有符号表会很难受。可以在configure时不加最后只对部署产物strip。-qt-zlib -qt-libpng -qt-libjpeg使用Qt源码自带的zlib、libpng、libjpeg不依赖系统版本。这样静态链接时不会引入版本混乱的问题。-no-gifGIF格式支持老旧且用得少关掉。这套参数配置完configure会输出一份Summary。强烈建议花两分钟把内容读一遍确认以下几个关键项Using static linking为yesPlatform一栏显示的是linux-aarch64-gnu-gQPA backends里包含linuxfb没有意外的Qt Xml等已被标记为skip的模块如果Summary里显示的platform不对或者static是no先别急着make回头检查参数再跑一次。提示configure脚本支持在命令行后面追加 -h 查看帮助。遇到不确定的模块开关直接在帮助里搜模块名比网上搜答案更快更准。3.3 mkspec定制与sysroot联动Qt 5.14.2自带linux-aarch64-gnu-g这个mkspec绝大多数情况下不需要额外修改。它内部通过include实现了对通用linux配置的复用默认已经指向了aarch64交叉编译器。但实际使用中我会做一个小改动在mkspec里显式指定sysroot的编译选项防止qmake在生成业务工程的Makefile时丢掉--sysroot参数。编辑qtbase/mkspecs/linux-aarch64-gnu-g/qmake.conf在文件末尾追加三行QMAKE_CFLAGS --sysroot/opt/rootfs QMAKE_CXXFLAGS --sysroot/opt/rootfs QMAKE_LFLAGS --sysroot/opt/rootfs这样做的原因是configure阶段虽然通过-sysroot指定了路径但qmake生成的工程文件里不一定每次都会带上完整的sysroot标志。显式写在mkspec里相当于给所有基于这个mkspec的编译过程加了一道保险。之所以放在mkspec而不是工程文件里是因为mkspec对所有基于该平台配置的工程都生效。你后续每建一个Qt工程qmake都会自动带上这些标志不需要反复手动配置。4. 编译全流程与实战部署4.1 Qt库编译与安装configure通过之后开始正式的编译make -j$(nproc)-j参数会调满所有CPU核心加速编译。如果机器内存小于8GB建议把并行数砍半比如-j4否则编译过程中内存可能被打满出现莫名其妙的编译报错。关于这个make过程我的经验是分步来比较稳妥cd qtbase make -j$(nproc) make install cd ..先把qtbase编译并安装验证qmake可用之后再回到源码根目录编译其他模块。make -j$(nproc) make install整个Qt 5.14.2全模块交叉编译在8核16线程的机器上大约需要40到60分钟。装完之后检查一下关键静态库是否生成ls /opt/Qt/5.14.2/aarch64-static/lib/正常情况下能看到libQt5Core.a、libQt5Gui.a、libQt5Widgets.a等.a文件以及plugins目录下已经静态编译好的平台插件文件。配置环境变量时有两点要特别注意qmake等主机工具要放到PATH前面方便直接调用。不要在主机上给LD_LIBRARY_PATH加上Qt安装目录因为这里面的库是aarch64架构x86程序的动态库搜索不该包含它。export QTDIR/opt/Qt/5.14.2/aarch64-static export PATH$QTDIR/bin:$PATH4.2 编写并编译第一个aarch64静态Qt程序Qt库编译完成后用一个小窗口程序验证整套环境是否真的能产出可运行的ARM程序。先建工程目录hello_qt里面放main.cpp和hello.pro。main.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Hello aarch64 static Qt); label.resize(400, 200); label.show(); return app.exec(); }hello.proQT widgets TARGET hello TEMPLATE app SOURCES main.cpp CONFIG static这里的CONFIG static告诉qmake链接时优先使用静态库。虽然Qt库本身是静态编译的但业务工程里显式加上这个配置能确保链接器行为符合预期。编译/opt/Qt/5.14.2/aarch64-static/bin/qmake hello.pro make编译过程如果没有报错产物就是一个aarch64架构的ELF可执行文件。检查一下file hello正常输出会包含ELF 64-bit LSB executable, ARM aarch64。再确认库链接情况aarch64-linux-gnu-ldd hello这里你会看到hello只依赖于libc、libstdc这些系统基础库Qt相关的依赖已经全部静态链接进去了。如果追求全静态还可以在链接时加上-static-libgcc -static-libstdc这样连gcc和g的运行时库也一并静态链接。但对大多数嵌入式场景来说目标系统是完整Linux的前提下动态链接基础glibc是可以接受的全静态反而可能触发glibc的NSS警告不建议一上来就这么干。部署前做一下strip瘦身aarch64-linux-gnu-strip hello我实测这个简单的Qt Widgets程序静态编译、optimize-size、release模式、strip之后体积在16MB左右。如果去掉优化体积编译或者没strip可能到20MB以上。体积能不能接受要看目标板存储情况但16MB对一个UI程序来说换来的是任何板子都能跑值这个价。4.3 部署到目标板并运行验证用scp把hello传到目标板scp hello root192.168.1.100:/root/在目标板终端里运行export QT_QPA_PLATFORMlinuxfb ./hello如果屏幕上有窗口显示出来说明整套交叉编译链路已经跑通。linuxfb这个平台插件有几个常用环境变量需要记住QT_QPA_FB_ROTATION90屏幕旋转90度类似参数还有180、270。QT_QPA_FB_FORCE_FULL_REFRESH1部分驱动下局部刷新会花屏强制全刷可以解决。QT_QPA_FB_HIDECURSOR1隐藏鼠标光标纯触屏设备上常用。运行不起来时先确认以下三件事目标板是否存在/dev/fb0没有的话检查内核配置CONFIG_FB。当前用户对/dev/fb0是否有读写权限没权限就加权限或者用root跑。是否设置了QT_QPA_PLATFORMlinuxfb不设置的话Qt默认会去找xcb或者其他插件极大概率报错。5. 常见问题排查与经验总结5.1 典型错误速查表交叉编译过程中我遇到过的、以及帮同事排查过的问题里最有代表性的整理成一个速查表。报错现象可能原因解决方案qt.qpa.plugin: could not find the qt platform plugin linuxfb编译时没有启用linuxfb插件或运行时没有设置QT_QPA_PLATFORMconfigure时加-linuxfb运行时export QT_QPA_PLATFORMlinuxfbqt: cannot mix incompatible Qt library (version 0x50601) with this library编译产物混用了不同版本的Qt库qmake路径不对或Makefile是旧的确保使用/opt/Qt/5.14.2/aarch64-static/bin下的qmake重新生成Makefile执行make clean后重新编译undefined reference toQWidget::xxx工程里只qt了core没qt到widgets或者编译命令少了-lQt5Widgets检查.pro文件确认QT widgets重新qmake后查看Makefile里的LIBS找不到交叉编译器gPATH里没加工具链路径或者没装g-aarch64-linux-gnu安装工具链并export PATH/usr/bin:$PATHQtWebEngine模块编译失败没有skip掉qmwebengine或者依赖了极高版本的python/gnconfigure加-skip qtwebengine嵌入式不用就不编运行时Segmentation faultlinuxfb的帧缓冲访问问题或者字体加载崩溃先试QT_QPA_FB_DISABLE_PARTIAL_UPDATE1确认/dev/fb0可读写换内置字体汉字显示成方块目标板上没有中文字体Qt找不到字体渲染交叉编译时用QT_QPA_FONTDIR指定字体路径或把字体文件拷到目标板/usr/share/fontsconfigure时报Could not find qmakeconfigure来自一个不完整的Qt源码包qtbase还没解压完整重新下载完整qt-everywhere-src包核对md5关于cannot mix incompatible Qt library这个错我多说一句。version 0x50601表示的是Qt 5.6.1的版本号。在网上看到很多人交叉编译Qt程序时遇到这个错误基本上都是因为系统里先装了一个旧版Qt比如Ubuntu自带的qtbase5-dev而业务工程Makefile里的路径又指到了这个旧版本上。排查时用which qmake看当前生效的是哪个qmake再用qmake -v确认版本号基本能定位问题。5.2 排错方法论与必备调试技巧交叉编译出了问题最忌讳的就是瞎试。我总结了一套固定的排查顺序按这个顺序来大多数问题都能收敛到一个小范围内第一确认工具链本身没问题。最简C程序能编译、能在板子上运行才说明从x86到ARM这条基础通道是通的。第二确认Qt库本身没问题。用编译好的qmake编一个最小Qt程序如果能运行说明Qt的core/gui/widgets/linuxfb这些关键模块都是好的。第三再排查业务工程的问题。比如第三方库、自定义模块、特殊的链接参数。这套思路的核心逻辑是把责任范围不断缩小不要一上来就在一个大工程里漫无目的地翻日志。另外分享一个很管用的调试手段看qmake生成的Makefile。qmake做完之后Makefile里会列出完整的编译命令和链接库列表。如果链接时报undefined reference打开Makefile看LIBS一项里面有没有-lQt5Widgets、-lQt5Gui、-lQt5Core一目了然。库的顺序也有讲究Qt静态库的链接依赖是Widgets依赖Gui、Gui依赖CoreMakefile里的顺序通常已经是正确的手动改链接参数时千万不要把顺序打乱。再提一下符号表的取舍。configure时我建议先不加-strip等所有功能都验证通过了最后部署阶段再对可执行文件单独执行strip。否则遇到段错误时用gdb调试会发现所有的函数符号都丢了根本定位不到问题在哪一行。5.3 体积优化与后续扩展心得静态编译最大的痛点就是程序体积。一个Hello级别的Widgets程序就16MB业务逻辑一多、模块一加突破30MB很正常。体积优化可以从几个方向入手第一个方向是模块裁剪。如果你用不到Qt Network就用-skip qtnetwork把模块跳过用不到Qt Sql同样跳过。静态链接器本身有死代码消除机制没引用到的函数不会进最终二进制但模块里被引用到的部分还是会带进来。所以源头裁剪比事后优化有效得多。第二个方向是编译选项。configure时用-optimize-size加上release模式对体积影响明显。这个方法对代码性能有一点负面影响但UI程序大部分时间在等用户输入性能差异几乎感知不到。第三个方向是strip。这是性价比最高的一步。release编译出来的二进制默认带符号表直接strip一下能砍掉接近一半体积。还有一个小技巧如果目标板有空间放字体文件不要在Qt程序里内置字体把字体放到/usr/share/fonts或者用QT_QPA_FONTDIR环境变量指定字体目录。否则为了显示几个汉字可能要为字体付出大几MB的体积代价。最后再分享一个我个人很受用的习惯把整个交叉编译环境复现过程写成一个shell脚本包括sysroot路径、configure参数、安装路径、环境变量全部记录下来。这样换一台开发机、加一个同型号的新板子、甚至交给同事接手跑一遍脚本就能把环境完整复现出来。我第一次搭这套环境前后花了两周第二次照着脚本重搭半小时搞定。这大概是整个过程中最值得沉淀的一笔资产。