2. 为什么选择 5.14.2 与静态交叉编译
先说说版本选择的问题。Qt 版本很多，5.15 之后商业版和开源版的边界变得很微妙，6.x 系列又在大刀阔斧地改架构。我在生产项目里长期用过 5.12、5.14、5.15 三个分支，最终选定 5.14.2 是有具体原因的。5.12 是 LTS 版本，稳定性确实好，但编译器和工具链相对老旧，对新处理器的优化支持一般。5.15 虽然是 LTS，但开源包下载受限，想拿到完整源码和二进制得走商业授权流程，对很多团队来说很麻烦。5.14.2 处于两者之间，既保留了 Qt 5 时代成熟的 qmake/qml 生态，又不会像 5.15 那样有授权上的坑。更重要的是，5.14.2 对 aarch64 架构的支持已经相当完善，包括 QPA 平台插件、OpenGL 相关的 EGLFS 支持、WebEngine 的 ARM 版本编译等，都有社区大量验证过的案例。
选择静态编译的理由更直接。工控、医疗、军工这类领域最常见的部署环境是完全隔离的内网，设备可能只有一块板子、一个触摸屏，连 ssh 都未必方便开，更别说到现场装一堆 so 动态库了。静态编译出来的可执行文件，理论上只依赖 libc 等极少数系统库，拷贝过去就能跑。这会极大地减少现场调试成本——你不需要核对目标板上 glibc 版本、检查 Qt 库路径、处理 LD_LIBRARY_PATH 环境变量。我见过太多同事在客户现场折腾动态库缺失的问题，经验是：能静态就静态，省下的时间足够你多写几百行业务代码。
不过静态编译也有代价，这一点后面会反复提到：第一，可执行文件体积会明显增大，一个简单的 Qt Widgets 程序静态编译后轻轻松松几十 MB；第二，任何依赖第三方库的功能，比如 OpenSSL、sqlite 插件、字体库，都需要在编译阶段一并静态链接进去，配置复杂度直线上升；第三，如果用了 LGPL 协议的库，纯静态链接在商业分发时存在合规风险，团队需要提前和法务确认。我的建议是：如果只是内部自用、部署在专用硬件上，静态编译是完全可以接受的方案。
3. 搭建交叉编译环境的完整步骤
3.1 宿主机准备与 Toolchain 安装
先交代我采用的宿主环境。我用的是一台 x86_64 架构的 Ubuntu 20.04 虚拟机，内存分配了 16GB，磁盘留了至少 80GB 空闲空间。为什么强调磁盘？因为 Qt 源码解压再加上编译产出，随便就是几十 GB。如果磁盘不够，编译到一半报 "No space left on device"，那种挫败感我经历过太多次了。
交叉编译工具链方面，针对 aarch64 目标，最常用的有两个选择：一是 Linaro 提供的 aarch64-linux-gnu 工具链，二是直接使用发行版仓库自带的交叉工具链。Ubuntu 20.04 的 apt 源里就有 gcc-aarch64-linux-gnu 和 g++-aarch64-linux-gnu，安装命令如下：
sudo apt update sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu安装完成后，验证一下工具链是否可用：
aarch64-linux-gnu-gcc --version aarch64-linux-gnu-g++ --version如果你看到类似aarch64-linux-gnu-gcc (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0的输出，说明工具链已经就位。我为什么用发行版自带的工具链而不是 Linaro？原因很简单：版本匹配。Qt 5.14.2 官方文档里明确支持 GCC 9 系列编译器，Ubuntu 20.04 自带的 GCC 9 正好在支持矩阵内。用太新或者太旧的编译器去编 Qt，可能会在链接阶段遇到各种莫名其妙的 ABI 不兼容问题，虽然一般都能绕过去，但没必要一开始就给流程增加不确定性。
还有一个容易忽略的点：工具链前缀。Ubuntu 的交叉工具链前缀是aarch64-linux-gnu-，在配置 Qt 时需要把前缀告诉交叉编译的 mkspec，否则编译器找不到。这一点在后面的 configure 阶段会具体体现。
3.2 疑难杂症：EABI 版本冲突的根本原因
实际编译过程中，我最常被问到的报错是这一条：
fatal: cannot mix incompatible Qt library (version ex50601) with this library这个报错翻译成人话就是：你正在链接的 Qt 库与当前程序编译时使用的 Qt 头文件版本不一致。ex50601这个编码对应的是 Qt 5.6.1 的版本号，注意，这并不代表你的电脑上装了 5.6.1，而是 Qt 的 qmake 在生成编译规则时，会把 qmake 自己编译时所用的 Qt 版本写进 Makefile 里。如果交叉编译时用了宿主机的 qmake 而不是交叉编译版本的 qmake，编译器就会用宿机 Qt 的头文件去编译你的程序，再链接到目标板的 Qt 静态库。宿机 Qt 头文件版本与目标板静态库版本一旦不一致，就会出现这个 fatal error。
我记得第一次踩这个坑时，整整查了一个下午。当时我用的命令是在源码目录里执行：
qmake && make问题就出在这个qmake上。系统默认的 PATH 里设置的 qmake 指向的是/usr/bin/qmake，而/usr/bin/qmake是 Ubuntu 自带的 Qt 5.12.8 工具。它生成的 Makefile 引用的头文件路径、编译器参数都基于 5.12.8。而我目标板静态库是 5.14.2，两个版本一混，链接器就毫不犹豫地报了 incompatible 错误。
正确的做法是：在 configure 完成 Qt 源码编译之后，必须使用交叉编译生成的 qmake 来构建你自己的应用工程。也就是$QT_BUILD_DIR/bin/qmake。有时候还需要设置环境变量QT_SELECT或者在构建时显式调用$QT_BUILD_DIR/bin/qmake /path/to/your/project.pro。确保 qmake 路径正确后，编译时 Qt 头文件和库文件才都来自同一个 5.14.2 源码树。
这个错误的另一个诱因是.pro文件里手动指定了LIBS += -L/path/to/host/qt/lib之类把宿机 Qt 库路径硬编码进去的配置。我的建议是：不要手动指定 Qt 相关路径，一切交给 qmake 从环境变量推导。如果确实需要加第三方库路径，用qtHaveModule和qtConfig来条件判断，别图省事写死。
3.3 Qt 5.14.2 源码获取与 configure 参数详解
获取 Qt 5.14.2 源码的方式很多，我推荐直接从官方仓库下载 tarball：
wget https://download.qt.io/archive/qt/5.14/5.14.2/single/qt-everywhere-src-5.14.2.tar.xz tar xf qt-everywhere-src-5.14.2.tar.xz cd qt-everywhere-src-5.14.2注意这个包名是qt-everywhere-src，它包含了 Qt 的所有模块源码。如果你只想编译其中一部分模块，也可以在 configure 时通过-skip参数跳过不需要的模块，比如 WebEngine 这种编译时间极长、依赖又多的模块，建议直接 skip。
configure 是整个流程中最重要的环节。一个合理的配置文件如下：
./configure \ -prefix /opt/qt/5.14.2/aarch64 \ -xplatform linux-aarch64-gnu-g++ \ -static \ -release \ -opensource \ -confirm-license \ -nomake examples \ -nomake tests \ -skip qtwebengine \ -skip qt3d \ -skip qtcanvas3d \ -skip qtpurchasing \ -skip qtvirtualkeyboard \ -no-opengl \ -no-icu \ -no-feature-cups \ -no-feature-dbus \ -no-feature-glib \ -qt-libpng \ -qt-libjpeg \ -qt-zlib \ -qt-pcre \ -qt-freetype \ -qt-harfbuzz \ -qt-sql-sqlite逐个解释关键参数的含义：
-xplatform linux-aarch64-gnu-g++：指定目标平台。这个 mkspec 在qtbase/mkspecs/linux-aarch64-gnu-g++目录下存在，是 Qt 官方提供的针对 aarch64 的配置。它会自动把编译器设置为aarch64-linux-gnu-g++。如果你用其他工具链，可能需要自定义 mkspec，后面会细说。-static：静态编译开关，这是本次任务的核心目标。-release：只编译 release 版本，不编 debug，节省时间。-opensource -confirm-license：接受开源协议，编过 Qt 的人都懂，没这两个参数 configure 会停下等你确认。-nomake examples -nomake tests：不编译示例和测试，省时间和磁盘。-skip qtwebengine：WebEngine 模块在 ARM 静态编译下非常折磨人，依赖 Python 2、Ninja、GN 等一堆工具，编译一次需要几个小时，而且经常失败。如果没有网页渲染需求，直接跳过。-no-opengl：如果你的目标板没有 GPU 或者不需要 OpenGL 加速，关掉它。开启 OpenGL 意味着要链接 libGL、libEGL 等库，静态编译时这些库必须能在工具链的 sysroot 里找到，配置很麻烦。纯 Qt Widgets 应用不需要 OpenGL。-no-icu：ICU 库体积大，编译慢，如果不需要复杂的文本排版和 Unicode 支持，关掉可以省大量时间。-no-feature-cups：打印支持，嵌入式板上基本用不到，关掉减少依赖。-no-feature-dbus：DBus 在嵌入式单进程环境下没用，关掉可以免去编译 DBus 库的麻烦。-no-feature-glib：glib 循环依赖很多，在 aarch64 交叉编译时尤其麻烦，无声需求直接禁用。-qt-libpng -qt-libjpeg -qt-zlib -qt-pcre -qt-freetype -qt-harfbuzz：这六个参数的意思是使用 Qt 源码树自带的第三方库，而不是依赖宿主机或 sysroot 里的系统库。这样做的好处是交叉编译时不需要额外安装目标平台的 libpng-dev、libjpeg-dev 等包，所有依赖都在 Qt 源码里编译，避免了 sysroot 不完整导致的链接错误。-qt-sql-sqlite：内置 sqlite 插件。大部分嵌入式应用都需要数据库能力，sqlite 是最轻量的选择，静态链接进去后程序直接可以操作 db 文件，不需要目标板安装任何东西。
configure 跑完之后，检查输出信息里有没有 error 或者 warning。重点看这几点：是否显示Building on: linux-g++，Building for: linux-aarch64-gnu-g++，确认目标平台正确；是否有Qt Sql drivers: sqlite，确保 sqlite 插件被启用；是否有Qt Network: no或不相关模块的提示，确认网络模块是按需编译。configure 过程大概需要几分钟，如果出现缺少依赖的报错，按提示安装对应包再重新跑。
3.4 多线程编译与常用故障排查
configure 成功之后，就可以正式编译了。强烈建议用make -j$(nproc)开启多线程编译。这里有个经验值：如果是 8 核 16GB 内存的机器，-j8比较合适；-j16有时候会因为内存不足导致编译进程被 OOM Killer 干掉。编译 Qt 静态库总体耗时在我的机器上大约是 40 到 60 分钟，具体取决于你开启了哪些模块。如果你加了-j$(nproc)后编译到一半崩溃，优先检查是不是内存不够用。
编译过程中常见的报错和排查思路我整理一个表格：
| 报错信息 | 问题原因 | 解决方案 |
|---|---|---|
g++: error: unrecognized command line option '-mfloat-abi=hard' | mkspec 里的浮点 ABI 参数与工具链不匹配 | 检查工具链的默认浮点 ABI，修改 mkspec 中的QMAKE_CFLAGS为-mfloat-abi=softfp或删除该参数 |
undefined reference to 'clock_gettime' | 较新 glibc 将 clock_gettime 移入 librt | 在 mkspec 或 .pro 文件中添加LIBS += -lrt |
cannot find -lGL | OpenGL 相关库缺失 | 确认是否真的需要 OpenGL，不需要就加-no-opengl；需要则安装 libgl1-mesa-dev 的 aarch64 版本并指定 sysroot |
No rule to make target '.../libQt5Core.a' | make 依赖顺序问题 | 先执行make module-qtbase再执行make |
cannot find -lts | 触摸屏库缺失 | 配置时添加-no-feature-tslib或在 sysroot 中安装 tslib |
编译完成后，执行安装：
sudo make install安装目录是 configure 时指定的-prefix，如果你不想污染系统目录，也可以不指定-prefix，默认会安装到源码树里的qtbase目录，后续使用相对路径引用。
4. 在目标板上的运行验证与常见坑
4.1 部署环境准备：sysroot 与运行库
交叉编译出的静态 Qt 程序运行时，仍然需要一套目标板的基础系统库，主要是 glibc、libstdc++、libm 等。这些库不是 Qt 自带的，而是由目标板的 Linux 发行版提供的。因此，交叉编译时工具链必须能够找到 aarch64 版本的这些库，也就是所谓的 sysroot。
Ubuntu 的交叉工具链默认 sysroot 在/usr/aarch64-linux-gnu目录下。检查一下：
ls /usr/aarch64-linux-gnu如果里面没有lib和usr/lib目录，说明 sysroot 不完整。安装以下包可以补充常见的运行时库：
sudo apt install -y libc6-dev-arm64-cross libstdc++-9-dev-arm64-cross除此之外，如果你的程序用到了 Qt 的某些功能（比如网络、加密、字体），可能还需要编译对应的第三方库。举个典型例子：Qt Network 模块的 HTTPS 支持依赖 OpenSSL，而静态编译 Qt 时默认不会自动带上 OpenSSL。你需要先为 aarch64 交叉编译一份 OpenSSL 静态库，然后在 configure Qt 时通过-openssl-linked参数指定库路径。这属于进阶需求了，我建议大多数场景先用-no-openssl或者运行时使用 HTTP 明文协议，避免过早陷入 OpenSSL 的配置泥潭。
4.2 平台插件：linuxfb 的启示与应用
刚把程序拷贝到目标板上运行，最常见的错误是：
qt.qpa.plugin: could not find the Qt platform plugin "linuxfb" in ""这个错误的本质是：Qt 的 QPA（Qt Platform Abstraction）插件层没有找到可用的平台插件。桌面 Linux 上，Qt 默认使用的是xcb插件，而你的程序是嵌入式设备，没有 X11 图形环境。此时 Qt 需要使用linuxfb、eglfs或者minimal等嵌入式平台插件。但静态编译时，平台插件不会自动包含进可执行文件里，必须通过-plugin参数显式告诉 Qt 加载。
解决这个问题有三个步骤：
第一步，确认 Qt 编译时确实生成了 linuxfb 插件。在安装目录里查找：
find /opt/qt/5.14.2/aarch64/plugins -name "*linuxfb*"如果不存在，说明 configure 时没有启用。检查配置输出里是否有linuxfb相关字样。若没有，需要重新 configure。
第二步，在源码里初始化 QApplication 之前，显式指定平台插件路径。最稳的方式是设置环境变量：
export QT_QPA_PLATFORM_PLUGIN_PATH=/opt/qt/5.14.2/aarch64/plugins或者在代码里调用：
qputenv("QT_QPA_PLATFORM_PLUGIN_PATH", "/opt/qt/5.14.2/aarch64/plugins");第三步，也是很多人忽略的：在静态编译下，平台插件需要被静态链接进程序。你需要在.pro文件中添加：
QTPLUGIN += qlinuxfb或者在代码里显式引用 Q_IMPORT_PLUGIN：
#include <QtPlugin> Q_IMPORT_PLUGIN(qlinuxfb)这样才能保证 linuxfb 插件被链接到最终可执行文件里，而不只是一个存在于文件系统里的 so 文件。
我实际测试中发现，在纯控制台环境下，用linuxfb配合-platform minimal可以快速跑起来，但触摸事件支持需要配置文件或者环境变量来指定设备节点。默认 linuxfb 插件会尝试读取/dev/input/event0作为触摸输入设备，如果你的触摸屏挂在别的设备节点，需要设置QT_QPA_FB_TSLIB或Tslib相关环境变量。
4.3 静态库体积优化与 strip 技巧
静态编译出来的程序体积普遍偏大，这在 ARM 嵌入式设备上可能是个敏感问题，尤其是 Flash 只有几十 MB 的板子。以一个空的 Qt Widgets 窗口程序为例，静态编译后：
- 不优化：体积约 18 MB
- strip 之后：体积约 12 MB
- strip 且禁用不需要的模块后：体积约 9 MB
strip 命令很简单：
aarch64-linux-gnu-strip your_program但是注意，strip 会使 gdb 调试信息失效。建议发布前单独保留一份未 strip 的版本用于现场故障排查，发布到设备上的是 strip 后的版本。
体积优化的另一个思路是裁剪 Qt 功能模块。如果你只用 Qt Core 和 Qt Gui，不碰 Widgets，编译出来的体积会小很多。在 configure 时通过-skip qtdeclarative -skip qtquickcontrols2 -skip qtgraphicaleffects等参数裁掉 QML 和 Quick 相关模块，这些模块体积占比很大。
我在实际项目里还做过一个更极端的操作：在 configure 时用-feature-*系列参数关闭单个特性。比如不需要拖拽功能就加-no-feature-draganddrop，不需要剪贴板就加-no-feature-clipboard，这些都能缩减静态库体积。不过关闭特性前要想清楚会不会影响业务功能，别上线后才发现某特性被裁掉了。
5. 我的实操记录与总结心得
回到文章最开始提到的那个版本号报错。经过排查和修正之后，我重新执行了整套流程，最终的编译命令和结果如下：
cd /opt/qt-everywhere-src-5.14.2 ./configure \ -prefix /opt/qt/5.14.2/aarch64 \ -xplatform linux-aarch64-gnu-g++ \ -static \ -release \ -opensource \ -confirm-license \ -nomake examples \ -nomake tests \ -skip qtwebengine \ -skip qt3d \ -skip qtcanvas3d \ -skip qtpurchasing \ -skip qtvirtualkeyboard \ -no-opengl \ -no-icu \ -no-feature-cups \ -no-feature-dbus \ -no-feature-glib \ -qt-libpng \ -qt-libjpeg \ -qt-zlib \ -qt-pcre \ -qt-freetype \ -qt-harfbuzz \ -qt-sql-sqlite make -j8 sudo make install整个过程在 16GB 内存的 Ubuntu 20.04 虚拟机上耗时约 50 分钟。安装完成后，我用一个最简单的 Qt Widgets 窗口程序做了最终验证：
// hi.pro QT += widgets SOURCES += main.cpp TARGET = hi// main.cpp #include <QApplication> #include <QLabel> int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label("Hello from aarch64 static Qt"); label.resize(320, 200); label.show(); return app.exec(); }交叉编译命令：
/opt/qt/5.14.2/aarch64/bin/qmake hi.pro make aarch64-linux-gnu-strip hi最终在目标板上直接执行./hi，屏幕上出现了预期的标签文字，触摸点击正常。这次从零搭建到跑通，算上踩坑时间，前后用了一个多星期。如果完全按照这篇文章的参数和步骤来，我估计三个工作日之内可以完成。
最后再分享一个小技巧：如果你的项目需要在多个目标平台（比如 x86_64 工控机和 aarch64 板卡）之间切换，建议把所有 Qt 构建配置写成一个 shell 脚本放到版本库里。每次切换平台时，只需要执行不同参数的同名脚本，生成的 qmake 互不干扰，团队协作时别人按脚本一跑就能复现环境，省得口口相传踩版本坑。我在实际项目中靠这套脚本，把新人的环境搭建时间从两个星期压缩到了两天。
