Qt 5.14.2 aarch64 静态交叉编译实战：从依赖库到部署

1. 为什么值得折腾 Qt 5.14.2 的 aarch64 静态交叉编译如果你手上有一块 Orange Pi CM5、树莓派 CM4 或者任何一块 aarch64 架构的板子又打算在上面跑一个带界面的 Qt 程序那你迟早会撞上交叉编译这堵墙。更麻烦的是如果目标板子存储紧张、依赖管理混乱或者你压根不想在板子上装一堆.so动态库那静态编译就成了绕不开的选项。Qt 5.14.2 这个版本在嵌入式圈子里口碑不错模块完整、bug 相对少、社区资料多配合 aarch64 静态交叉编译能产出一个几乎扔进去就能跑的单文件可执行程序。这篇文章要解决的核心问题很明确在 x86_64 的 Linux 开发机上用交叉编译工具链把 Qt 5.14.2 编译成 aarch64 架构的静态库最终让 Qt 程序在 ARM 板子上不依赖任何 Qt 动态库就能运行。听起来一句话实际做起来坑不少——工具链选型、configure 参数、静态库的依赖顺序、openssl 和字体库的处理每一步都能让你卡半天。适合谁看如果你已经会用 Qt Creator 写点界面程序懂基本的./configure make流程但对交叉编译只有模糊概念那这篇就是给你写的。我会把每一步的为什么讲清楚而不是甩一堆命令让你抄。当然如果你只是想快速拿到一个能用的工具链配置直接跳到第 3 节的参数表也行但我建议至少把第 2 节的选型逻辑看完否则出了问题你都不知道从哪查。先说结论性的经验Qt 静态交叉编译最难的不是编译本身而是依赖库的架构一致性。你的 zlib、libpng、openssl、fontconfig 全都必须是 aarch64 静态库而且编译时的--host和--prefix要统一规划否则链接阶段会报一堆 incompatible 或者 undefined reference。我踩过最惨的一次是 openssl 用了系统自带的 x86 版本结果 QtNetwork 编译通过、链接失败排查了整整一个下午。2. 整体方案设计与工具链选型逻辑2.1 静态编译和动态编译到底差在哪先把这个概念捋清楚不然后面很多选择你无法理解。动态编译时你的可执行文件里只存了函数调用的地址占位真正的代码在运行时才从.so文件加载。静态编译则相反所有用到的代码在链接阶段就被复制进了可执行文件。带来的直接后果是文件体积暴涨一个简单 Qt 界面程序从 2MB 变成 30MB 很正常但换来的是零运行时依赖——板子上不需要装 Qt 库不需要配LD_LIBRARY_PATH拷贝过去就能跑。对于嵌入式场景这个 trade-off 通常是划算的。板子存储便宜但依赖管理的时间和出错成本很贵。尤其是当你需要给多个不同配置的板子部署同一套程序时静态编译能省掉大量这个板子缺那个库的扯皮。不过静态编译有个硬性限制LGPL 协议下的 Qt 静态链接有合规要求。如果你要商业发布要么买商业授权要么确保提供目标文件让用户能重新链接。这一点自己心里有数就行本文只谈技术实现。2.2 工具链怎么选官方 vs 第三方aarch64 的交叉编译工具链主流有这么几个来源工具链来源典型前缀优点缺点Linaro 官方aarch64-linux-gnu-稳定、资料多版本更新慢ARM 官方 GNU Toolchainaarch64-none-linux-gnu-优化好、支持新特性下载需注册发行版自带aarch64-linux-gnu-装起来最省事版本可能偏旧Bootlin 预编译aarch64-linux-gnu-开箱即用、带 sysroot定制性一般我的建议是优先用 Bootlin 或者 Linaro 的预编译工具链因为它们自带完整的 sysroot省去了你自己去凑头文件和库的麻烦。Ubuntu 上直接apt install gcc-aarch64-linux-gnu g-aarch64-linux-gnu也能用但要注意它默认的 sysroot 可能和你的目标板 glibc 版本不匹配。选工具链时有个关键点容易被忽略glibc 版本要低于或等于目标板的 glibc 版本。比如你的板子跑的是 glibc 2.28那工具链的 glibc 就不能是 2.31否则程序在板子上会报GLIBC_2.31 not found。查工具链 glibc 版本的方法aarch64-linux-gnu-gcc -print-file-namelibc.so.6 # 然后对这个文件执行 strings /path/to/libc.so.6 | grep GLIBC_22.3 目录规划一开始就要想清楚交叉编译最忌讳边做边改路径。我建议在动手前就把目录结构定死后面所有--prefix都往这里塞# 假设工作根目录 export WORK_ROOT/opt/aarch64-qt # 工具链解压位置 export TOOLCHAIN/opt/toolchain/gcc-aarch64 # 交叉编译产物统一安装到这里 export SYSROOT_INSTALL/opt/aarch64-qt/sysroot # Qt 源码和编译目录 export QT_SRC/opt/aarch64-qt/src/qt-everywhere-src-5.14.2 export QT_BUILD/opt/aarch64-qt/build/qt-5.14.2这样规划的好处是所有第三方库zlib、openssl、libpng 等都装到SYSROOT_INSTALLQt 编译时只需要一个-I和-L指向它依赖关系一目了然。等哪天要升级某个库直接重编那一个不影响其他。注意SYSROOT_INSTALL这个目录名我故意叫 sysroot但它其实不是真正的 sysroot只是第三方库的安装前缀。真正的 sysroot 在工具链里。别搞混了。3. 依赖库的交叉编译实操Qt 不是孤岛它依赖一堆基础库。静态编译时这些依赖也必须是 aarch64 静态库。下面按依赖顺序一个个来。3.1 zlib最底层先编它zlib 是几乎所有图形库的底层依赖必须先编。它的 configure 脚本比较老派用环境变量传参cd /opt/aarch64-qt/src tar xzf zlib-1.2.11.tar.gz cd zlib-1.2.11 export CCaarch64-linux-gnu-gcc export ARaarch64-linux-gnu-ar export RANLIBaarch64-linux-gnu-ranlib export CFLAGS-O2 -fPIC ./configure --prefix$SYSROOT_INSTALL --static make -j$(nproc) make install这里-fPIC是关键。静态库虽然不涉及运行时重定位但 Qt 在链接时可能要求位置无关代码加上它省得后面报错。--static告诉 zlib 只生成.a文件。3.2 openssl最容易翻车的一个openssl 的交叉编译是新手杀手。它的 Configure 脚本需要你显式指定目标平台而且不同版本的平台名不一样。1.1.1 系列用linux-aarch64cd /opt/aarch64-qt/src tar xzf openssl-1.1.1w.tar.gz cd openssl-1.1.1w ./Configure linux-aarch64 \ --prefix$SYSROOT_INSTALL \ --cross-compile-prefixaarch64-linux-gnu- \ --openssldir$SYSROOT_INSTALL/etc/ssl \ no-shared no-tests no-asm make -j$(nproc) make install_sw几个参数解释一下no-shared只生成静态库no-tests跳过测试程序编译交叉编译时测试程序跑不了编了也白编no-asm禁用汇编优化因为汇编代码和具体 CPU 架构强相关交叉编译时容易出问题虽然会损失一点性能但稳定性优先。实操心得如果你用的是 openssl 3.x平台名要改成linux-aarch64依然可用但配置项有变化no-asm可能不生效需要改成no-asm加-DOPENSSL_NO_ASM。我建议 Qt 5.14.2 就配 openssl 1.1.1 系列兼容性最好。3.3 libpng 和 freetype图形渲染的基础libpng 依赖 zlibfreetype 依赖 libpng 和 zlib所以顺序不能乱# libpng cd /opt/aarch64-qt/src tar xzf libpng-1.6.37.tar.gz cd libpng-1.6.37 ./configure --hostaarch64-linux-gnu \ --prefix$SYSROOT_INSTALL \ --enable-static --disable-shared \ CPPFLAGS-I$SYSROOT_INSTALL/include \ LDFLAGS-L$SYSROOT_INSTALL/lib make -j$(nproc) make install # freetype cd /opt/aarch64-qt/src tar xzf freetype-2.10.4.tar.gz cd freetype-2.10.4 ./configure --hostaarch64-linux-gnu \ --prefix$SYSROOT_INSTALL \ --enable-static --disable-shared \ --with-zlibyes --with-pngyes \ --with-bzip2no --with-harfbuzzno \ CPPFLAGS-I$SYSROOT_INSTALL/include \ LDFLAGS-L$SYSROOT_INSTALL/lib make -j$(nproc) make installfreetype 这里我关掉了 bzip2 和 harfbuzz因为这两个不是必须的关掉能减少依赖链。如果你需要复杂的文字排版比如阿拉伯语那 harfbuzz 得加上但那就又多一层依赖。3.4 fontconfig字体查找的必需品Qt 在 Linux 上渲染文字依赖 fontconfig 来查找系统字体。静态编译时它也得是静态的cd /opt/aarch64-qt/src tar xzf fontconfig-2.13.1.tar.gz cd fontconfig-2.13.1 ./configure --hostaarch64-linux-gnu \ --prefix$SYSROOT_INSTALL \ --enable-static --disable-shared \ --with-expatno \ --disable-docs \ CPPFLAGS-I$SYSROOT_INSTALL/include \ LDFLAGS-L$SYSROOT_INSTALL/lib make -j$(nproc) make install--with-expatno是因为 expat 又是一个额外依赖fontconfig 不用它也能工作只是解析某些 XML 配置时功能弱一点。嵌入式场景够用了。4. Qt 5.14.2 的 configure 参数详解依赖库齐了重头戏来了。Qt 的 configure 参数有几百个但真正影响静态交叉编译的就那么几十个。我把关键参数分成几组来讲。4.1 平台和工具链指定cd $QT_BUILD $QT_SRC/configure \ -prefix $SYSROOT_INSTALL/qt5 \ -hostprefix $SYSROOT_INSTALL/qt5-host \ -xplatform linux-aarch64-gnu-g \ -device-option CROSS_COMPILEaarch64-linux-gnu- \ -sysroot /opt/toolchain/gcc-aarch64/aarch64-linux-gnu/libc \ -no-gcc-sysroot \ ...-xplatform linux-aarch64-gnu-g指定目标平台这个值对应qtbase/mkspecs/linux-aarch64-gnu-g/qmake.conf文件。Qt 5.14.2 自带这个 mkspec但里面的工具链前缀默认是aarch64-linux-gnu-如果你用的工具链前缀不同需要改这个文件。-sysroot指向工具链的 sysroot-no-gcc-sysroot是告诉 Qt 不要给 gcc 传--sysroot因为我们已经通过-sysroot处理了。这两个参数配合使用避免路径重复。4.2 静态编译和模块裁剪-static \ -static-runtime \ -no-shared \ -nomake examples \ -nomake tests \ -no-compile-examples \ -skip qtwebengine \ -skip qtwebview \ -skip qtquick3d \ ...-static是核心生成静态库。-static-runtime让 Qt 内部也尽量静态链接运行时。-nomake examples -nomake tests跳过示例和测试能省大量编译时间——Qt 全量编译在普通机器上要几个小时跳过这些能砍掉三分之一。-skip系列是模块裁剪。qtwebengine 基于 Chromium交叉编译几乎不可能成功直接跳过。qtquick3d、qtwebview 这些如果你不用也跳过。模块裁剪是静态编译的关键优化因为每多一个模块最终可执行文件就大一圈。4.3 功能开关哪些必须开哪些必须关-openssl-linked \ -I $SYSROOT_INSTALL/include \ -L $SYSROOT_INSTALL/lib \ -no-opengl \ -no-xcb \ -no-eglfs \ -linuxfb \ -qt-zlib \ -qt-libpng \ -qt-libjpeg \ -qt-freetype \ -qt-harfbuzz \ -fontconfig \ -no-icu \ -no-glib \ -no-dbus \ -no-cups \ -no-pch \ ...这一组是重灾区一个个说-openssl-linked表示链接 openssl 而不是运行时加载。静态编译必须用这个否则 QtNetwork 会在运行时找不到 openssl。-no-opengl如果你的板子没有 GPU 或者不需要 OpenGL 渲染关掉能省很多事。但如果你要用 QtQuick那 OpenGL 是必须的得改成-opengl es2并确保板子有对应的 GL 库。-no-xcb关掉 X11 支持嵌入式板子通常跑 framebuffer 或者 Wayland不需要 X11。-linuxfb启用 Linux framebuffer 支持这是最基础的显示后端几乎任何板子都支持。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-harfbuzz这几个是让 Qt 用自带的第三方库版本而不是用系统的。静态编译时强烈建议用 Qt 自带的因为 Qt 自带的版本经过了适配链接时不容易出问题。虽然我们前面编了 zlib 和 libpng但 Qt 内部用自己那份更省心。-fontconfig启用 fontconfig 支持这个必须开否则中文显示会出问题。-no-icu关掉 ICU 支持ICU 是个巨大的国际化库静态编译它非常痛苦而且嵌入式场景通常不需要完整的国际化支持。-no-glib -no-dbus关掉 glib 和 dbus这两个在嵌入式场景往往用不上关掉能减少依赖。-no-pch关掉预编译头交叉编译时 PCH 容易出问题关掉更稳。4.4 一个完整的 configure 命令把上面的拼起来就是一份可以直接用的配置$QT_SRC/configure \ -prefix $SYSROOT_INSTALL/qt5 \ -hostprefix $SYSROOT_INSTALL/qt5-host \ -xplatform linux-aarch64-gnu-g \ -device-option CROSS_COMPILEaarch64-linux-gnu- \ -sysroot /opt/toolchain/gcc-aarch64/aarch64-linux-gnu/libc \ -no-gcc-sysroot \ -static -static-runtime -no-shared \ -nomake examples -nomake tests -no-compile-examples \ -skip qtwebengine -skip qtwebview -skip qtquick3d \ -openssl-linked \ -I $SYSROOT_INSTALL/include \ -L $SYSROOT_INSTALL/lib \ -no-opengl -no-xcb -linuxfb \ -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-harfbuzz \ -fontconfig -no-icu -no-glib -no-dbus -no-cups -no-pch \ -no-feature-testlib \ -confirm-license -opensource-confirm-license -opensource是自动确认开源协议省得交互式提问。5. 编译、安装与验证5.1 编译过程与时间预期configure 通过后直接make -j$(nproc)。这里要有心理准备即使裁剪了模块Qt 静态编译在 8 核机器上也要 1.5 到 3 小时。我实测过一台 16 核的机器跳过 webengine 后大约 50 分钟。时间主要花在 qtbase、qtdeclarative、qtmultimedia 这几个大模块上。编译过程中如果报错最常见的是两类一是找不到某个头文件通常是-I路径没配对二是链接时 undefined reference通常是某个依赖库没编或者架构不对。排查方法# 查看某个符号在哪个库 aarch64-linux-gnu-nm -A $SYSROOT_INSTALL/lib/*.a | grep 符号名 # 查看库的架构 file $SYSROOT_INSTALL/lib/libssl.a # 应该显示 current ar archive如果是 x86 的会显示不同5.2 安装与目录结构make install之后$SYSROOT_INSTALL/qt5下会有完整的 Qt 安装qt5/ ├── bin/ # qmake 等工具注意这是 aarch64 的不能在 x86 上跑 ├── include/ # 头文件 ├── lib/ # 静态库 .a 文件 ├── mkspecs/ # 平台配置 ├── plugins/ # 插件静态编译时插件也是 .a └── translations/ # 翻译文件注意bin/下的 qmake 是 aarch64 架构的在 x86 开发机上跑不了。真正能在开发机上用的是$SYSROOT_INSTALL/qt5-host/bin/qmake这是 host 版本。5.3 用 qmake 编译一个测试程序写个最简单的 Qt 程序验证// main.cpp #include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Hello aarch64 static Qt); label.show(); return app.exec(); }# test.pro QT widgets SOURCES main.cpp用 host qmake 生成 Makefile$SYSROOT_INSTALL/qt5-host/bin/qmake test.pro make编译出来的可执行文件用file检查file test # 应该显示 ELF 64-bit LSB executable, ARM aarch64再用ldd检查动态依赖aarch64-linux-gnu-ldd test # 理想情况下只依赖 libc、libm、libpthread、libdl如果ldd显示依赖了libQt5Widgets.so之类的说明静态链接没生效回去检查 configure 参数。6. 常见问题与排查技巧实录这一节是我踩坑最多的部分整理成速查表。问题现象可能原因解决方法unknown module(s) in qt: serialport对应模块没编译或没安装检查 configure 是否 skip 了该模块重新 configurecannot mix incompatible Qt library混用了不同版本的 Qt 库清理 build 目录重新编译确保只用一套 Qt链接时undefined reference to SSL_xxxopenssl 没链接或架构不对确认-openssl-linked和-L路径程序在板子上报GLIBC_2.xx not found工具链 glibc 版本高于板子换低版本工具链或升级板子 glibc中文显示成方块fontconfig 没启用或字体缺失确认-fontconfig板子上放中文字体编译到一半内存不足并行编译占用内存过大减少-j数量或加 swapqmake报Project ERROR: Unknown modulemkspec 配置错误检查linux-aarch64-gnu-g/qmake.conf静态程序体积过大没裁剪模块或没 strip用aarch64-linux-gnu-strip处理6.1 关于 serialport 模块的坑热词里出现了unknown module(s) in qt: serialport这个我专门说一下。QtSerialPort 在 Qt 5.14.2 里是独立模块默认会编译但如果你 configure 时用了-skip qtserialport或者编译失败就会在项目里报这个错。解决方法是确认qtbase编译时 serialport 模块被包含或者单独编译 qtserialportcd $QT_SRC/qtserialport $SYSROOT_INSTALL/qt5-host/bin/qmake make make install6.2 静态插件的处理Qt 的插件比如图片格式插件、平台插件在静态编译时不会自动链接进程序。你需要在代码里显式导入#include QtPlugin Q_IMPORT_PLUGIN(QLinuxFbIntegrationPlugin) Q_IMPORT_PLUGIN(QJpegPlugin) Q_IMPORT_PLUGIN(QGifPlugin)或者在.pro文件里加QTPLUGIN qlinuxfb qjpeg qgif漏掉这一步的典型症状是程序能编译能运行但图片显示不出来或者界面根本不显示平台插件没加载。6.3 一个我踩过的坑sysroot 路径有次我编译 Qt 时-sysroot指向了工具链的根目录结果 Qt 去那里找 zlib 找不到报了一堆头文件缺失。正确做法是-sysroot指向工具链的 sysroot通常是.../aarch64-linux-gnu/libc而第三方库通过-I和-L单独指定。这两个路径是独立的别混在一起。7. 部署到目标板的注意事项编译出来的程序拷到板子上还有几个细节要注意。字体问题静态编译的 Qt 不会自带字体板子上需要有 fontconfig 能找到的字体。最省事的做法是在板子上建/usr/share/fonts/目录放一个中文字体比如文泉驿或者思源黑体然后跑fc-cache -fv刷新缓存。如果板子上没有 fontconfig 工具可以直接把字体路径写进 Qt 程序的QFontDatabase::addApplicationFont()。环境变量静态程序虽然不依赖 Qt 库但可能依赖一些环境变量。比如 framebuffer 设备节点export QT_QPA_PLATFORMlinuxfb export QT_QPA_FB_DRM1 # 如果用 DRM export QT_QPA_FONTDIR/usr/share/fonts权限问题访问/dev/fb0需要 root 权限或者把用户加到video组。这个在部署文档里一定要写清楚否则用户跑起来报 cannot open framebuffer 会一脸懵。strip 处理编译出来的可执行文件带调试符号体积可能上百 MB。部署前用aarch64-linux-gnu-strip处理一下aarch64-linux-gnu-strip --strip-unneeded test体积通常能砍掉 70% 以上。但记得保留一份带符号的版本用于调试别 strip 完发现问题没法查。8. 关于版本选择和后续扩展Qt 5.14.2 是个 LTS 版本但如果你在热词里看到qt-everywhere-src-5.15.10说明 5.15 系列也在被广泛使用。5.15 相比 5.14 主要是 bug 修复和一些小功能增强交叉编译的流程几乎一样configure 参数也基本兼容。如果你是新项目可以考虑 5.15.10但要注意 5.15 后期版本对 openssl 3.x 的支持更好如果你用 openssl 3.x建议直接上 5.15。至于qt5.12.10交叉编译5.12 更老但有些老项目还在用。流程和本文一样只是 mkspec 文件名可能不同需要自己确认。最后说一个实际部署中的小技巧把 Qt 的静态库和你的程序分开管理。静态库编译一次可以用很久程序改动频繁。建议把$SYSROOT_INSTALL整个打包备份下次换机器或者重装系统直接解压就能用不用重新编译那几个小时的 Qt。我自己就维护了一份这样的备份省了无数次重编的时间。