做嵌入式产品的人大概都遇到过这样的场面板子上跑的程序在开发机上一测就崩提示找不到 libQt5Core.so.5或者现场设备要升级脚本里写死了库路径结果一换文件系统整个界面就起不来。更头疼的是有些方案为了省空间把 Qt 库裁得七零八落删掉一个看起来没用到的插件 so程序就在某个特定操作下直接退出。说到底这些都是动态链接带来的耦合。Qt5.14.2 的 aarch64 静态交叉编译本质上要解决的就是这件事让一个可执行文件自己扛下所有依赖拷过去就能跑不用在目标板上维护一套 Qt 运行库。这篇手册写给已经会写 Qt 程序、但还没系统做过交叉静态编译的人也写给被动态库折磨过、想一次性把部署问题解决掉的同行。从工具链搭建到 configure 参数取舍再到静态插件导入和字体这些静态编译特有的坑我会按我实际趟过的路径讲一遍。1. 为什么选静态交叉编译先想清楚收益和代价1.1 动态部署踩过的那些坑动态链接的部署方式逻辑上是优雅的目标板存一份 Qt 运行库多个程序共享升级库就能统一修 bug。但落到实际产品里这份优雅经常变成麻烦。最常见的是库版本漂移——开发机装的是某个发行版自带的 Qt5.14.x目标板是另一套裁剪过的运行时.so的 soname 对得上符号版本却对不上运行时报一句莫名其妙的 version Qt_5 not found。其次是插件路径问题。Qt 的插件默认从可执行文件目录的platforms/、imageformats/等子目录加载打包时少拷一个libqjpeg.so用户上传 jpg 头像就失败少拷platforms/libqlinuxfb.so程序直接报 This application failed to start because no Qt platform plugin could be initialized。这类问题在实验室里很难复现因为它只在特定文件系统布局下出现。再有一个更隐蔽的目标板 rootfs 是只读的程序想在运行时动态加载库但库被放在了一个靠后的挂载点上启动顺序稍有偏差就加载不到。你临时改个环境变量能绕过可产品不会给你改环境变量的机会。静态编译把这些不确定性一刀切掉。所有用到的 Qt 代码、图片格式解析、字体渲染、平台抽象全部编译进最终的可执行文件运行时不再依赖外部 Qt 库和插件目录。代价也明确单个文件体积从几 MB 涨到几十 MB多个程序无法共享代码改一个 bug 就得整体重编。这些代价在嵌入式场景里往往是能接受的尤其是设备功能单一、更新频率低的时候。1.2 方案选型的几个关键决策决定做静态交叉编译之后还有几个岔路口要选。第一宿主机用哪个发行版。我不是在开玩笑这是真会踩坑的地方。Qt5.14.2 的源码对 glibc 版本和 GCC 版本有一定要求太新的发行版比如默认 GCC 13 的编译时会撞上一堆老代码的告警甚至报错。我一般倾向选一个稍保守的构建环境GCC 版本落在 9 到 11 之间比较省心。实在只能用新环境就准备几组补丁后面对应问题我会展开。第二用不用目标板的 sysroot。sysroot 是目标系统头文件和库的集合。静态编译理论上只需要-static链接 Qt 的库但因为 Qt 会依赖 zlib、libpng、freetype 这些第三方库如果没有 sysroot就得让 Qt 用自己源码树里带的版本。Qt 提供了一批-qt-*开关-qt-zlib、-qt-libpng等作用就是用自带的第三方库编译省去准备 sysroot 的麻烦。我的建议是能在 sysroot 里准备好的依赖尽量用 sysroot用得顺手且版本可控不好准备的比如 freetype、harfbuzz就用-qt-前缀让 Qt 自带减少对目标系统的假设。第三平台插件怎么选。aarch64 嵌入式设备常见的显示后端有 linuxfb、eglfs 两种。纯 framebuffer、没 GPU 的方案用 linuxfb有 GPU、跑 OpenGL ES 的用 eglfs。这个选择会直接影响 configure 里对 opengl 的处理也决定后面要不要静态导入QLinuxFbIntegrationPlugin还是QEglFSIntegrationPlugin。提示平台插件选错不会在编译期报错而是编译成功后一运行就提示找不到 QPA 插件。先确认目标板有没有 /dev/fb0、有没有 GLES 驱动再定插件别凭感觉。2. 编译环境与工具链的落地准备2.1 宿主机依赖包清单交叉编译 Qt 本身对宿主机的依赖不算多但少了任何一样都会在 configure 或 make 阶段卡住。以常见的 Debian/Ubuntu 系为例需要准备的包大致是这些sudo apt-get install -y \ build-essential perl python3 \ bison flex gperf \ libxkbcommon-dev libxkbcommon-x11-dev \ libglib2.0-dev libpixman-1-dev \ libfontconfig1-dev libfreetype6-dev \ zlib1g-dev libpng-dev libjpeg-dev \ pkg-config这里面有几个值得说明。perl和python3是 Qt 构建系统自己的脚本依赖具体点说Qt 有部分模块比如 qtvirtualkeyboard 的词库处理用到了 Pythonbison、flex、gperf用于生成解析器libxkbcommon-dev是 X11 和 Wayland 下键盘映射需要的。需要特别强调的是这些宿主机的开发包主要服务于 Qt 的 host 工具比如 moc、uic、rcc、host 版 qmake它们的编译走的是宿主机本地编译器和交叉编译目标程序是两条线。这一点很容易混淆你以为装了libfreetype6-dev就能给目标板用其实那只是让 host 侧不报错。目标侧真正用到的 freetype要么在 sysroot 里要么用-qt-freetype走 Qt 自带源码。2.2 aarch64 交叉工具链与 sysroot 的取得工具链我一般用 Linaro 或者 ARM 官方发布的 GNU toolchain版本挑比 sysroot 里 glibc 稍新一点但不要跨度太大的。判断标准很简单工具链的 glibc 版本不能高于目标板 rootfs 的 glibc否则静态链接出来的程序在运行时可能因为符号版本不兼容而直接段错误。拿到工具链后先做两件事。第一把它解压到固定路径比如/opt/toolchain/gcc-aarch64然后把bin加进PATHexport PATH/opt/toolchain/gcc-aarch64/bin:$PATH export CROSS_COMPILEaarch64-linux-gnu-验证aarch64-linux-gnu-gcc -v能打印出版本信息就说明路径没问题。第二准备 sysroot。如果你的工具链自带 sysroot很多发行版工具链内置了可以直接用它的路径如果没有就从目标板 rootfs 里把/usr/include、/usr/lib、/lib拷贝出来整理成一份干净的 sysroot 目录mkdir -p /opt/sysroot # 从目标板或 SDK 中同步头文件和库 rsync -a rootfs/usr/include/ /opt/sysroot/usr/include/ rsync -a rootfs/usr/lib/ /opt/sysroot/usr/lib/ rsync -a rootfs/lib/ /opt/sysroot/lib/这里要留意软链接。rootfs 里的/lib经常是/usr/lib的软链接直接 rsync 会把链接原样带过去甚至报错。用cp -a或者加-L参数把符号链接解引用成实体文件更稳。注意sysroot 不需要完整包含目标板所有内容只保留编译需要的头文件、静态库和必要的动态库即可。多余的脚本和配置文件反而会干扰 configure 的探测。整理完后general 建议是du -sh看一眼控制在几百 MB 到 1GB 之间比较合理。2.3 Qt5.14.2 源码的获取与目录规划Qt5.14.2 的源码官方发布为qt-everywhere-src-5.14.2.tar.xz体积在 500MB 上下解压后接近 3GB。很多人在搜qt5.14.2离线安装包下载其实那类在线安装器主要是给桌面开发用的交叉编译要的是这份 everywhere-src 源码包。源码里包含了 qtbase、qtdeclarative、qtsvg 等所有子模块一次编译就能出一整套。解压和目录规划mkdir -p /opt/qt-build cd /opt/qt-build tar -xf qt-everywhere-src-5.14.2.tar.xz mv qt-everywhere-src-5.14.2 src mkdir -p build-static install-static我习惯把源码、构建目录、安装目录三处分开放源码保持干净、可复用构建目录放 configure 生成的 Makefile 和中间产物安装目录就是最终make install的落点。这样即使一次编译失败删掉 build 目录重来源码和已安装内容都不受影响。install 目录最终会被打包进 SDK 或直接拷到开发机固定位置路径记得设成相对稳定、不带用户名的绝对路径否则 qmake 生成的路径里会写进你的 HOME团队其他人用起来就麻烦了。3. configure 参数逐条拆解与 mkspecs 定制3.1 核心配置参数的含义与取舍Qt 的 configure 脚本参数多到吓人但真正影响静态交叉编译成败的其实就那么十来个。下面这条命令是我在 linuxfb 方案下比较常用的一套cd /opt/qt-build/build-static /opt/qt-build/src/configure \ -prefix /opt/qt-build/install-static \ -hostprefix /opt/qt-build/install-static-host \ -opensource -confirm-license \ -release -static -optimize-size \ -xplatform linux-aarch64-gnu-g \ -device-option CROSS_COMPILEaarch64-linux-gnu- \ -sysroot /opt/sysroot \ -nomake examples -nomake tests \ -no-opengl \ -no-icu -no-iconv \ -qt-zlib -qt-libpng -qt-libjpeg \ -qt-freetype -qt-harfbuzz -qt-pcre \ -no-dbus -no-cups -no-feature-printdialog \ -skip qtwebengine -skip qtquick3d -skip qtmultimedia逐条说。-static是核心让 Qt 编译出静态库并在链接时把依赖打进去。-release关闭调试信息静态库本来体积就大debug 版会再翻几倍。-optimize-size让编译器偏向体积优化对嵌入式很实用如果你更在意运行速度可以换成-optimize-speed。-xplatform linux-aarch64-gnu-g指定目标平台描述文件。Qt5.14.2 的qtbase/mkspecs/下一般已经有linux-aarch64-gnu-g。如果没有某些裁剪过的子版本会缺就从linux-arm-gnueabi-g复制一份改名再改里面的qmake.conf。这个文件后面单独讲。-device-option CROSS_COMPILEaarch64-linux-gnu-把交叉前缀传给 mkspecs配合上面那个 xplatform 使用。它有讲究如果你的工具链前缀不是标准的aarch64-linux-gnu-比如带厂商名的aarch64-xx-linux-gnu-这里必须写全否则 configure 探测编译器时会失败。-sysroot /opt/sysroot告诉编译器到哪找目标系统的头文件和库。这个路径会同时影响 host 和 target 两套工具的编译务必确认它存在且结构正确写错了 configure 不会立刻报错而是在某个模块的 make 阶段冒出一堆找不到头文件的错误。-no-opengl是 linuxfb 方案的关键。没有 GPU 的设备完全不需要 OpenGL关掉能省一大块体积也避免因为找不到 GLES 库而编译失败。如果你的设备跑 OpenGL ES改成-opengl es2并且确认 sysroot 里有libGLESv2和libEGL的静态库——注意必须静态库动态库链接不进去。-no-icu -no-iconv是为了避开 ICU 这个大依赖。ICU 是国际化库提供排序、正则、日期格式化。Qt5 里 QtCore 在某些配置下会依赖它。交叉静态编译时 ICU 的静态库很难搞到用-no-icu直接去掉代价是部分国际化功能变为 Qt 自带的简化实现正则表达式仍能用走 Qt 自带的 QRegularExpression 或 PCRE对绝大多数设备界面没影响。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-harfbuzz -qt-pcre这一串意思是这些第三方库全部用 Qt 源码树里自带的版本编译成静态库。这样就不必在 sysroot 里准备它们的目标端版本极大降低了准备工作的复杂度。代价是版本稍旧但 Qt 官方选定的版本和 Qt 配合是验证过的稳定性反而更好。-nomake examples -nomake tests跳过示例和测试能省下大量编译时间。-skip qtwebengine这一条尤其重要qtwebengine 内部自带一个 Chromium交叉编译它是个独立的大工程和静态编译无关的时候一定要跳过否则会卡在拉取和编译 Chromium 上几个小时。3.2 mkspecs 的定制细节多数情况下linux-aarch64-gnu-g直接可用但你要理解它的结构出问题时才知道改哪。这个目录下通常只有一个qmake.conf# # qmake configuration for linux-aarch64-gnu-g # MAKEFILE_GENERATOR UNIX CONFIG incremental QMAKE_INCREMENTAL_STYLE sublib QT_QPA_DEFAULT_PLATFORM linuxfb include(../common/linux.conf) include(../common/gcc-base-unix.conf) include(../common/g-unix.conf) QMAKE_CC $${CROSS_COMPILE}gcc QMAKE_CXX $${CROSS_COMPILE}g QMAKE_LINK $${CROSS_COMPILE}g QMAKE_LINK_SHLIB $${CROSS_COMPILE}g QMAKE_AR $${CROSS_COMPILE}ar cqs QMAKE_OBJCOPY $${CROSS_COMPILE}objcopy QMAKE_NM $${CROSS_COMPILE}nm -P load(qt_config)其中最值得注意的是QT_QPA_DEFAULT_PLATFORM linuxfb。这一行决定了 Qt 编译时默认启用哪个平台抽象层也决定了最终链接进程序的是哪个平台的默认逻辑。如果你的设备走 eglfs这里要改成eglfs否则程序启动会去初始化 framebuffer 而非 EGL。这一项和 configure 里的 opengl 设置要对应linuxfb 配-no-opengleglfs 配-opengl es2。另外QMAKE_CC那几行用了$${CROSS_COMPILE}变量。这个变量要么来自环境变量要么来自 configure 的-device-option。你如果不想每次 configure 都传也可以直接把这几行里的$${CROSS_COMPILE}换成字面量aarch64-linux-gnu-。但我不建议写死因为换个工具链就要改文件容易忘反倒不如传参来得清楚。如果你的工具链没有处理好 sysroot还可能需要在这里追加QMAKE_CFLAGS和QMAKE_LFLAGS把--sysroot/opt/sysroot显式加进去。正常情况下-sysroot参数已经能覆盖但如果遇到链接阶段找不到-lc、-lpthread这类基础库八成是这里没配好。3.3 configure 执行与结果核对configure 会跑几分钟逐个探测编译器能力、第三方库存在性、平台特性。跑完之后重点看两处输出。第一看它是用什么编译器探测的。输出里应该能找到aarch64-linux-gnu-g的字样如果全是宿主机的g说明-xplatform或CROSS_COMPILE没生效赶紧停下来检查不然编译出来的“目标程序”其实是 x86 的白忙一场。第二看 configure 结尾的 summary。这个摘要会列出哪些功能启用了、哪些禁用了。重点确认这几点Build type: release、Static build: yes、-no-opengl对应的 OpenGL 是 disabled、libpng/libjpeg/zlib 用的是 bundled自带版本、ICU 是 no。任何一项不对就回到参数里找原因别带着错误的配置往下 make那样只会在几十分钟后以报错收场。提示configure 的参数被缓存进了config.summary和.qmake.cache改参数后建议重新运行一次完整的 configure而不是在旧目录上打补丁。参数变更如果不触发重新探测可能出现配置和实际不一致的情况。4. 编译、安装与静态产物的验证4.1 并行编译与内存管理configure 通过后就进入 make 阶段。这里的核心问题只有一个并行度。Qt 编译加上后面的静态链接阶段单个编译单元处理 qtdeclarative 时内存占用能飙到好几个 GB一上来就make -j$(nproc)很容易触发 OOM把编译进程杀掉报出virtual memory exhausted或者直接Killed。我的经验是分两段设置并行度。普通源文件编译阶段可以用核数的一半到全部make -j$(nproc) 21 | tee build.log一旦进入链接阶段尤其是qtdeclarative、qtsvg这些模块把并行度降到 2 到 4make -j4判断是否进入链接阶段看日志里LINK、ld出现的频率。或者干脆稳一点全程用-j4多花点时间换稳定。aarch64 的编译在中等配置机器上大概需要 1.5 到 3 小时视核数和模块数量而定。还有一个容易被忽略的点make中断后不要急着删目录重来。Qt 的 make 支持增量重新make -j4会从断点继续。但如果你在中断时改过 configure 参数那就必须重新 configure 甚至make distclean否则缓存会对不上。4.2 make install 与目录结构编译成功后make install安装后的目录结构大致是install-static/ ├── bin/ (host 工具比如宿主可用的一些辅助程序) ├── include/ (Qt 头文件) ├── lib/ │ ├── libQt5Core.a │ ├── libQt5Gui.a │ ├── libQt5Widgets.a │ ├── libQt5Network.a │ └── cmake/ (CMake 配置文件) ├── mkspecs/ ├── plugins/ │ ├── platforms/ │ ├── imageformats/ │ └── ... └── phrasebooks/注意lib/下全是.a静态库看不到.so这就是静态编译成功的标志。plugins/下的插件也是静态的.a文件。静态编译时插件不是靠目录加载的而是靠代码里显式导入后面细说。另外如果你在 configure 里没指定-hostprefixhost 工具会被装进同一个 install 目录。因为 host 工具是宿主机可执行的和目标静态库放在一起有点乱所以建议用-hostprefix单独指定把 host 工具和 target 库分开管理。4.3 用一个最小程序验证静态链接光看.a存在还不够得实际编一个程序验证。我一般用最简的 Qt Widgets 程序// main.cpp #include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(static build ok); label.show(); return app.exec(); }用安装出来的 qmake 生成 Makefileexport PATH/opt/qt-build/install-static/bin:$PATH qmake -query QT_VERSION # 应该输出 5.14.2 qmake main.cpp.pro make编出来之后先看文件类型和依赖file hello # 期望看到: ELF 64-bit LSB executable, ARM aarch64, statically linked ldd hello # 期望看到: not a dynamic executable如果file显示dynamically linked说明某个环节还在用动态链接回到 configure 确认-static是否生效如果显示了ARM aarch64但ldd还列出几个库那通常是libstdc、libgcc这些编译器运行时没静态化需要在链接时补上-static-libstdc -static-libgcc或者直接在 qmake 配置里让链接器全静态。这个细节下一节展开。5. 静态编译特有的坑与排查技巧5.1 插件必须显式静态导入这是静态编译和动态编译最大的差别也是新手最容易栽的地方。动态编译时Qt 会在运行时扫描plugins/platforms/目录自动加载插件静态编译时没有运行时扫描所有插件都得在代码里显式导入用Q_IMPORT_PLUGIN宏。平台插件是必须的。linuxfb 方案要导入#include QtPlugin Q_IMPORT_PLUGIN(QLinuxFbIntegrationPlugin)eglfs 方案则是#include QtPlugin Q_IMPORT_PLUGIN(QEglFSIntegrationPlugin)图片格式插件按需导入。如果你需要程序处理 jpg 图片就必须导入 JPEG 插件否则QPixmap::load(x.jpg)会静默失败Q_IMPORT_PLUGIN(QJpegPlugin) Q_IMPORT_PLUGIN(QGifPlugin)导入宏要写在有main()的源码里或者至少是会被链接进来的某个源文件中。写在头文件里然后被多个源文件包含会导致重复定义链接错误这一点要留意。导入的类名怎么确认去install-static/plugins/目录下看比如plugins/imageformats/libqjpeg.a对应的类名一般是QJpegPlugin规则是把libq前缀去掉、首字母大写加 Plugin。实在拿不准可以用nm libqjpeg.a | grep -i plugin找qt_plugin_instance_相关符号符号名里通常能反推出类名。提示漏导入插件的症状很隐蔽。程序能启动、能显示窗口但加载某种格式图片时返回空对象或者剪贴板功能失效却没有明确报错。遇到这类“某个功能静默失效”的问题先把可能相关的插件都Q_IMPORT_PLUGIN一遍。5.2 字体与运行时资源动态编译时Qt 通过 fontconfig 从系统字体目录里找字体。静态编译后程序跑在可能连字体目录都没有的环境里fontconfig 很可能无法工作。所以静态方案里字体必须自己带。两种做法。一是把 ttf 文件编进 qrc 资源程序启动时用QFontDatabase::addApplicationFontFromData加载QFile fontFile(:/fonts/NotoSansCJK.ttf); fontFile.open(QIODevice::ReadOnly); QFontDatabase::addApplicationFontFromData(fontFile.readAll());二是把 ttf 放在可执行文件旁边用addApplicationFont从磁盘路径加载。我倾向第一种因为资源编进二进制部署时又少一个外部依赖和静态编译的思路一致。字体的坑还不止于此。中文字体动辄十几 MB编进资源文件会让可执行文件体积再涨一截。实践中我会裁一个常用字库子集或者选一个体积较小的开源中文字体。这不是偷懒是嵌入式空间有限时的必要取舍。图片资源、翻译文件.qm同理都要用 qrc 的方式嵌进去不能用运行时从目录读取那套。5.3 常见报错速查下面这些错误我在不同项目里都碰到过整理成表方便对照。报错信息可能原因处理办法Unknown module(s) in QT: xcbqmake 用到了没编译的模块确认 configure 没有跳过相关模块或改用 linuxfb/eglfs 平台运行时no Qt platform plugin could be initialized平台插件没静态导入补Q_IMPORT_PLUGIN并确认类名正确链接时undefined reference to __cxa_throwlibstdc 没静态链接链接加-static-libstdc -static-libgccvirtual memory exhausted/ 进程 Killed并行度太高触发 OOM降低-j数值尤其链接阶段configure 报找不到编译器CROSS_COMPILE 前缀不对检查工具链前缀和 PATH运行时段错误且无输出目标板 glibc 低于工具链 glibc换用 glibc 版本不高于目标板的工具链Cannot find -lGLESv2缺少静态 GLES 库sysroot 中补静态库或改用-no-opengl关于 glibc 那一条我再补充一点。静态链接的程序虽然把 Qt 打了进去但libc层面它通常还是动态依赖的除非你连 libc 一起静态化那会带来一堆坑。所以目标板的 glibc 版本必须不低于工具链的 glibc。排查方法是在宿主机上执行aarch64-linux-gnu-strings /opt/toolchain/lib/libc.so.6 | grep GLIBC_看最高版本号再和目标板上的同名文件对比。5.4 链接脚本里的静态化补全如果你发现程序虽然目标架构对了但还挂着几个动态依赖通常是编译器运行时没静态化。可以在程序的.pro文件里补链接参数QMAKE_LFLAGS -static-libstdc -static-libgcc -Wl,-Bstatic -lc -Wl,-Bdynamic这里-Wl,-Bstatic和-Wl,-Bdynamic是成对使用的包夹语法把-lc夹在中间强制静态链接其余仍可动态。全静态-static虽然也能做但 glibc 全静态会遇到 NSS名称服务切换的问题比如域名解析在静态程序里可能失效网络功能受影响。除非你确认程序不需要解析域名、不需要用户组查询否则不建议对 libc 做全静态。这个取舍值得说清楚qtbase 网络模块做 DNS 解析时会调用 glibc 的 NSS 机制而 NSS 是运行时通过dlopen加载libnss_dns.so等模块的。全静态链接的程序没有dlopen能力严格的静态环境DNS 解析就可能退化甚至失败。所以如果你的设备要用 QtNetwork 做域名访问链接时别用全-static打 libc。6. 部署、体积优化和一点后续扩展先说完整体积。一个带 Widgets、Network、SVG并且嵌了中文字体的静态可执行文件落在 25MB 到 45MB 之间是正常的。想压一压有几个方向configure 时加-optimize-size把-release里的调试信息彻底剥掉编译完成后aarch64-linux-gnu-strip hello只链实际用到的模块用不到 QtNetwork 就别在.pro里QT network字体裁子集。经过这几步一个纯界面程序压到 15MB 以内完全可行。strip这一步别忘。不 strip 的静态二进制里带着所有符号表体积能大出将近一倍。strip 之后再拷到目标板路径无所谓放哪都能跑这也是静态方案最舒服的地方。调试方面要提前留一手。strip 之前务必把带符号的版本存档否则线上出问题只能靠打印调试。更专业的做法是用objcopy --only-keep-debug把调试信息单独存成一个.debug文件再objcopy --add-gnu-debuglink建立关联这样发布的二进制是精简的排查时又能用gdb加载符号。这个流程在嵌入式项目里值得一开始就建好。后续如果设备支持 OTA静态方案还有个附加好处更新就是把一个新文件覆盖旧文件失败回滚也是换回旧文件没有库版本冲突这一层部署脚本能写得很简单。我在这类项目里的做法是保留两份可执行文件加减一个启动脚本判断几乎不出问题。要是后面设备要跑多个独立功能进程静态方案导致的体积重复就会开始显现那时再考虑改成动态或部分动态的混合模式把共享的那部分 Qt 库单独拎出来这是另一个话题了。
Qt5.14.2 aarch64 静态交叉编译与嵌入式部署实战
做嵌入式产品的人大概都遇到过这样的场面板子上跑的程序在开发机上一测就崩提示找不到 libQt5Core.so.5或者现场设备要升级脚本里写死了库路径结果一换文件系统整个界面就起不来。更头疼的是有些方案为了省空间把 Qt 库裁得七零八落删掉一个看起来没用到的插件 so程序就在某个特定操作下直接退出。说到底这些都是动态链接带来的耦合。Qt5.14.2 的 aarch64 静态交叉编译本质上要解决的就是这件事让一个可执行文件自己扛下所有依赖拷过去就能跑不用在目标板上维护一套 Qt 运行库。这篇手册写给已经会写 Qt 程序、但还没系统做过交叉静态编译的人也写给被动态库折磨过、想一次性把部署问题解决掉的同行。从工具链搭建到 configure 参数取舍再到静态插件导入和字体这些静态编译特有的坑我会按我实际趟过的路径讲一遍。1. 为什么选静态交叉编译先想清楚收益和代价1.1 动态部署踩过的那些坑动态链接的部署方式逻辑上是优雅的目标板存一份 Qt 运行库多个程序共享升级库就能统一修 bug。但落到实际产品里这份优雅经常变成麻烦。最常见的是库版本漂移——开发机装的是某个发行版自带的 Qt5.14.x目标板是另一套裁剪过的运行时.so的 soname 对得上符号版本却对不上运行时报一句莫名其妙的 version Qt_5 not found。其次是插件路径问题。Qt 的插件默认从可执行文件目录的platforms/、imageformats/等子目录加载打包时少拷一个libqjpeg.so用户上传 jpg 头像就失败少拷platforms/libqlinuxfb.so程序直接报 This application failed to start because no Qt platform plugin could be initialized。这类问题在实验室里很难复现因为它只在特定文件系统布局下出现。再有一个更隐蔽的目标板 rootfs 是只读的程序想在运行时动态加载库但库被放在了一个靠后的挂载点上启动顺序稍有偏差就加载不到。你临时改个环境变量能绕过可产品不会给你改环境变量的机会。静态编译把这些不确定性一刀切掉。所有用到的 Qt 代码、图片格式解析、字体渲染、平台抽象全部编译进最终的可执行文件运行时不再依赖外部 Qt 库和插件目录。代价也明确单个文件体积从几 MB 涨到几十 MB多个程序无法共享代码改一个 bug 就得整体重编。这些代价在嵌入式场景里往往是能接受的尤其是设备功能单一、更新频率低的时候。1.2 方案选型的几个关键决策决定做静态交叉编译之后还有几个岔路口要选。第一宿主机用哪个发行版。我不是在开玩笑这是真会踩坑的地方。Qt5.14.2 的源码对 glibc 版本和 GCC 版本有一定要求太新的发行版比如默认 GCC 13 的编译时会撞上一堆老代码的告警甚至报错。我一般倾向选一个稍保守的构建环境GCC 版本落在 9 到 11 之间比较省心。实在只能用新环境就准备几组补丁后面对应问题我会展开。第二用不用目标板的 sysroot。sysroot 是目标系统头文件和库的集合。静态编译理论上只需要-static链接 Qt 的库但因为 Qt 会依赖 zlib、libpng、freetype 这些第三方库如果没有 sysroot就得让 Qt 用自己源码树里带的版本。Qt 提供了一批-qt-*开关-qt-zlib、-qt-libpng等作用就是用自带的第三方库编译省去准备 sysroot 的麻烦。我的建议是能在 sysroot 里准备好的依赖尽量用 sysroot用得顺手且版本可控不好准备的比如 freetype、harfbuzz就用-qt-前缀让 Qt 自带减少对目标系统的假设。第三平台插件怎么选。aarch64 嵌入式设备常见的显示后端有 linuxfb、eglfs 两种。纯 framebuffer、没 GPU 的方案用 linuxfb有 GPU、跑 OpenGL ES 的用 eglfs。这个选择会直接影响 configure 里对 opengl 的处理也决定后面要不要静态导入QLinuxFbIntegrationPlugin还是QEglFSIntegrationPlugin。提示平台插件选错不会在编译期报错而是编译成功后一运行就提示找不到 QPA 插件。先确认目标板有没有 /dev/fb0、有没有 GLES 驱动再定插件别凭感觉。2. 编译环境与工具链的落地准备2.1 宿主机依赖包清单交叉编译 Qt 本身对宿主机的依赖不算多但少了任何一样都会在 configure 或 make 阶段卡住。以常见的 Debian/Ubuntu 系为例需要准备的包大致是这些sudo apt-get install -y \ build-essential perl python3 \ bison flex gperf \ libxkbcommon-dev libxkbcommon-x11-dev \ libglib2.0-dev libpixman-1-dev \ libfontconfig1-dev libfreetype6-dev \ zlib1g-dev libpng-dev libjpeg-dev \ pkg-config这里面有几个值得说明。perl和python3是 Qt 构建系统自己的脚本依赖具体点说Qt 有部分模块比如 qtvirtualkeyboard 的词库处理用到了 Pythonbison、flex、gperf用于生成解析器libxkbcommon-dev是 X11 和 Wayland 下键盘映射需要的。需要特别强调的是这些宿主机的开发包主要服务于 Qt 的 host 工具比如 moc、uic、rcc、host 版 qmake它们的编译走的是宿主机本地编译器和交叉编译目标程序是两条线。这一点很容易混淆你以为装了libfreetype6-dev就能给目标板用其实那只是让 host 侧不报错。目标侧真正用到的 freetype要么在 sysroot 里要么用-qt-freetype走 Qt 自带源码。2.2 aarch64 交叉工具链与 sysroot 的取得工具链我一般用 Linaro 或者 ARM 官方发布的 GNU toolchain版本挑比 sysroot 里 glibc 稍新一点但不要跨度太大的。判断标准很简单工具链的 glibc 版本不能高于目标板 rootfs 的 glibc否则静态链接出来的程序在运行时可能因为符号版本不兼容而直接段错误。拿到工具链后先做两件事。第一把它解压到固定路径比如/opt/toolchain/gcc-aarch64然后把bin加进PATHexport PATH/opt/toolchain/gcc-aarch64/bin:$PATH export CROSS_COMPILEaarch64-linux-gnu-验证aarch64-linux-gnu-gcc -v能打印出版本信息就说明路径没问题。第二准备 sysroot。如果你的工具链自带 sysroot很多发行版工具链内置了可以直接用它的路径如果没有就从目标板 rootfs 里把/usr/include、/usr/lib、/lib拷贝出来整理成一份干净的 sysroot 目录mkdir -p /opt/sysroot # 从目标板或 SDK 中同步头文件和库 rsync -a rootfs/usr/include/ /opt/sysroot/usr/include/ rsync -a rootfs/usr/lib/ /opt/sysroot/usr/lib/ rsync -a rootfs/lib/ /opt/sysroot/lib/这里要留意软链接。rootfs 里的/lib经常是/usr/lib的软链接直接 rsync 会把链接原样带过去甚至报错。用cp -a或者加-L参数把符号链接解引用成实体文件更稳。注意sysroot 不需要完整包含目标板所有内容只保留编译需要的头文件、静态库和必要的动态库即可。多余的脚本和配置文件反而会干扰 configure 的探测。整理完后general 建议是du -sh看一眼控制在几百 MB 到 1GB 之间比较合理。2.3 Qt5.14.2 源码的获取与目录规划Qt5.14.2 的源码官方发布为qt-everywhere-src-5.14.2.tar.xz体积在 500MB 上下解压后接近 3GB。很多人在搜qt5.14.2离线安装包下载其实那类在线安装器主要是给桌面开发用的交叉编译要的是这份 everywhere-src 源码包。源码里包含了 qtbase、qtdeclarative、qtsvg 等所有子模块一次编译就能出一整套。解压和目录规划mkdir -p /opt/qt-build cd /opt/qt-build tar -xf qt-everywhere-src-5.14.2.tar.xz mv qt-everywhere-src-5.14.2 src mkdir -p build-static install-static我习惯把源码、构建目录、安装目录三处分开放源码保持干净、可复用构建目录放 configure 生成的 Makefile 和中间产物安装目录就是最终make install的落点。这样即使一次编译失败删掉 build 目录重来源码和已安装内容都不受影响。install 目录最终会被打包进 SDK 或直接拷到开发机固定位置路径记得设成相对稳定、不带用户名的绝对路径否则 qmake 生成的路径里会写进你的 HOME团队其他人用起来就麻烦了。3. configure 参数逐条拆解与 mkspecs 定制3.1 核心配置参数的含义与取舍Qt 的 configure 脚本参数多到吓人但真正影响静态交叉编译成败的其实就那么十来个。下面这条命令是我在 linuxfb 方案下比较常用的一套cd /opt/qt-build/build-static /opt/qt-build/src/configure \ -prefix /opt/qt-build/install-static \ -hostprefix /opt/qt-build/install-static-host \ -opensource -confirm-license \ -release -static -optimize-size \ -xplatform linux-aarch64-gnu-g \ -device-option CROSS_COMPILEaarch64-linux-gnu- \ -sysroot /opt/sysroot \ -nomake examples -nomake tests \ -no-opengl \ -no-icu -no-iconv \ -qt-zlib -qt-libpng -qt-libjpeg \ -qt-freetype -qt-harfbuzz -qt-pcre \ -no-dbus -no-cups -no-feature-printdialog \ -skip qtwebengine -skip qtquick3d -skip qtmultimedia逐条说。-static是核心让 Qt 编译出静态库并在链接时把依赖打进去。-release关闭调试信息静态库本来体积就大debug 版会再翻几倍。-optimize-size让编译器偏向体积优化对嵌入式很实用如果你更在意运行速度可以换成-optimize-speed。-xplatform linux-aarch64-gnu-g指定目标平台描述文件。Qt5.14.2 的qtbase/mkspecs/下一般已经有linux-aarch64-gnu-g。如果没有某些裁剪过的子版本会缺就从linux-arm-gnueabi-g复制一份改名再改里面的qmake.conf。这个文件后面单独讲。-device-option CROSS_COMPILEaarch64-linux-gnu-把交叉前缀传给 mkspecs配合上面那个 xplatform 使用。它有讲究如果你的工具链前缀不是标准的aarch64-linux-gnu-比如带厂商名的aarch64-xx-linux-gnu-这里必须写全否则 configure 探测编译器时会失败。-sysroot /opt/sysroot告诉编译器到哪找目标系统的头文件和库。这个路径会同时影响 host 和 target 两套工具的编译务必确认它存在且结构正确写错了 configure 不会立刻报错而是在某个模块的 make 阶段冒出一堆找不到头文件的错误。-no-opengl是 linuxfb 方案的关键。没有 GPU 的设备完全不需要 OpenGL关掉能省一大块体积也避免因为找不到 GLES 库而编译失败。如果你的设备跑 OpenGL ES改成-opengl es2并且确认 sysroot 里有libGLESv2和libEGL的静态库——注意必须静态库动态库链接不进去。-no-icu -no-iconv是为了避开 ICU 这个大依赖。ICU 是国际化库提供排序、正则、日期格式化。Qt5 里 QtCore 在某些配置下会依赖它。交叉静态编译时 ICU 的静态库很难搞到用-no-icu直接去掉代价是部分国际化功能变为 Qt 自带的简化实现正则表达式仍能用走 Qt 自带的 QRegularExpression 或 PCRE对绝大多数设备界面没影响。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-harfbuzz -qt-pcre这一串意思是这些第三方库全部用 Qt 源码树里自带的版本编译成静态库。这样就不必在 sysroot 里准备它们的目标端版本极大降低了准备工作的复杂度。代价是版本稍旧但 Qt 官方选定的版本和 Qt 配合是验证过的稳定性反而更好。-nomake examples -nomake tests跳过示例和测试能省下大量编译时间。-skip qtwebengine这一条尤其重要qtwebengine 内部自带一个 Chromium交叉编译它是个独立的大工程和静态编译无关的时候一定要跳过否则会卡在拉取和编译 Chromium 上几个小时。3.2 mkspecs 的定制细节多数情况下linux-aarch64-gnu-g直接可用但你要理解它的结构出问题时才知道改哪。这个目录下通常只有一个qmake.conf# # qmake configuration for linux-aarch64-gnu-g # MAKEFILE_GENERATOR UNIX CONFIG incremental QMAKE_INCREMENTAL_STYLE sublib QT_QPA_DEFAULT_PLATFORM linuxfb include(../common/linux.conf) include(../common/gcc-base-unix.conf) include(../common/g-unix.conf) QMAKE_CC $${CROSS_COMPILE}gcc QMAKE_CXX $${CROSS_COMPILE}g QMAKE_LINK $${CROSS_COMPILE}g QMAKE_LINK_SHLIB $${CROSS_COMPILE}g QMAKE_AR $${CROSS_COMPILE}ar cqs QMAKE_OBJCOPY $${CROSS_COMPILE}objcopy QMAKE_NM $${CROSS_COMPILE}nm -P load(qt_config)其中最值得注意的是QT_QPA_DEFAULT_PLATFORM linuxfb。这一行决定了 Qt 编译时默认启用哪个平台抽象层也决定了最终链接进程序的是哪个平台的默认逻辑。如果你的设备走 eglfs这里要改成eglfs否则程序启动会去初始化 framebuffer 而非 EGL。这一项和 configure 里的 opengl 设置要对应linuxfb 配-no-opengleglfs 配-opengl es2。另外QMAKE_CC那几行用了$${CROSS_COMPILE}变量。这个变量要么来自环境变量要么来自 configure 的-device-option。你如果不想每次 configure 都传也可以直接把这几行里的$${CROSS_COMPILE}换成字面量aarch64-linux-gnu-。但我不建议写死因为换个工具链就要改文件容易忘反倒不如传参来得清楚。如果你的工具链没有处理好 sysroot还可能需要在这里追加QMAKE_CFLAGS和QMAKE_LFLAGS把--sysroot/opt/sysroot显式加进去。正常情况下-sysroot参数已经能覆盖但如果遇到链接阶段找不到-lc、-lpthread这类基础库八成是这里没配好。3.3 configure 执行与结果核对configure 会跑几分钟逐个探测编译器能力、第三方库存在性、平台特性。跑完之后重点看两处输出。第一看它是用什么编译器探测的。输出里应该能找到aarch64-linux-gnu-g的字样如果全是宿主机的g说明-xplatform或CROSS_COMPILE没生效赶紧停下来检查不然编译出来的“目标程序”其实是 x86 的白忙一场。第二看 configure 结尾的 summary。这个摘要会列出哪些功能启用了、哪些禁用了。重点确认这几点Build type: release、Static build: yes、-no-opengl对应的 OpenGL 是 disabled、libpng/libjpeg/zlib 用的是 bundled自带版本、ICU 是 no。任何一项不对就回到参数里找原因别带着错误的配置往下 make那样只会在几十分钟后以报错收场。提示configure 的参数被缓存进了config.summary和.qmake.cache改参数后建议重新运行一次完整的 configure而不是在旧目录上打补丁。参数变更如果不触发重新探测可能出现配置和实际不一致的情况。4. 编译、安装与静态产物的验证4.1 并行编译与内存管理configure 通过后就进入 make 阶段。这里的核心问题只有一个并行度。Qt 编译加上后面的静态链接阶段单个编译单元处理 qtdeclarative 时内存占用能飙到好几个 GB一上来就make -j$(nproc)很容易触发 OOM把编译进程杀掉报出virtual memory exhausted或者直接Killed。我的经验是分两段设置并行度。普通源文件编译阶段可以用核数的一半到全部make -j$(nproc) 21 | tee build.log一旦进入链接阶段尤其是qtdeclarative、qtsvg这些模块把并行度降到 2 到 4make -j4判断是否进入链接阶段看日志里LINK、ld出现的频率。或者干脆稳一点全程用-j4多花点时间换稳定。aarch64 的编译在中等配置机器上大概需要 1.5 到 3 小时视核数和模块数量而定。还有一个容易被忽略的点make中断后不要急着删目录重来。Qt 的 make 支持增量重新make -j4会从断点继续。但如果你在中断时改过 configure 参数那就必须重新 configure 甚至make distclean否则缓存会对不上。4.2 make install 与目录结构编译成功后make install安装后的目录结构大致是install-static/ ├── bin/ (host 工具比如宿主可用的一些辅助程序) ├── include/ (Qt 头文件) ├── lib/ │ ├── libQt5Core.a │ ├── libQt5Gui.a │ ├── libQt5Widgets.a │ ├── libQt5Network.a │ └── cmake/ (CMake 配置文件) ├── mkspecs/ ├── plugins/ │ ├── platforms/ │ ├── imageformats/ │ └── ... └── phrasebooks/注意lib/下全是.a静态库看不到.so这就是静态编译成功的标志。plugins/下的插件也是静态的.a文件。静态编译时插件不是靠目录加载的而是靠代码里显式导入后面细说。另外如果你在 configure 里没指定-hostprefixhost 工具会被装进同一个 install 目录。因为 host 工具是宿主机可执行的和目标静态库放在一起有点乱所以建议用-hostprefix单独指定把 host 工具和 target 库分开管理。4.3 用一个最小程序验证静态链接光看.a存在还不够得实际编一个程序验证。我一般用最简的 Qt Widgets 程序// main.cpp #include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(static build ok); label.show(); return app.exec(); }用安装出来的 qmake 生成 Makefileexport PATH/opt/qt-build/install-static/bin:$PATH qmake -query QT_VERSION # 应该输出 5.14.2 qmake main.cpp.pro make编出来之后先看文件类型和依赖file hello # 期望看到: ELF 64-bit LSB executable, ARM aarch64, statically linked ldd hello # 期望看到: not a dynamic executable如果file显示dynamically linked说明某个环节还在用动态链接回到 configure 确认-static是否生效如果显示了ARM aarch64但ldd还列出几个库那通常是libstdc、libgcc这些编译器运行时没静态化需要在链接时补上-static-libstdc -static-libgcc或者直接在 qmake 配置里让链接器全静态。这个细节下一节展开。5. 静态编译特有的坑与排查技巧5.1 插件必须显式静态导入这是静态编译和动态编译最大的差别也是新手最容易栽的地方。动态编译时Qt 会在运行时扫描plugins/platforms/目录自动加载插件静态编译时没有运行时扫描所有插件都得在代码里显式导入用Q_IMPORT_PLUGIN宏。平台插件是必须的。linuxfb 方案要导入#include QtPlugin Q_IMPORT_PLUGIN(QLinuxFbIntegrationPlugin)eglfs 方案则是#include QtPlugin Q_IMPORT_PLUGIN(QEglFSIntegrationPlugin)图片格式插件按需导入。如果你需要程序处理 jpg 图片就必须导入 JPEG 插件否则QPixmap::load(x.jpg)会静默失败Q_IMPORT_PLUGIN(QJpegPlugin) Q_IMPORT_PLUGIN(QGifPlugin)导入宏要写在有main()的源码里或者至少是会被链接进来的某个源文件中。写在头文件里然后被多个源文件包含会导致重复定义链接错误这一点要留意。导入的类名怎么确认去install-static/plugins/目录下看比如plugins/imageformats/libqjpeg.a对应的类名一般是QJpegPlugin规则是把libq前缀去掉、首字母大写加 Plugin。实在拿不准可以用nm libqjpeg.a | grep -i plugin找qt_plugin_instance_相关符号符号名里通常能反推出类名。提示漏导入插件的症状很隐蔽。程序能启动、能显示窗口但加载某种格式图片时返回空对象或者剪贴板功能失效却没有明确报错。遇到这类“某个功能静默失效”的问题先把可能相关的插件都Q_IMPORT_PLUGIN一遍。5.2 字体与运行时资源动态编译时Qt 通过 fontconfig 从系统字体目录里找字体。静态编译后程序跑在可能连字体目录都没有的环境里fontconfig 很可能无法工作。所以静态方案里字体必须自己带。两种做法。一是把 ttf 文件编进 qrc 资源程序启动时用QFontDatabase::addApplicationFontFromData加载QFile fontFile(:/fonts/NotoSansCJK.ttf); fontFile.open(QIODevice::ReadOnly); QFontDatabase::addApplicationFontFromData(fontFile.readAll());二是把 ttf 放在可执行文件旁边用addApplicationFont从磁盘路径加载。我倾向第一种因为资源编进二进制部署时又少一个外部依赖和静态编译的思路一致。字体的坑还不止于此。中文字体动辄十几 MB编进资源文件会让可执行文件体积再涨一截。实践中我会裁一个常用字库子集或者选一个体积较小的开源中文字体。这不是偷懒是嵌入式空间有限时的必要取舍。图片资源、翻译文件.qm同理都要用 qrc 的方式嵌进去不能用运行时从目录读取那套。5.3 常见报错速查下面这些错误我在不同项目里都碰到过整理成表方便对照。报错信息可能原因处理办法Unknown module(s) in QT: xcbqmake 用到了没编译的模块确认 configure 没有跳过相关模块或改用 linuxfb/eglfs 平台运行时no Qt platform plugin could be initialized平台插件没静态导入补Q_IMPORT_PLUGIN并确认类名正确链接时undefined reference to __cxa_throwlibstdc 没静态链接链接加-static-libstdc -static-libgccvirtual memory exhausted/ 进程 Killed并行度太高触发 OOM降低-j数值尤其链接阶段configure 报找不到编译器CROSS_COMPILE 前缀不对检查工具链前缀和 PATH运行时段错误且无输出目标板 glibc 低于工具链 glibc换用 glibc 版本不高于目标板的工具链Cannot find -lGLESv2缺少静态 GLES 库sysroot 中补静态库或改用-no-opengl关于 glibc 那一条我再补充一点。静态链接的程序虽然把 Qt 打了进去但libc层面它通常还是动态依赖的除非你连 libc 一起静态化那会带来一堆坑。所以目标板的 glibc 版本必须不低于工具链的 glibc。排查方法是在宿主机上执行aarch64-linux-gnu-strings /opt/toolchain/lib/libc.so.6 | grep GLIBC_看最高版本号再和目标板上的同名文件对比。5.4 链接脚本里的静态化补全如果你发现程序虽然目标架构对了但还挂着几个动态依赖通常是编译器运行时没静态化。可以在程序的.pro文件里补链接参数QMAKE_LFLAGS -static-libstdc -static-libgcc -Wl,-Bstatic -lc -Wl,-Bdynamic这里-Wl,-Bstatic和-Wl,-Bdynamic是成对使用的包夹语法把-lc夹在中间强制静态链接其余仍可动态。全静态-static虽然也能做但 glibc 全静态会遇到 NSS名称服务切换的问题比如域名解析在静态程序里可能失效网络功能受影响。除非你确认程序不需要解析域名、不需要用户组查询否则不建议对 libc 做全静态。这个取舍值得说清楚qtbase 网络模块做 DNS 解析时会调用 glibc 的 NSS 机制而 NSS 是运行时通过dlopen加载libnss_dns.so等模块的。全静态链接的程序没有dlopen能力严格的静态环境DNS 解析就可能退化甚至失败。所以如果你的设备要用 QtNetwork 做域名访问链接时别用全-static打 libc。6. 部署、体积优化和一点后续扩展先说完整体积。一个带 Widgets、Network、SVG并且嵌了中文字体的静态可执行文件落在 25MB 到 45MB 之间是正常的。想压一压有几个方向configure 时加-optimize-size把-release里的调试信息彻底剥掉编译完成后aarch64-linux-gnu-strip hello只链实际用到的模块用不到 QtNetwork 就别在.pro里QT network字体裁子集。经过这几步一个纯界面程序压到 15MB 以内完全可行。strip这一步别忘。不 strip 的静态二进制里带着所有符号表体积能大出将近一倍。strip 之后再拷到目标板路径无所谓放哪都能跑这也是静态方案最舒服的地方。调试方面要提前留一手。strip 之前务必把带符号的版本存档否则线上出问题只能靠打印调试。更专业的做法是用objcopy --only-keep-debug把调试信息单独存成一个.debug文件再objcopy --add-gnu-debuglink建立关联这样发布的二进制是精简的排查时又能用gdb加载符号。这个流程在嵌入式项目里值得一开始就建好。后续如果设备支持 OTA静态方案还有个附加好处更新就是把一个新文件覆盖旧文件失败回滚也是换回旧文件没有库版本冲突这一层部署脚本能写得很简单。我在这类项目里的做法是保留两份可执行文件加减一个启动脚本判断几乎不出问题。要是后面设备要跑多个独立功能进程静态方案导致的体积重复就会开始显现那时再考虑改成动态或部分动态的混合模式把共享的那部分 Qt 库单独拎出来这是另一个话题了。
