最近给一块ARM64工控板做人机界面程序在x86上跑得好好的交叉编译出来拷到板子上一会儿缺libQt5Core.so一会儿libstdc.so.6版本太旧动态库依赖问题层出不穷。后来干脆把Qt 5.14.2整套做成静态交叉编译编译器生成的可执行文件把所有依赖全都熔进一个文件拷过去就能跑。这套流程我前前后后折腾了一周踩了不少坑最后整理成一份可以照着抄的完整手册今天就分享出来。这篇文章适合的读者很明确手里有aarch64设备需要跑Qt界面程序想摆脱动态库依赖的嵌入式工程师或者暂时不用Qt但想把交叉编译环境吃透的朋友。内容从“为什么”讲起再给配置参数和完整命令然后讲应用编译与部署最后是问题实录。主机是x86_64 Ubuntu目标是ARM64 Linux环境整个过程都在终端里完成。1. 项目背景与应用场景1.1 什么是静态交叉编译交叉编译就是在x86主机上编译出aarch64目标架构的二进制程序。静态交叉编译更进一步要求程序依赖的所有库都以.a静态库形式链接进最终可执行文件而不是指望目标系统提供.so动态库。这样产出一个单文件拷到目标板子上就能运行。理解这个区别很重要。动态链接的Qt程序在开发机上可能跑得很顺但一旦部署到aarch64设备上会遇到一系列令人抓狂的问题目标系统没有Qt库、glibc版本比开发环境旧、之前装过的Qt版本冲突、LD_LIBRARY_PATH配错等等。静态交叉编译直接把这些麻烦挡在构建阶段运行时只有一个可执行文件不需要额外安装任何Qt组件。当然静态编译不是免费的午餐。代价是可执行文件体积大很多启动时占用的内存会多一些许可证方面也有讲究这些问题后面都会细说。1.2 为什么选择Qt 5.14.2选Qt 5.14.2不是一个随意的决定。Qt开源版本从5.15.0之后补丁版本不再直接开放离线安装包获取门槛变高。而5.14.2是5.14系列最后一个补丁版本稳定性经过大量生产环境验证API和Qt 6的差异虽然存在但就控件、布局、基础模块来说5.14.2已经足够成熟。更重要的是Qt 5.14.2的源码包自带linux-aarch64-gnu-g这套mkspec可以直接使用不用自己另外写交叉编译平台描述文件。对于ARM64设备这个版本对内存和CPU的占用比Qt 6温和不少很多老一点的工控板跑起来流畅度更好。有人可能会问为什么不直接上Qt 6我的体会是新项目可以认真评估Qt 6但存量项目、老旧BSP、长期维护的产品Qt 5.14.2依然是风险最低的选择。1.3 适用场景和基本思路适合用这套方案的项目大致有这么几类场景典型需求推荐方案工控HMI设备现场环境不可控不能依赖在线安装纯静态单文件交付医疗/车载设备合规要求高依赖列表必须透明静态交叉编译 完整文档多设备批量部署几十台设备系统版本不一致静态二进制无视.so版本差异启动盘/救援系统rootfs极小不带图形库静态Qt程序 linuxfb/offscreen我的整体思路是主机上用apt安装交叉工具链获取Qt 5.14.2源码通过configure参数裁剪掉不需要的模块强制使用Qt内置库然后编译安装到独立目录。最后用这个目录里的qmake交叉编译自己的Qt程序部署到aarch64板子验证。下面按步骤来。2. 主机环境与交叉工具链准备2.1 主机系统要求我在Ubuntu 22.04 x86_64上做完整套编译16GB内存磁盘预留了60GB。Qt源码包解压后大概2GB中间产物和安装目录加起来很容易超过20GB如果没做裁剪全量编译40GB都打不住。建议磁盘至少留40GB以上否则编译到一半磁盘满了前面的时间全白费。内存方面静态编译比动态编译吃得多因为静态库要处理大量目标文件。16GB内存用-j4编译相对安全如果用-j$(nproc)跑到8线程或16线程连接器可能把内存吃掉一半甚至触发OOM。后面我会强调编译并行数怎么调。主机系统不一定是UbuntuDebian、Fedora等都可以但命令会略有差别。Ubuntu最容易找到交叉编译包这也是我推荐用Ubuntu的原因。2.2 安装基础依赖先把编译需要的工具装上sudo apt update sudo apt install -y build-essential perl python3 git \ libfontconfig1-dev libfreetype6-dev \ libxkbcommon-dev libx11-dev libx11-xcb-dev \ libxcb1-dev libxcb-glx0-dev libxcb-icccm4-dev \ libxcb-image0-dev libxcb-keysyms1-dev libxcb-randr0-dev \ libxcb-render-util0-dev libxcb-shape0-dev libxcb-shm0-dev \ libxcb-sync-dev libxcb-util-dev libxcb-xfixes0-dev \ libxcb-xinerama0-dev libxcb-xkb-dev这些依赖的主要作用是让Qt的configure脚本在主机上能正常生成构建文件。有一点需要特别说明如果目标是纯嵌入式不使用X11上面部分xcb开发包并非必须装。但装上它们的成本很低而且某些Qt模块在configure阶段会做检测缺了反而会多出不少unable的提示安装省心。交叉编译工具链sudo apt install -y gcc-aarch64-linux-gnu g-aarch64-linux-gnu libstdc-10-dev-arm64-cross安装后检查版本和交叉目标aarch64-linux-gnu-g --version aarch64-linux-gnu-g -dumpmachine输出应为aarch64-linux-gnu如果显示x86_64说明装错工具了。2.3 交叉工具链和sysroot的关系使用apt安装的aarch64工具链自带一份基础sysroot路径通常在/usr/aarch64-linux-gnu里面有头文件和基本库。这个sysroot够不够用取决于目标系统的libc版本。如果开发板BSP自带了rootfs建议优先用BSP里的sysroot并通过--sysroot/path/to/rootfs传递给编译器这样编译出的程序与目标系统内核和C库版本更匹配。我的做法是先用apt工具链完成整条流程验证证明静态编译方案可行再切换到厂商BSP工具链做正式构建。厂商工具链往往还附带特定的硬件加速库如DRM、GBM依赖如果只用内核帧缓冲其实不需要它们。先写一个最小的hello.cpp确认工具链能正常交叉编译#include iostream int main() { std::cout aarch64 cross toolchain works! std::endl; return 0; }编译验证aarch64-linux-gnu-g hello.cpp -o hello-arm64 file hello-arm64正常会输出ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV)看到这个工具链就说明没问题可以进入下一步。3. Qt 5.14.2源码获取与目录规划3.1 下载源码包Qt 5.14.2的源码包是qt-everywhere-opensource-src-5.14.2.tar.xz从Qt官方下载地址或国内镜像站获取。Qt官方archive目录结构很稳定http://download.qt.io/archive/qt/5.14/5.14.2/国内镜像会同步这个目录下载速度通常更快。选一个离自己近的镜像即可。源码包大小约500MB解压后约2GB下载后建议做一下校验官方页面会给出SHA256避免拿到不完整的压缩包。解压mkdir -p ~/qt-src cd ~/qt-src tar -xJf qt-everywhere-opensource-src-5.14.2.tar.xz cd qt-everywhere-src-5.14.2这个目录就是之后构建的工作目录。3.2 目录规划与环境变量建议把所有构建产物都放在固定目录里方便后面的命令引用。我的规划是export QT_TOP~/qt-aarch64 export QT_SRC$QT_TOP/src export QT_PREFIX$QT_TOP/qt5.14.2-aarch64-static export PATH$QT_PREFIX/bin:$PATH mkdir -p $QT_TOP $QT_SRC $QT_PREFIXQT_SRC放解压后的源码QT_PREFIX是Qt安装前缀也就是编译完成后qmake、库、头文件的安装位置。所有构建命令都基于这些变量换目录时只需改一处。3.3 为什么单独设置安装前缀Qt的configure脚本支持-prefix指定安装位置。很多人默认安装在/usr/local/Qt-5.14.2但在交叉编译场景下这个位置很容易污染主机环境。单独放在一个本地目录有几点好处方便删除不需要sudo不碰系统目录。可以同时保留多个版本比如5.14.2和5.15.2互不干扰。后续编译Qt程序时直接把该目录里的qmakeexport PATH即可不会和主机上其它qmake冲突。我踩过的坑是一开始图省事没设prefix结果make install把静态库装到系统目录里后来想升级配置梳理半天也不知道哪些文件是Qt的。重新规划后清爽得多。4. Configure配置详解与静态裁剪4.1 configure参数为什么这么多Qt的configure脚本是整个编译过程的核心也是劝退很多人的地方。参数不是越多越好但也不能太少。对于静态交叉编译核心诉求是“尽量不依赖外部库尽量不编译不用的模块”。如果配置时少了一句-no-opengl后续可能要链接主机的OpenGL库交叉编译器找不到时直接报错如果没跳过qtwebengine会进入一个几十GB的代码库编译时间翻倍内存和磁盘都吃紧。所以配置阶段的关键是理解每个参数的意义然后根据目标设备做减法。4.2 推荐配置组合先给出一套我实测过的配置目标环境是无X11、无GPU的ARM64精简LinuxQt界面通过linuxfb帧缓冲显示。cd $QT_SRC ./configure \ -prefix $QT_PREFIX \ -xplatform linux-aarch64-gnu-g \ -release \ -static \ -opensource \ -confirm-license \ -no-dbus \ -no-alsa \ -no-pulseaudio \ -no-gtk \ -no-cups \ -no-opengl \ -no-eglfs \ -no-kms \ -no-gbm \ -no-xcb \ -no-fontconfig \ -linuxfb \ -qt-zlib \ -qt-libpng \ -qt-libjpeg \ -qt-freetype \ -qt-harfbuzz \ -qt-pcre \ -nomake examples \ -nomake tests \ -skip qtwebengine \ -skip qtwebview \ -skip qtwebchannel \ -skip qtdeclarative \ -skip qtquickcontrols \ -skip qtquickcontrols2 \ -skip qtscript \ -skip qtlocation \ -skip qtsensors \ -skip qtserialbus \ -skip qtmultimedia \ -skip qttools \ -skip qttranslations \ -skip qtdoc这个配置的主要思路-static静态编译。-release编译发布版本不加调试符号。-xplatform linux-aarch64-gnu-g告诉Qt使用交叉平台配置。-no-*关闭常见依赖项避免交叉编译时找不到库。-qt-*强制使用Qt源码内置的libpng、libjpeg、freetype、harfbuzz、pcre避免依赖外部开发包。-linuxfb保留linuxfb平台插件用于帧缓冲设备。-skip剔除用不到的大模块。4.3 关于xcb和GUI平台插件的重要说明如果目标板有X11服务器并且希望Qt程序运行在X11环境里那就需要xcb平台插件。但是静态交叉编译xcb插件非常麻烦因为它依赖libxcb及其一堆兄弟库还需要为aarch64目标单独编译静态版本。一个常见误区是在主机上安装了libxcb开发包configure时Qt检测到xcb后自动启用编译也能通过但最终可执行文件拷贝到板子上却报错could not find or load the Qt platform plugin xcb原因就是Qt只把xcb客户端库存在了主机路径没有打包进目标二进制文件静态编译的“静态”掺了水分。所以在嵌入式项目中如果完全不需要X11服务器最简单可靠的做法就是-no-xcb改用-linuxfb或-offscreen。如果确实要xcb建议直接使用Buildroot这样的工具链生成完整静态环境而不是手工搭建sysroot后者成本高得多。4.4 常用配置参数速查表参数作用注意事项-static生成静态库需要额外的授权合规支持-release发布版无调试符号结合-strip可进一步减小体积-xplatform指定交叉编译平台aarch64对应linux-aarch64-gnu-g-no-opengl不编译OpenGL模块如果不需要硬件加速推荐关闭-no-xcb禁用xcb平台插件无X11的嵌入式设备建议关闭-no-fontconfig不依赖系统字体配置使用Qt内置freetype可省一层依赖-linuxfb启用帧缓冲平台插件用于/dev/fb0这类设备节点-qt-freetype用Qt内置FreeType避免外部freetype版本问题-skip qtwebengine跳过WebEngine模块该模块体积超大一般不用就跳过-nomake examples不编译示例程序节省时间-nomake tests不编译测试程序节省时间配置完成后终端会显示一份编译摘要列出Qt各模块和单独编译的模块列表。记得重点看是否有linuxfb对应项如果显示disabled确认一下-linuxfb参数是否被正确识别。5. 编译安装全过程5.1 make并行度怎么调configure通过后会生成Makefile接着执行make。这里的并行数量直接决定编译时间但千万不能无脑拉满。make -j416GB内存下-j4是稳妥选择。如果内存更大的工作站可以试-j8但一旦看到virtual memory exhausted或者g: internal compiler error: Killed说明内存跟不上了马上降级。静态编译需要多次调用ar归档目标文件内存峰值比动态编译高宁可慢一点也不要中途OOM重来。编译时长取决于机器。我在i7-12700H上跑-j8大约40到50分钟完成如果4核老机器可能要做好等两三个小时的准备。硬盘用SSD和机械盘差距很大工作站有条件还是用SSD。5.2 make installmake install这一步把构建好的头文件、静态库、qmake和各类工具安装到$QT_PREFIX目录。安装过程比编译快很多一般几分钟内完成。完成后目录结构大致是$QT_PREFIX/ ├── bin/ │ ├── qmake │ ├── moc │ ├── uic │ └── rcc ├── include/ ├── lib/ │ ├── libQt5Core.a │ ├── libQt5Gui.a │ ├── libQt5Widgets.a │ └── ... └── mkspecs/看到lib目录下存在一堆.a文件说明静态Qt已经就绪。5.3 验证编译产物是否能用检查qmake版本$QT_PREFIX/bin/qmake -v正常输出QMake version 3.1 Using Qt version 5.14.2 in /home/xxx/qt-aarch64/qt5.14.2-aarch64-static/lib如果这里显示的路径不对比如指向系统Qt检查PATH环境变量确认/usr/bin/qmake没有被优先调用。还可以看qmake的配置信息$QT_PREFIX/bin/qmake -query重点看QT_CONFIG字段里是否包含static和linuxfb。包含就说明编译配置生效了。5.4 常见的configure反复问题如果在configure之后又改变了参数重新执行configure前务必清理旧配置make confclean如果不清理Qt会保留上次的cache新参数可能不生效产生很难定位的怪异错误。我遇到过改了-no-xcb后编译出的程序仍然带xcb插件就是因为没清干净。6. 交叉编译Qt应用并静态部署6.1 编写测试程序和pro文件下面用一个最简单的Qt Widgets程序验证整条链路。创建hello_qt目录写两个文件。main.cpp#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(h2Hello aarch64 static Qt/h2); label.resize(400, 200); label.show(); return app.exec(); }hello_qt.proQT core gui widgets TARGET hello_qt TEMPLATE app CONFIG static SOURCES main.cpp注意CONFIG static在编译Qt程序时也要明确静态链接。严格来说qmake从Qt库配置中已经知道静态但显式写上更保险尤其当同一个pro文件还要在动态Qt环境里编译时这个选项能避免“意外生成动态程序”。6.2 用交叉qmake编译export PATH$QT_PREFIX/bin:$PATH mkdir -p build_qt cd build_qt $QT_PREFIX/bin/qmake ../hello_qt.pro make如果一切顺利目录下会生成名为hello_qt的可执行文件。这里有个细节qmake在配置阶段已经记住了目标平台和编译器路径所以make时不需要再手动指定CC和CXX。如果某些环境变量污染了编译器路径可以在make时显式覆盖make CCaarch64-linux-gnu-gcc CXXaarch64-linux-gnu-g但标准情况下别这么干免得掩盖其它配置问题。6.3 检查是不是真正静态file hello_qt输出ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked, with debug_info, not stripped看到statically linked说明是静态链接。进一步验证是否完全没有动态段aarch64-linux-gnu-readelf -d hello_qt | grep NEEDED如果输出为空没有任何Shared library依赖说明除了一些内核级系统调用外所有用户态库都已打入二进制。这种文件部署到板子上最省心。6.4 部署到aarch64设备用scp或U盘把hello_qt拷贝到板子上赋予执行权限chmod x hello_qt如果板子有帧缓冲设备直接指定linuxfb平台运行QT_QPA_PLATFORMlinuxfb ./hello_qt如果板子当前没有显示器可以先用offscreen平台验证程序能正常启动QT_QPA_PLATFORMoffscreen ./hello_qtoffscreen模式不会显示窗口但程序能跑起来且不崩溃证明Qt核心组件和资源路径没大问题。6.5 字体问题别等部署后才头大静态Qt程序部署后最常见的现象是程序能启动但中文显示一堆方框。这是因为静态程序不读取主机上的fontconfig配置也没有跟随一套中文字体。解决有几个思路在目标板上放一个ttf字体通过QT_QPA_FONTDIR/usr/share/fonts指定字体目录。用Qt资源系统把字体打包进可执行文件并通过QFontDatabase::addApplicationFont(:/fonts/xxx.ttf)加载。部署时同步拷贝一套Noto或文泉驿字体到设备。我最常用的是资源文件方式一劳永逸。把字体qrc进二进制后目标板无需再配字体目录多设备分发也方便。7. 常见问题与避坑实录7.1cannot find -lGL或libGL.so这个错误说明Qt build里还有OpenGL相关模块启用或者应用pro中引入了opengl库。如果不需要OpenGL确认configure使用了-no-opengl并且检查应用pro中的QT行有没有多余的opengl。我在第一次编译时就漏了-no-openglconfigure生成了libQt5OpenGL模块后面连静态库都编译出来了但应用链接时找不到GL库折腾了很久才定位到根因。7.2 平台插件加载失败报错This application failed to start because no Qt platform plugin could be initialized.或could not find or load the Qt platform plugin xcb问题几乎都出在configure和运行时平台不一致。如果configure时留着xcb但目标板没有xcb库运行时就加载失败。解决是用-no-xcb配置或者用-linuxfb强制指定帧缓冲平台。另外程序运行前设置环境变量也可以排查QT_DEBUG_PLUGINS1 ./hello_qt这会打印插件搜索和加载过程能快速看出它是在找哪个目录的哪个插件。7.3Bad ELF interpreter或Exec format error这个一般不是Qt问题而是部署时把x86程序当成了aarch64程序。先用file检查本地文件确认架构。顺便确认交叉编译器是aarch64-linux-gnu-g而不是arm-linux-gnueabihf-g后者生成的是32位ARM程序。另外如果目标系统是32位内核却想跑64位静态程序也会失败。静态可执行文件对内核架构要求没有降低64位ELF只能跑在64位内核上。7.4 编译过程中出现virtual memory exhausted典型的OOM。解决方法是降低make并行度必要时在两台机器上分别构建或者给虚拟机扩大内存。交叉编译Qt最怕在make执行一小时之后突然Kill提前评估内存比事后补救省时间。7.5libstdc.so.6: cannot open shared object file虽然程序本身是静态的但如果工具链配置不彻底某些辅助程序不是最终应用可能还会链接动态库。检查程序运行链路特别是qt.conf和插件相关部分。最终交付的二进制用readelf -d确认没有NEEDED条目即可。7.6 可执行文件体积太大Qt静态编译一个简单Widgets程序轻松超过150MB剥掉调试符号能降到100MB左右aarch64-linux-gnu-strip hello_qt如果还嫌大可以做模块裁剪。configure时把不需要的feature通过-no-feature-...关掉例如-no-feature-concurrent -no-feature-xml不过feature裁剪需要阅读Qt源码配置项对每个功能逐个判断工作量不小。我建议先正常编译能跑起来后再优化体积别一上来就裁剪否则问题排查范围会变得很大。7.7 静态Qt的许可证合规注意事项这一点必须单独提。Qt 5.14.2开源版采用LGPLv3/GPLv3协议。LGPL允许动态链接Qt的商业应用闭源但如果静态链接Qt就有额外的义务你必须给用户提供重新链接Qt替换版本所需的信息比如目标文件、链接脚本等。GPL静态链接则要求整个应用以GPL协议开源。所以静态编译不是简单的技术选择还关系到产品合规。如果要做闭源商业产品又必须静态链接比较稳妥的方案是购买Qt商业授权如果坚持开源就要认真梳理协议义务。这个建议不构成法律意见正式决策前建议咨询专业律师。7.8 用qemu模拟验证静态程序没有目标板的时候怎么尽快验证静态Qt程序能不能跑装个qemu-user即可sudo apt install -y qemu-user-static aarch64-linux-gnu-readelf -d hello_qt | grep INTERP # 如果上面没有INTERP运行 ./hello_qt但纯静态程序的主机内核无法直接运行需要用qemu-aarch64显式执行qemu-aarch64 ./hello_qt如果程序没有使用板子专属设备节点这种方式能模拟大部分运行逻辑。linuxfb平台在qemu下可能访问不了/dev/fb0可以临时用offscreen平台验证逻辑。7.9 遇到的问题速查表现象可能原因处理方式configure找不到编译器PATH未加交叉工具链检查aarch64-linux-gnu-g是否可执行make报undefined reference外部依赖未裁剪干净在configure中增加-no-*或-qt-*运行时报xcb插件错误configure启用了xcb改用-linuxfb或-offscreen程序启动后无界面没有指定平台设置QT_QPA_PLATFORMlinuxfb中文字体显示方块没有字体文件部署字体或用资源qrc体积过大未strip且模块过多执行strip并裁剪不需要的模块链接时multiple definition库重复或顺序不对调整pro文件LIBS顺序7.10 我给新手的建议如果这是你第一次自己编译Qt不要追求一步到位先按我上面的配置跑通能出二进制能显示界面再考虑裁剪和优化。中间的日志保留好出问题时对照Qt官网文档和源码目录下的mkspecs去分析。交叉编译本身不复杂复杂的是一旦出错排查链很长需要耐心逐层定位。多准备几个小测试程序每完成一个环节就用file和readelf验证别攒到最后才检查。最后再分享一点个人体会静态交叉编译Qt 5.14.2这条路线一旦配置确定收益是长期的。构建脚本、环境变量、目录结构固定下来后团队里任何人拉下来都能快速复现产品迭代也不用反复和动态库依赖纠缠。虽然过程里被坑了好几次但把这套流程固化成团队资料之后后续移植到其它ARM平台、升级Qt版本都有了可以依赖的底子。如果你也在折腾类似的目标希望这份手册能帮你少走几个弯路。