1. 为什么值得折腾静态交叉编译做嵌入式 Qt 的人早晚会撞上这个需求目标板是 aarch64 架构系统里没有 Qt 运行库甚至根本没有包管理器你不可能把一堆.so拷过去再配LD_LIBRARY_PATH凑合跑。这时候静态编译就是唯一体面的出路——把 Qt 核心库、平台插件、你写的业务代码全部塞进一个可执行文件拷过去就能跑不依赖目标机上的任何 Qt 环境。我这次要处理的目标环境是典型的国产化 ARM 平台aarch64 架构系统精简没有网络连yum源都是内网自建的。开发机是 x86_64 的 Ubuntu需要产出能在目标板上直接运行的 Qt 程序。整个链路涉及三块硬骨头交叉编译工具链的选型与验证、Qt 源码的静态配置裁剪、平台插件与第三方依赖的静态链接。任何一环出问题最后要么编译不过要么编译过了运行时报could not find the qt platform plugin linuxfb要么跑起来直接段错误。这篇手册面向的是已经会用 Qt 写业务、但对交叉编译和静态链接没有系统经验的开发者。我会从工具链准备一路讲到目标板验证把每一步的意图、参数含义、踩坑点都摊开说。你照着做大概率能一次跑通就算中途报错也能在排查章节里找到对应线索。需要提前说明的是静态编译 Qt 是个重活完整编译一次在普通四核机器上大约需要 40 分钟到 2 小时取决于你裁剪掉多少模块。所以配置阶段想清楚要什么、不要什么比盲目开编重要得多。2. 工具链选型与开发环境准备2.1 为什么工具链是第一个坑交叉编译的本质是在 A 架构上生成 B 架构的机器码这个转换全靠工具链完成。工具链选错了后面所有工作都是白费。aarch64 的工具链来源主要有几类芯片厂商随 SDK 提供的、Linaro 发布的通用版本、各发行版仓库里的gcc-aarch64-linux-gnu。我的建议是优先用目标板厂商提供的工具链因为它的 glibc 版本、内核头文件版本跟目标系统最匹配能避免大量编译通过但运行报 GLIBC 版本不符的问题。如果厂商没提供退而求其次用 Linaro 的gcc-linaro-7.5.0或gcc-arm-10.3系列这两个版本在社区里验证得最充分。发行版仓库里的工具链版本往往偏新glibc 也新静态链接时虽然 Qt 库本身是静态的但最终可执行文件仍会动态链接 glibc除非你用-static全静态但那会带来更多麻烦所以 glibc 版本必须低于或等于目标板的版本。验证工具链是否可用最直接的办法是编一个 hello world 拷到板子上跑# 假设工具链前缀是 aarch64-linux-gnu- aarch64-linux-gnu-gcc -o hello hello.c file hello # 输出应包含: ELF 64-bit LSB executable, ARM aarch64file命令确认架构正确后把hello拷到目标板执行。这一步能跑通说明工具链的 libc 跟目标系统兼容可以继续。2.2 环境变量与路径规划我习惯把工具链解压到/opt/toolchain/下然后通过环境变量引用而不是写死绝对路径。这样换机器、换版本时改动最小export TOOLCHAIN_PATH/opt/toolchain/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu export PATH$TOOLCHAIN_PATH/bin:$PATH export CROSS_COMPILEaarch64-none-linux-gnu-注意CROSS_COMPILE这个变量Qt 的configure脚本和很多构建系统都会读它。工具链前缀一定要跟实际文件名对齐比如你的编译器叫aarch64-none-linux-gnu-gcc那前缀就是aarch64-none-linux-gnu-多一个字符少一个字符都会导致找不到编译器。另外要规划好三个目录源码目录放 Qt 源码、构建目录shadow build跟源码分离、安装目录make install的产物。我强烈建议用 shadow build因为 Qt 源码树一旦被污染重新配置时残留的缓存文件会让你怀疑人生。目录结构大概这样/home/dev/qt-build/ ├── src/qt-everywhere-src-5.14.2/ # 源码 ├── build-aarch64/ # 构建目录 └── install-aarch64/ # 安装目录2.3 依赖库的交叉编译Qt 静态编译时如果启用了某些模块比如qtbase里的字体、图像格式会依赖第三方库zlib、libpng、libjpeg、freetype、libharfbuzz等。这些库也必须用同一套工具链交叉编译成静态库否则链接时会混入 x86_64 的.a文件报架构不匹配。以zlib为例交叉编译流程很标准./configure --prefix/home/dev/qt-build/deps-aarch64 make CCaarch64-none-linux-gnu-gcc ARaarch64-none-linux-gnu-ar make installfreetype稍微麻烦点它依赖libpng和zlib配置时要通过--with-zlibyes和--with-pngyes指定同时用CFLAGS和LDFLAGS把依赖库的路径传进去./configure --hostaarch64-none-linux-gnu \ --prefix/home/dev/qt-build/deps-aarch64 \ --with-zlibyes --with-pngyes \ CFLAGS-I/home/dev/qt-build/deps-aarch64/include \ LDFLAGS-L/home/dev/qt-build/deps-aarch64/lib提示所有第三方依赖统一装到同一个deps-aarch64前缀下后面 Qt 配置时只需要指定一个-I和一个-L管理起来清爽很多。3. Qt 源码配置静态编译的核心战场3.1 configure 参数逐条拆解Qt 5.14.2 的configure脚本参数极多但真正决定成败的就那么十几个。我把关键参数分成四类来讲。第一类是平台与工具链指定-xplatform linux-aarch64-gnu-g -device-option CROSS_COMPILEaarch64-none-linux-gnu- -sysroot /path/to/sysroot # 如果工具链自带 sysroot 则指定-xplatform指定的是qtbase/mkspecs/下的目录名。Qt 5.14.2 自带linux-aarch64-gnu-g这个 mkspec但里面的QMAKE_CC、QMAKE_CXX等变量默认写的是aarch64-linux-gnu-前缀。如果你的工具链前缀不同要么改 mkspec 文件要么用-device-option CROSS_COMPILE覆盖。我倾向于后者不动源码保持可复现性。第二类是静态编译开关-static -no-shared这两个是核心。-static让 Qt 库以静态形式构建-no-shared明确禁止生成动态库。注意有些模块比如qtwebengine根本不支持静态编译所以配置时要显式-skip qtwebengine否则 configure 阶段就会报错。第三类是模块裁剪-skip qtwebengine -skip qtwebview -skip qtquickcontrols -skip qt3d -skip qtcharts -skip qtdatavis3d -no-opengl -no-eglfs -no-xcb裁剪的原则是只留业务需要的。静态编译的产物体积跟启用的模块数量强相关全量编译出来的可执行文件轻松超过 100MB。如果你的业务只用 Widgets 和网络那把 Quick、3D、多媒体全砍掉体积能压到 20MB 以内。-no-opengl和-no-xcb在无桌面的嵌入式环境里几乎必开因为目标板根本没有 X 服务和 GPU。第四类是平台插件-qt-libpng -qt-zlib -qt-freetype -qt-pcre这几个-qt-xxx表示使用 Qt 源码树里自带的第三方库副本而不是去系统里找。静态编译时强烈建议这么干因为 Qt 自带的副本已经过验证跟 Qt 本身的兼容性最好省去大量交叉编译第三方库的麻烦。代价是编译时间变长但换来的是稳定性。3.2 一个可复用的完整配置命令把上面的参数组合起来我实际用的配置命令长这样../src/qt-everywhere-src-5.14.2/configure \ -prefix /home/dev/qt-build/install-aarch64 \ -xplatform linux-aarch64-gnu-g \ -device-option CROSS_COMPILEaarch64-none-linux-gnu- \ -static -no-shared \ -release -optimize-size \ -no-opengl -no-eglfs -no-xcb -no-glib \ -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre \ -no-feature-cups -no-feature-printdialog \ -skip qtwebengine -skip qtwebview -skip qt3d \ -skip qtcharts -skip qtdatavis3d -skip qtquickcontrols \ -skip qtserialport -skip qtmultimedia \ -nomake examples -nomake tests \ -confirm-license -opensource-optimize-size是给嵌入式场景准备的让编译器优先优化体积而非速度。-nomake examples -nomake tests能省掉大量编译时间除非你要跑 Qt 自带的测试用例否则没必要编。-no-feature-cups和-no-feature-printdialog砍掉打印相关功能嵌入式设备基本用不上。配置完成后configure 会输出一份摘要务必逐行检查。重点看三处QPA 插件列表确认linuxfb或eglfs在列、静态库列表确认-static生效、跳过的模块确认该跳的都跳了。摘要里如果出现WARNING: Using ... from system说明某个依赖没走 Qt 自带副本要去系统里找这在交叉编译场景下往往是隐患。3.3 编译与安装配置通过后就是make -j$(nproc)。这里有个经验首次编译不要开太高的并行度。-j8在四核机器上可能因为内存不足触发 OOM尤其是编译qtdeclarative这种大模块时。我一般用-j4起步稳定后再往上加。如果中途报错先看错误信息里有没有internal compiler error有的话基本是内存问题降并行度重试。编译完成后make install产物会装到-prefix指定的目录。检查一下install-aarch64/lib/下是不是一堆.a文件install-aarch64/plugins/platforms/下是不是有libqlinuxfb.a或libqeglfs.a。这两个目录是后面链接的关键。4. 业务工程接入静态 Qt 的实操4.1 qmake 工程的静态链接配置业务代码用 qmake 管理的话.pro文件里要加几行关键配置QT core gui widgets network CONFIG static QMAKE_LFLAGS -static-libgcc -static-libstdcCONFIG static让 qmake 生成静态链接的 Makefile。-static-libgcc -static-libstdc把 GCC 和 C 标准库也静态链进去避免目标板上缺libstdc.so.6的特定版本。但注意glibc 本身不建议全静态-static因为 glibc 的静态版本在涉及dlopen、NSS等功能时有已知问题而且体积巨大。保持 glibc 动态链接只要目标板的 glibc 版本不低于工具链的即可。平台插件必须显式导入否则链接器不会把libqlinuxfb.a拉进来运行时就会报找不到插件QTPLUGIN qlinuxfb如果用的是 eglfs就写QTPLUGIN qeglfs。这一行是静态 Qt 部署最容易漏的地方漏了之后程序能编译能启动但一创建窗口就崩报错信息就是那句经典的could not find the qt platform plugin linuxfb。4.2 用 CMake 管理时的差异现在越来越多项目用 CMakeQt 5.14.2 对 CMake 的支持已经比较完善。静态链接时CMake 的find_package(Qt5 ...)会去找Qt5Config.cmake这个文件在install-aarch64/lib/cmake/下。关键是要设置CMAKE_PREFIX_PATH指向安装目录并且用工具链文件指定交叉编译器。工具链文件aarch64-toolchain.cmake内容set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_C_COMPILER aarch64-none-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64-none-linux-gnu-g) set(CMAKE_FIND_ROOT_PATH /home/dev/qt-build/install-aarch64) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER这行很重要它保证 CMake 找moc、uic、rcc这些构建工具时用宿主机的版本而不是去交叉编译目录里找那里根本没有可执行文件只有库。LIBRARY和INCLUDE设为ONLY保证链接和头文件都从交叉编译产物里取。CMakeLists 里导入平台插件的方式跟 qmake 不同要用Qt5::QLinuxFbPlugin这样的目标find_package(Qt5 COMPONENTS Core Gui Widgets Network REQUIRED) target_link_libraries(myapp PRIVATE Qt5::Core Qt5::Gui Qt5::Widgets Qt5::Network Qt5::QLinuxFbPlugin)4.3 静态资源与插件路径处理静态 Qt 有个反直觉的点资源文件.qrc和翻译文件.qm在静态链接后路径解析逻辑跟动态库不一样。动态链接时Qt 会去install-aarch64/plugins/下找插件静态链接时插件已经编进可执行文件了但 Qt 仍会尝试从文件系统加载插件配置。解决办法是用Q_IMPORT_PLUGIN宏显式注册#include QtPlugin Q_IMPORT_PLUGIN(QLinuxFbPlugin) Q_IMPORT_PLUGIN(QJpegPlugin) Q_IMPORT_PLUGIN(QGifPlugin)这些宏放在main.cpp里确保链接器把对应的静态插件对象拉进来。图像格式插件尤其容易漏漏了之后程序能跑但加载 JPG 图片时静默失败返回空QPixmap排查起来很费时间。字体也是静态部署的常见坑。目标板如果没有fontconfig和系统字体Qt 会找不到任何字体界面上的文字全部显示为方块或空白。解决办法是把一个.ttf字体文件用 qrc 打进可执行文件然后在main里用QFontDatabase::addApplicationFontFromData()加载QFile fontFile(:/fonts/NotoSansCJK.ttf); fontFile.open(QIODevice::ReadOnly); int fontId QFontDatabase::addApplicationFontFromData(fontFile.readAll()); QFont font(QFontDatabase::applicationFontFamilies(fontId).at(0)); qApp-setFont(font);5. 目标板部署与运行验证5.1 可执行文件体积与依赖检查编译出来的可执行文件拷到目标板之前先在开发机上用file和ldd检查file myapp # ELF 64-bit LSB executable, ARM aarch64, statically linked (部分静态) aarch64-none-linux-gnu-ldd myapp # 应该只列出 libc.so.6、libm.so.6、libpthread.so.0 等基础库如果ldd输出里出现libQt5Core.so.5之类的说明静态链接没生效要回去检查.pro或 CMakeLists 里的配置。如果出现not a dynamic executable说明全静态链接了这时候要确认目标板的 glibc 是否真的不需要——全静态虽然省事但前面提过的dlopen问题要留意。体积方面一个只含 Widgets 和网络功能的静态 Qt 程序strip 之后大约 15-25MB。如果超过 50MB大概率是某些大模块没裁干净可以用aarch64-none-linux-gnu-size看看各段占用或者用nm统计符号来源。5.2 目标板运行环境准备静态程序虽然不依赖 Qt 库但仍依赖一些系统资源/dev/fb0帧缓冲设备、/dev/tty终端、/tmp可写目录。linuxfb 平台插件启动时会去打开/dev/fb0如果权限不够或设备不存在会报Failed to open framebuffer device。用ls -l /dev/fb0确认设备存在权限一般是crw-rw----运行程序的用户要在video组里。如果目标板用的是 systemd可以写一个简单的 service 文件让程序开机自启[Unit] DescriptionMy Qt App Aftermulti-user.target [Service] Typesimple ExecStart/opt/myapp/myapp EnvironmentQT_QPA_PLATFORMlinuxfb Restarton-failure [Install] WantedBymulti-user.targetQT_QPA_PLATFORMlinuxfb这个环境变量显式指定平台插件比依赖自动探测可靠。如果目标板有 GPU 且支持 EGLFS改成eglfs性能更好但需要对应的 GPU 驱动和libEGL支持。5.3 运行日志与崩溃定位静态程序崩溃时因为没有调试符号堆栈信息往往是一堆地址。发布版本建议保留一份带符号的可执行文件崩溃时用addr2line反查aarch64-none-linux-gnu-addr2line -e myapp.debug 0x400abc如果目标板支持gdb直接跑gdb ./myapp然后bt看堆栈最直接。但嵌入式板子上往往没有 gdb这时候可以在开发机上用gdbserver配合交叉 gdb 远程调试。启动程序时用gdbserver :1234 ./myapp开发机上aarch64-none-linux-gnu-gdb ./myapp然后target remote 板子IP:1234。Qt 自身的日志也很有用。设置QT_LOGGING_RULES*true打开全部日志或者针对特定类别qt.qpa.*true看平台插件加载过程。静态 Qt 的日志默认输出到 stderr如果程序是后台启动的记得重定向到文件。6. 常见问题速查与避坑经验6.1 编译期问题排查表报错信息根因解决方式cannot find -lQt5Core链接器找不到静态库检查-L路径是否指向install-aarch64/libincompatible Qt library (version ex50601)混用了不同版本的 Qt 库清理构建目录确认只链接一套 Qtunknown module in QT: serialport该模块被-skip了重新 configure去掉对应的-skipinternal compiler error并行编译内存不足降低-j数值或增加 swapundefined reference to dlopen全静态链接 glibc 导致去掉-static保留 glibc 动态链接incompatible Qt library这个报错特别常见本质是链接时混入了宿主机系统里的 Qt 库。排查方法是看链接命令里有没有/usr/lib/x86_64-linux-gnu/libQt5*.so有的话说明CMAKE_PREFIX_PATH或QMAKE_LIBDIR没设对系统 Qt 抢先被找到了。6.2 运行期问题排查表现象根因解决方式could not find the qt platform plugin linuxfb插件未静态导入.pro加QTPLUGIN qlinuxfb或代码加Q_IMPORT_PLUGIN界面全黑无显示帧缓冲设备权限或分辨率问题检查/dev/fb0权限用fbset确认分辨率中文显示为方块缺少中文字体qrc 打包 ttf用addApplicationFontFromData加载程序启动即段错误平台插件初始化失败用 gdbserver 抓堆栈检查QT_QPA_PLATFORM图片加载失败图像格式插件未导入Q_IMPORT_PLUGIN(QJpegPlugin)等6.3 几条用血换来的经验第一configure 摘要一定要逐行看。我遇到过好几次 configure 成功但摘要里某个依赖走了系统路径编译时才发现架构不匹配。摘要里的WARNING行不是摆设每一条都值得追查。第二静态编译的增量构建不可靠。改了 configure 参数后务必make distclean或直接删掉构建目录重来。Qt 的构建系统对配置变更的追踪不完善残留的.o文件可能导致新旧配置混用产生各种诡异链接错误。第三平台插件名要跟 Qt 版本对齐。Qt 5.14 里 linuxfb 插件的类名是QLinuxFbPlugin但早期版本可能是QLinuxFbIntegrationPlugin。用nm libqlinuxfb.a | grep Plugin确认实际符号名再决定Q_IMPORT_PLUGIN里写什么。第四交叉编译工具链的sysroot要理清楚。有些工具链自带 sysroot头文件和库都在工具链目录里有些则依赖宿主机的/usr/include。用aarch64-none-linux-gnu-gcc -print-sysroot看输出如果是空或/说明没有独立 sysroot这时候要特别小心头文件混用问题。第五发布前在目标板上跑一遍完整业务流程。开发机上用qemu-aarch64模拟运行只能验证基本启动帧缓冲、触摸输入、网络这些跟硬件强相关的功能必须在真实板子上验证。我踩过一次坑qemu 里跑得好好的到板子上触摸坐标全偏原因是触摸屏的坐标变换矩阵没配。7. 关于版本选择的一点个人看法Qt 5.14.2 是个 LTS 版本社区支持周期长静态编译的成熟度也高。有人会问为什么不直接上 5.15.2 或 Qt 6。我的经验是嵌入式项目优先选 LTS且优先选厂商验证过的版本。5.15.2 在静态编译上跟 5.14.2 差异不大但如果你用的 BSP 或 SDK 是基于 5.14 的贸然升级可能引入不必要的不确定性。Qt 6 的构建系统换成了 CMake静态编译的配置方式变化较大而且部分模块的静态支持还不完善除非有明确的新特性需求否则嵌入式场景没必要追新。另外提一句静态编译出来的程序虽然部署简单但升级维护成本高。每次改代码都要重新链接整个 Qt编译时间长而且多个程序无法共享 Qt 库每个可执行文件都带着一份完整的 Qt磁盘占用大。如果目标板存储空间充裕、且能保证 Qt 库版本一致动态链接反而是更灵活的方案。静态编译适合的是部署环境极度受限、升级频率低的场景这个前提想清楚了再动手能省下不少返工。