1. 为什么你需要一份完整的 Qt aarch64 静态交叉编译手册先说结论在 ARM 设备上跑 Qt 应用如果你不想背着一堆 .so 到处配置环境变量、不想在客户现场被缺失依赖折腾到怀疑人生那静态交叉编译是你迟早要跨过去的一道坎。我这次做的是 Qt 5.14.2 在 aarch64 架构下的静态交叉编译目标板是 ARMv8 平台宿主编译机用的 Ubuntu 20.04 x86_64。从安装交叉工具链、配置 sysroot 到最后把二进制丢到板子上跑起来整个流程从头走了两遍踩了不少坑这篇手册就是把这两遍的经验全部沉淀下来给后来的人当一份可以直接抄作业的参考。先说清楚这个手册解决的是什么问题第一Qt 官方没有直接提供 aarch64 平台下的静态库安装包你必须自己用源码编译这一点和桌面版 Windows/Linux 的做法完全不同第二交叉编译涉及工具链、目标系统根文件系统sysroot、目标平台依赖库三个维度任何一个环节版本不匹配都会导致链接阶段报出一堆莫名其妙的错误第三Qt 5.14.2 属于 LTS 版本相对稳定且不强制要求 C17如果你的项目还跑在老旧的 ARM 板卡 Linux 系统上这个版本是一个很务实的选择。如果你正在做嵌入式 Qt 应用开发、车载方案或者国产化 ARM 平台适配这篇文章就是照着做就能跑通的完整路径。顺便回应一下很多人在搜索“qt 交叉编译环境”时遇到的困惑网上关于 Qt 5.14 的教程不少但大多数讲的是 x86 平台动态编译或者针对 armv732位的交叉编译一旦换成 aarch64会冒出至少四类问题——工具链前缀不同aarch64-linux-gnu- 而不是 arm-linux-gnueabihf-、库依赖从 lib/arm-linux-gnueabihf 换到了 lib/aarch64-linux-gnu、静态编译时 zlib/png/openssl 等组件反复冲突、以及部署阶段因为 glibc 或 Cairo 等系统库仍然动态链接而功亏一篑。本文会把这四个坑连同解决方案全部覆盖掉在实操层面直接给你参数和命令不铺垫废话。2. 编译环境搭建与前置条件2.1 宿主机与目标板基础信息我用的宿主机是 Ubuntu 20.04.6 LTS内核 5.4 以上x86_64 架构。为什么选 20.04因为 Qt 5.14.2 官方支持列表里对 glibc 2.31 和 GCC 9.x 有较好的兼容性而 Ubuntu 20.04 默认环境恰好满足这两个条件不需要额外折腾太多。若你使用 Ubuntu 22.04 或者 Debian 12系统默认 GCC 11/12 在编译旧版本 Qt 源码时可能会触发“-stdc17 混用”“Qt Xcb 模块编译失败”这类怪问题处理起来成本会高于直接上手 20.04。目标板信息aarch64 架构ARMv8板卡厂商的 BSP 基于 glibc 2.28内核版本 4.19。板卡上的根文件系统我单独提取出来作为交叉编译 sysroot具体提取方法和要点见下一节。如果你手里没有现成的 sysroot也可以从开发板烧录镜像里解包或者直接下载厂商提供的交叉 SDK例如 Linaro 的 aarch64 工具链会附带一个预构建 sysroot只是里面一般只有基础库Qt 运行依赖的 libicu 等需要额外补充。硬性配置建议编译 Qt 这种巨型项目建议宿主机的内存不低于 8GB。我第一次用 4GB 虚拟机编译在 -j4 并行度下直接把系统内存打满导致 perl 进程和 moc 进程被杀编到 qtbase 就失败。如果想要舒服一点16GB 内存、-j8 并行qtbase 加 qtdeclarative 加 qtmultimedia全部编完大约 90 到 120 分钟属于可以接受的范围。2.2 交叉编译工具链选择与安装交叉编译 aarch64 的工具链可选方案不少常见的有Linaro GCC 工具链gcc-linaro-7.x 或 9.x支持 aarch64-linux-gnuARM GNU Toolchainarm-gnu-toolchain-11.x 之后版本命名改成 arm-gnu-toolchain-xUbuntu 自带交叉工具链gcc-aarch64-linux-gnu版本随系统源更新我最终选用的是 Ubuntu 自带的 gcc-aarch64-linux-gnu版本为 9.4.0。理由很简单自带的工具链与系统 glibc 版本匹配度最高而且用 apt 安装能顺手解决 cpp、binutils 等一组配套依赖不用手工配置 PATH。安装命令sudo apt update sudo apt install gcc-aarch64-linux-gnu g-aarch64-linux-gnu安装完成之后验证一下工具链是否可用aarch64-linux-gnu-gcc --version aarch64-linux-gnu-g --version这里有个小经验如果后续编译 Qt 时遇到“cannot find -lstdc”“cannot find -lgcc_s”之类的报错不要慌张优先检查工具链是否安装完整因为 Ubuntu 把 aarch64 的 libstdc 放在 g-aarch64-linux-gnu 这个包里面只装 gcc 不装 g 会缺一整套 C 运行库。另一个重要组件是交叉编译版本的 pkg-config。在 Ubuntu 20.04 上直接安装sudo apt install pkg-config-aarch64-linux-gnu这个包会提供一个名为 aarch64-linux-gnu-pkg-config 的包装脚本在配置 Qt 和后续编写工程时需要把 PKG_CONFIG 环境变量指到它否则 configure 阶段检测 xcb、libpng 时会把宿主机的 .pc 文件路径混进来最终生成错误的链接参数。2.3 sysroot 的获取与目录结构sysroot 是指目标板根文件系统的拷贝作用是在交叉编译时提供给编译器和链接器一套与目标板一致的基础库头文件和 .so 文件。获取方式有两种从开发板镜像里直接解包。通常厂商会提供 .img 镜像文件可以用 debootstrap、qemu-nbd 或者直接用 file 命令识别镜像格式后用 7z 解包。如果板卡支持联网直接在板子上拷贝。例如用 rsync 把 /lib、/usr/lib、/usr/include 目录同步回来。我用的是第二种方式因为手里的板子能开机联网操作最快rsync -avz root板卡IP:/lib sysroot/ rsync -avz root板卡IP:/usr/lib sysroot/usr/ rsync -avz root板卡IP:/usr/include sysroot/usr/同步时必须注意保留符号链接不要加 -L 参数把软链解开否则 sysroot 里 /lib/aarch64-linux-gnu 目录下的 .so 全部变成常规文件后续调试和部署阶段很容易出问题。另外/usr/local 下如果有额外安装的库也要一并同步。最终形成的 sysroot 目录结构大概是sysroot/ ├── lib/ │ └── aarch64-linux-gnu/ │ ├── libc.so.6 │ ├── libm.so.6 │ ├── ld-linux-aarch64.so.1 │ └── ... └── usr/ ├── include/ │ ├── aarch64-linux-gnu/ │ └── ... └── lib/ ├── aarch64-linux-gnu/ └── ...后续所有编译操作都会用 --sysroot 参数指向这个目录因此建议把它放到稳定的路径例如 /opt/sysroot/aarch64-linux-gnu并且设置一个环境变量方便调用export SYSROOT/opt/sysroot/aarch64-linux-gnu注意sysroot 中必须保留 ld-linux-aarch64.so.1 动态链接器。如果你发现板卡根文件系统里这个文件丢失可以尝试从相同芯片平台的系统镜像中提取也可以直接用工具链中的 /aarch64-linux-gnu/libc/ 拷贝一份但版本必须与板子的 glibc 匹配否则部署出来动态加载直接崩。3. Qt 5.14.2 源码获取与关键编译选项解析3.1 下载源码并校验完整性Qt 5.14.2 的源码包在官方下载站点 archive 目录下当前网络上有大量“qt 下载”“qt 5.15.2 下载”“qt 离线安装包下载5.14”的搜索结果如果你需要访问官方仓库直接去 Qt 官方 Archive 路径查找 qt-everywhere-src-5.14.2.tar.xz 即可。下载之后强烈建议做一次 SHA1 校验避免压缩包断点损坏导致编译过程中莫明其妙报语法错误。wget https://download.qt.io/archive/qt/5.14/5.14.2/qt-everywhere-src-5.14.2.tar.xz sha1sum 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这里多说一句为什么选 5.14.2 而不是更新的 5.15.2 或 6.x主要原因有两个。第一5.14.2 是最后一个支持“传统 qmake 体系 官方离线安装包”组合的 LTS 版本很多第三方的嵌入式 BSP 或老项目代码都在这个版本上验证过第二从 5.15 开始Qt 公司调整了开源版下载渠道和更新策略离线源码包的获取不如 5.14.2 省心。如果你的项目没有硬性要求使用 5.15 的新特性5.14.2 在嵌入式 Linux 场景下会更稳定。3.2 目标平台依赖库的梳理交叉编译 Qt 时最费时间的就是依赖库的准备。对于 aarch64 静态编译关键依赖大致如下zlib基础压缩库几乎必选。libpng / libjpeg图像格式支持Qt GUI 常见依赖。freetype / fontconfig字体渲染很多嵌入式板子不带静态编译时建议编进 Qt 库中。openssl如果需要 https 或加密传输必须提前准备好 aarch64 版本。sqlite3一般嵌入式会用到。libicuTextCodec 和 QLocale 的底层依赖如果你不做国际化需求可以关掉但建议保留。libxcb 系列xcb-xlib、xcb-util 等若你的板子跑的是带 X11 的桌面环境这部分必须保留如果是纯 framebuffer 或者 eglfs则可以跳过。在开始 configure 之前先用文件搜索的方式确认 sysroot 里有没有这些库的 .pc 文件。例如find $SYSROOT -name *.pc如果缺少某个库可以在 sysroot 中从板子的软件源安装也可以在宿主机上交叉编译一份后拷贝进 sysroot。实操上我更推荐后者的进阶版直接把需要的第三方库以源码方式放到 Qt 工程三分支编译目录由 Qt 的 configure 流程统一处理这样最省心。3.3 configure 参数的选择逻辑与完整命令标准 aarch64 静态编译 configure 命令如下mkdir build cd build ../configure \ -prefix /opt/qt-aarch64-static \ -xplatform linux-aarch64-gnu-g \ -release \ -static \ -opensource \ -confirm-license \ -nomake examples \ -nomake tests \ -no-compile-examples \ -skip qtwebengine \ -skip qtwayland \ -skip qtscript \ -skip qtquick3d \ -dbus-linked \ -openssl-linked \ -sql-sqlite \ -qt-zlib \ -qt-libpng \ -qt-libjpeg \ -qt-freetype \ -qt-pcre \ -no-opengl \ -no-eglfs \ -no-linuxfb \ -no-kms \ -no-gbm \ -no-xcb \ -- \ -DCMAKE_SYSROOT$SYSROOT \ -DCMAKE_TOOLCHAIN_FILE../toolchain.cmake参数逐个解释-prefix最终安装路径建议独立目录避免污染系统目录。-xplatform linux-aarch64-gnu-g这是 Qt 内置的 mkspec专门用于 aarch64 交叉编译。在 qtbase/mkspecs 目录下可以看到这个文件。-static核心中的核心没有这个参数其他全部免谈。-release去掉调试符号减少编译时间和产物体积。-opensource -confirm-license开源版许可确认。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre强制 Qt 使用源码包自带的第三方库避免和 sysroot 里的对应库打架。这是静态编译最稳妥的策略不然链接的时候会遇到一堆“duplicate symbol”或“undefined reference”。-no-opengl -no-eglfs -no-linuxfb -no-kms -no-gbm -no-xcb如果你不需要图形显示把这些全部关闭可以大幅降低依赖复杂度。实测目标板上只需要纯逻辑计算 网络通信用这一组参数编出来的 Qt 库体积比开启 xcb 时少了约 30%。-openssl-linked如果目标板代码需要 https 调用用这个选项让 Qt Network 静态链入 OpenSSL。相应地需要提前准备 aarch64 OpenSSL 静态库具体方法见 3.4。-dbus-linkedQt 的 D-Bus 模块使用静态链接。嵌入式应用如果不需要 D-Bus可以改为 -no-dbus省一堆编译时间。另外要准备一个交叉编译 toolchain.cmake 文件内容大致如下set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g) set(CMAKE_SYSROOT $ENV{SYSROOT}) set(CMAKE_FIND_ROOT_PATH $ENV{SYSROOT}) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)这个文件的作用是给 Qt 的 CMake 辅助模块指明交叉编译环境避免它错误找到宿主机的库。虽然 Qt 5.14 主要靠 qmake configure 驱动但内部有些代码检查会调用 CMake 脚本准备好这个文件可以省去不少麻烦。3.4 第三方库的交叉静态编译上面说了依赖库有三种处理方式开源最常用、也是我这套方案采用的方式把关键第三方库编成静态库放进 sysroot。这里只挑最桥关键的两个——OpenSSL 和 ICU——来说明。OpenSSL 交叉编译命令wget https://www.openssl.org/source/openssl-1.1.1w.tar.gz tar xf openssl-1.1.1w.tar.gz cd openssl-1.1.1w ./Configure linux-aarch64 \ --prefix$SYSROOT/usr \ --cross-compile-prefixaarch64-linux-gnu- \ no-shared \ no-tests make -j$(nproc) make install_sw这里的no-shared是必须的Qt 链接 OpensSSL 的方式如果是-openssl-linked就必须提供静态库。如果 Qt 配置的是-openssl-runtime那你的 sysroot 里需要准备动态库同时在板子上部署时也要带上 .so。ICU 的交叉编译比 OpenSSL 麻烦不少64 位平台下需要特别处理 ICU_DATA 的路径。我的实际经验是如果项目中没有涉及 QLocale、QTextCodec 的复杂区域处理需求建议直接把 ICU 关掉。怎么关在 configure 参数里加-no-icu。如果确实需要 ICU那准备工作稍多ICU 官方提供了完整的交叉编译工具链配置示例你可以在 pkgdata 阶段设置PKGDATA_OPTS指向目标平台配置但这对新手不太友好。稳妥的方式是先用宿主机的 ICU 生成数据文件再交叉编译时指定数据文件路径但这套流程复杂度偏高不建议首次做静态交叉编译时混入。3.5 编译安装需要注意的资源与并发问题configure 完成后执行编译make -j$(nproc) make install实际操作中不建议一次性把-j拉满到宿主机 CPU 全部核心因为 aarch64 交叉编译时 gcc 的内存占用比原生编译高不少特别是编译 qvfb、qml 相关的代码时。我的建议物理核心数小于 8 的机器用 -j4大于 8 的用 -j8 或 -j12 都行但要留出至少 2GB 内存余量。编译过程中如果中途失败可以直接make -j4继续断点续传Qt 的构建系统通常不会因为某个模块失败而需要全部重编。但有一个例外如果失败原因是 Qt 源码解压不完整或磁盘空间不足那就必须先清理。安装完成后检查成果ls /opt/qt-aarch64-static/lib静态库文件以 .a 结尾例如 libQt5Core.a、libQt5Gui.a 等。同时确认 bin 目录下的 qmake 是 aarch64 格式file /opt/qt-aarch64-static/bin/qmake正常输出会显示 ELF 64-bit LSB executable, ARM aarch64。4. 编写第一个 aarch64 静态 Qt 程序并完成部署4.1 交叉编译 Qt Creator 构建套件的配置如果你习惯用 Qt Creator 开发需要手动添加一个 aarch64 构建套件。流程为Qt Creator - Tools - Options - Devices 中添加 Generic Linux Device写入板卡 IP 和用户名在 Compilers 页面手动添加 aarch64-linux-gnu-gcc 和 aarch64-linux-gnu-gC 语言和 C 编译器分别对应然后在 Qt Versions 页面选择 /opt/qt-aarch64-static/bin/qmake最后在 Kits 页面新建套件把 Sysroot 指向 $SYSROOT并设置 CMake Toolchain 文件为之前创建的 toolchain.cmake。这些配置做完之后可以新建一个 Empty qmake Project检查 qmake 和编译链是否生效。很多初学者遇到的问题是这个界面配置完成后没有生效我通常的排查思路是先确认 qmake 版本页面显示的是 Qt 5.14.2 for aarch64再看编译输出里的编译器路径是不是 /usr/bin/aarch64-linux-gnu-g最后确认没有混入宿主机 /usr/include 路径。这三点只要确认无误基本就通了。4.2 qmake 工程文件写好静态链接参数在工程 .pro 文件里除了常规的 QT widgets 之类的内容外静态编译场景下需要额外写QMAKE_LFLAGS -static QMAKE_LFLAGS -Wl,-Bstatic QMAKE_LFLAGS -Wl,-Bdynamic需要注意全部静态链接时有可能会把 libc 也静态链进去这时 glibc 会打印警告建议不使用全静态模式。实际最优策略是 Qt 及其依赖库静态链接底层 glibc 保留动态链接。方法是只加-static不行要把 Qt 库做成静态库后链接同时保留 libc、libstdc 动态链接。设置CONFIG static QMAKE_LFLAGS -Wl,-Bstatic -lQt5Core -lQt5Gui ... -Wl,-Bdynamic如果你的 Qt 库是安装在自定义路径还需要QMAKE_INCDIR /opt/qt-aarch64-static/include QMAKE_LIBDIR /opt/qt-aarch64-static/lib为了省事也可以在 .pro 里用QMAKE_LIBDIR把 /opt/qt-aarch64-static/lib 加进去但注意别把宿主机 /usr/lib 加进去不然链接时编译器会优先找到宿主机 x86 库然后报“wrong ELF class”错误。4.3 从源码到二进制可执行文件的完整构建流程以 Qt Widgets 程序为例完整步骤cd myqtapp /opt/qt-aarch64-static/bin/qmake myqtapp.pro -spec linux-aarch64-gnu-g make -j4生成的可执行文件直接用 file 命令确认file myqtapp理论上输出应为 ELF 64-bit LSB executable, ARM aarch64。接下来把它复制到板子scp myqtapp root板卡IP:/usr/local/bin/ chmod x /usr/local/bin/myqtapp然后板子上运行export QT_QPA_PLATFORMoffscreen ./myqtapp如果你的板子有屏幕可以设置 QT_QPA_PLATFORM 为 eglfs 或 linuxfb。等等——我们之前配置 Qt 时用-no-linuxfb -no-eglfs把 framebuffer 插板关掉了那这里应该怎么办这就是典型的前后矛盾的坑。我在此前 configure 中把显示相关全部停掉的策略适用于纯后端服务型 Qt 程序。如果你的程序需要 GUI 界面显示必须在 configure 参数里保留-linuxfb或-eglfs以及对应的-xcb选项。否则运行界面程序会报qt.qpa.plugin: Could not load the Qt platform plugin linuxfb。我建议的做法对于需要界面的项目configure 中至少保留-linuxfb -eglfs -xcb三种平台插件中的一种。如果目标板是树莓派类似的高性能 ARM 板且接有 HDMI 屏幕选用 eglfs如果板子只有 LCD 屏且没有 GPU用 linuxfb 最稳。二者的共性是编译依赖会多一点——linuxfb 需要 libinput 或直接使用内核 input-eventeglfs 需要 OpenGL ES 相关库。4.4 二进制瘦身与审计静态编译出来的可执行程序体积通常会很大因为 Qt Core 和 Qt Widgets 全量初始化代码都被放了进去。一个空窗口程序动辄 15MB 到 30MB 很正常。如果对体积有要求可以启动 strip 去掉符号表aarch64-linux-gnu-strip myqtappstrip 之后体积通常能减少 20% 到 30%。如果还不够可以继续做两件事一是检查可执行文件是否使用了-lQt5*静态库中的全部符号某些项目可以用 Qt 的 feature 系统裁剪模块二是看可执行文件里是否有 x86 架构的可疑依赖块用aarch64-linux-gnu-readelf -d myqtapp检查动态段确认没有意外引用宿主机的库。5. 高频问题排查编译期与运行期实录5.1 cannot find -lGL 与 OpenGL 相关链接错误Qt 的 xcb 插件在有 OpenGL 的情况会尝试链接 libGL而嵌入式板卡上很多没有独立 GPU甚至没有 OpenGL 开发库。解决办法第一确认 configure 阶段是否带上了-no-opengl第二在 sysroot 的 /usr/lib/aarch64-linux-gnu 中建立符号链接 libGL.so 指向 libGL.so.1有些板载 GPU 驱动只提供运行时库链接时需要一个 .so 符号链接。但这里有个细节如果你的板子只有 Mali GPU它的用户态驱动通常带 libMali.so而不是 libGL.so那链接时可以通过在 Qt 的 xcb 模块编译配置中指定-DQT_NO_OPENGL来绕开。这个不是常规操作需要你在板卡 SDK 文档中确认。总之OpenGL 相关错误在所有交叉编译 Qt 的反馈中最常见定位时一定要先区分是链接错误还是运行时错误。5.2 Qt 编译阶段报错 cannot find -lz / -lpngzlib、libpng 等基础库缺失。在静态编译时我推荐用 configure 的-qt-zlib -qt-libpng -qt-libjpeg参数让 Qt 使用源码自带的三方库一劳永逸。如果你确实需要用 sysroot 里的库那提前确保 sysroot 中有对应的 .a 静态库而不仅仅是 .so。因为静态链接模式下 ld 不会去尝试 .so 文件。常见场景是板卡上的 libpng.so.16 存在但 libpng.a 不存在那 configure 阶段能通过但编译阶段会失败原因就在这里。5.3 unknown module(s) in Qt: serialport很多人在新环境里编译 Qt 项目时会遇到这个报错。它代表 Qt 缺少对应的模块文件你需要在 configure 阶段确认没有把 qtserialport 排除掉。Qt 5.14.2 默认源码树中 serialport 模块位于 qtserialport 目录编译前检查这个模块是否存在如果不存在需要单独下载。最稳妥的方法是在 configure 之后进入 qtserialport 目录单独执行qmake make make install。如果你是在完整源码包中一次性编译的需要确认 configure 时没有加-skip qtserialport。这个报错我在 Ubuntu 20.04 自带的 Qt 5.15.3 上遇到得特别多而 5.14.2 源码包自带 serialport 模块一般不会踩这个雷。如果你仍然遇到还有可能是 mkspec 路径没找到在工程 .pro 里添加QT serialport后检查系统环境变量 QMAKEPATH。5.4 cannot mix incompatible Qt library (5.15.3) with this library (5.15.2)这个错误常见于 qmake 和系统安装的 Qt 库版本不一致的情况。静态编译时尤其容易出现因为你可能是手动指定 qmake 到 /opt/qt-aarch64-static/bin/qmake但工程文件里用了系统默认的 Qt 环境变量导致编译时链接到了宿主机 x86 的 Qt 5.15.3 库。解决办法很简单在运行 qmake 时用绝对路径并且检查工程文件里是否有对 Qt 库路径的硬编码另外将宿主机上 /usr/lib/x86_64-linux-gnu/cmake 下的 Qt5Config.cmake 等文件临时挪走避免编译过程 CMake 在国际化检测或其他辅助时误引用。5.5 部署到板子后运行弹出 could not find or load the Qt platform plugin这个错误是最经典的运行期问题。你编出的程序跑起来后需要加载平台插件静态编译模式下插件通常也被编到库里了但由于没有放到插件搜索路径Qt 无法找到。解决方案确认程序里是否设置了QApplication::setLibraryPaths()或者在运行时设置export QT_PLUGIN_PATH/opt/qt-aarch64-static/plugins。把 plugins 目录整体拷贝到板子的同一相对路径下例如 /opt/qt-aarch64-static/plugins。在代码中指定路径QCoreApplication::addLibraryPath(/opt/qt-aarch64-static/plugins);运行时配上QT_QPA_PLATFORM_PLUGIN_PATH环境变量。另外要注意如果你的程序只依赖 core 和 network那 platform plugin 这一项通常不会出现一旦出现了 GUI、Widgets、QML 等模块引用平台插件就必须“存在且可被找到”。5.6 解决宿主与目标 glibc 版本不一致导致的段错误这个坑比较隐蔽。你在宿主机的 sysroot 中拷板子的根文件系统时时间久了板子的 glibc 或 libstdc 被更新了但你的 sysroot 没有同步于是编译出的静态程序在板子上运行时报段错误而不是报缺库。排查方式aarch64-linux-gnu-readelf 查看可执行文件的动态依赖确认 NEEDED 字段中的 libc.so.6 是否指向目标板的链接器路径再用aarch64-linux-gnu-objdump -T检查版本引用。要么同步更新 sysroot要么降低交叉编译工具链版本匹配板子的系统库版本。这个没有完美的通用解唯一的稳定性规则是确保 sysroot 中 glibc 的大版本号与板子运行系统一致。6. 写在最后的几条个人心得这套 Qt 5.14.2 静态交叉编译方案前前后后折腾了大概两个星期才彻底跑通。回头看几个核心问题其实不是技术难度本身而在于很多人会忽略的“路径和版本一致性”。Qt 的 configure 是一个非常灵活的构建系统参数不对、路径不对、工具链版本不统一都可能编译出“看似成功却不能用”的产物。我在实际操作中最受益的做法有两个一是把 sysroot 当成一套资产来管理单独打包备份每次板卡系统更新后重新生成一次 sysroot并记录日期和版本号二是把 configure 参数写成 shell 脚本保存下来而不是每次都靠命令行手敲这样无论是重新编译还是交给同事复现都能保持一致。还有一个容易被忽略的小技巧当你需要在 Qt 工程中嵌入第三方 C/C 模块时尽量保证这些模块也是静态编译的否则你在最后链接阶段还要处理大量“undefined reference”的库顺序问题。静态库在 gcc 链接命令中的顺序很敏感通常建议把依赖底层的库放在后面——比如 libm、libz、libc。如果你在链接阶段遇到莫名其妙的未定义符号优先检查库顺序而不是怀疑 Qt 本身。最后再说一个部署层面的细节静态编译的 Qt 程序虽然摆脱了 Qt 自身 .so 的依赖但不代表它是纯“绿色”的它仍然需要目标板满足两点glibc 版本不能低于 sysroot 中开发时的版本/etc/fonts 或字库目录里需要存在可供 Qt 字体渲染使用的字体文件否则 GUI 程序在板子上显示中文会变成方框。如果你在板子上运行 GUI 程序发现字体不显示不要怀疑 Qt 编译问题直接检查字体文件的安装位置即可。
1. 为什么你需要一份完整的 Qt aarch64 静态交叉编译手册先说结论在 ARM 设备上跑 Qt 应用如果你不想背着一堆 .so 到处配置环境变量、不想在客户现场被缺失依赖折腾到怀疑人生那静态交叉编译是你迟早要跨过去的一道坎。我这次做的是 Qt 5.14.2 在 aarch64 架构下的静态交叉编译目标板是 ARMv8 平台宿主编译机用的 Ubuntu 20.04 x86_64。从安装交叉工具链、配置 sysroot 到最后把二进制丢到板子上跑起来整个流程从头走了两遍踩了不少坑这篇手册就是把这两遍的经验全部沉淀下来给后来的人当一份可以直接抄作业的参考。先说清楚这个手册解决的是什么问题第一Qt 官方没有直接提供 aarch64 平台下的静态库安装包你必须自己用源码编译这一点和桌面版 Windows/Linux 的做法完全不同第二交叉编译涉及工具链、目标系统根文件系统sysroot、目标平台依赖库三个维度任何一个环节版本不匹配都会导致链接阶段报出一堆莫名其妙的错误第三Qt 5.14.2 属于 LTS 版本相对稳定且不强制要求 C17如果你的项目还跑在老旧的 ARM 板卡 Linux 系统上这个版本是一个很务实的选择。如果你正在做嵌入式 Qt 应用开发、车载方案或者国产化 ARM 平台适配这篇文章就是照着做就能跑通的完整路径。顺便回应一下很多人在搜索“qt 交叉编译环境”时遇到的困惑网上关于 Qt 5.14 的教程不少但大多数讲的是 x86 平台动态编译或者针对 armv732位的交叉编译一旦换成 aarch64会冒出至少四类问题——工具链前缀不同aarch64-linux-gnu- 而不是 arm-linux-gnueabihf-、库依赖从 lib/arm-linux-gnueabihf 换到了 lib/aarch64-linux-gnu、静态编译时 zlib/png/openssl 等组件反复冲突、以及部署阶段因为 glibc 或 Cairo 等系统库仍然动态链接而功亏一篑。本文会把这四个坑连同解决方案全部覆盖掉在实操层面直接给你参数和命令不铺垫废话。2. 编译环境搭建与前置条件2.1 宿主机与目标板基础信息我用的宿主机是 Ubuntu 20.04.6 LTS内核 5.4 以上x86_64 架构。为什么选 20.04因为 Qt 5.14.2 官方支持列表里对 glibc 2.31 和 GCC 9.x 有较好的兼容性而 Ubuntu 20.04 默认环境恰好满足这两个条件不需要额外折腾太多。若你使用 Ubuntu 22.04 或者 Debian 12系统默认 GCC 11/12 在编译旧版本 Qt 源码时可能会触发“-stdc17 混用”“Qt Xcb 模块编译失败”这类怪问题处理起来成本会高于直接上手 20.04。目标板信息aarch64 架构ARMv8板卡厂商的 BSP 基于 glibc 2.28内核版本 4.19。板卡上的根文件系统我单独提取出来作为交叉编译 sysroot具体提取方法和要点见下一节。如果你手里没有现成的 sysroot也可以从开发板烧录镜像里解包或者直接下载厂商提供的交叉 SDK例如 Linaro 的 aarch64 工具链会附带一个预构建 sysroot只是里面一般只有基础库Qt 运行依赖的 libicu 等需要额外补充。硬性配置建议编译 Qt 这种巨型项目建议宿主机的内存不低于 8GB。我第一次用 4GB 虚拟机编译在 -j4 并行度下直接把系统内存打满导致 perl 进程和 moc 进程被杀编到 qtbase 就失败。如果想要舒服一点16GB 内存、-j8 并行qtbase 加 qtdeclarative 加 qtmultimedia全部编完大约 90 到 120 分钟属于可以接受的范围。2.2 交叉编译工具链选择与安装交叉编译 aarch64 的工具链可选方案不少常见的有Linaro GCC 工具链gcc-linaro-7.x 或 9.x支持 aarch64-linux-gnuARM GNU Toolchainarm-gnu-toolchain-11.x 之后版本命名改成 arm-gnu-toolchain-xUbuntu 自带交叉工具链gcc-aarch64-linux-gnu版本随系统源更新我最终选用的是 Ubuntu 自带的 gcc-aarch64-linux-gnu版本为 9.4.0。理由很简单自带的工具链与系统 glibc 版本匹配度最高而且用 apt 安装能顺手解决 cpp、binutils 等一组配套依赖不用手工配置 PATH。安装命令sudo apt update sudo apt install gcc-aarch64-linux-gnu g-aarch64-linux-gnu安装完成之后验证一下工具链是否可用aarch64-linux-gnu-gcc --version aarch64-linux-gnu-g --version这里有个小经验如果后续编译 Qt 时遇到“cannot find -lstdc”“cannot find -lgcc_s”之类的报错不要慌张优先检查工具链是否安装完整因为 Ubuntu 把 aarch64 的 libstdc 放在 g-aarch64-linux-gnu 这个包里面只装 gcc 不装 g 会缺一整套 C 运行库。另一个重要组件是交叉编译版本的 pkg-config。在 Ubuntu 20.04 上直接安装sudo apt install pkg-config-aarch64-linux-gnu这个包会提供一个名为 aarch64-linux-gnu-pkg-config 的包装脚本在配置 Qt 和后续编写工程时需要把 PKG_CONFIG 环境变量指到它否则 configure 阶段检测 xcb、libpng 时会把宿主机的 .pc 文件路径混进来最终生成错误的链接参数。2.3 sysroot 的获取与目录结构sysroot 是指目标板根文件系统的拷贝作用是在交叉编译时提供给编译器和链接器一套与目标板一致的基础库头文件和 .so 文件。获取方式有两种从开发板镜像里直接解包。通常厂商会提供 .img 镜像文件可以用 debootstrap、qemu-nbd 或者直接用 file 命令识别镜像格式后用 7z 解包。如果板卡支持联网直接在板子上拷贝。例如用 rsync 把 /lib、/usr/lib、/usr/include 目录同步回来。我用的是第二种方式因为手里的板子能开机联网操作最快rsync -avz root板卡IP:/lib sysroot/ rsync -avz root板卡IP:/usr/lib sysroot/usr/ rsync -avz root板卡IP:/usr/include sysroot/usr/同步时必须注意保留符号链接不要加 -L 参数把软链解开否则 sysroot 里 /lib/aarch64-linux-gnu 目录下的 .so 全部变成常规文件后续调试和部署阶段很容易出问题。另外/usr/local 下如果有额外安装的库也要一并同步。最终形成的 sysroot 目录结构大概是sysroot/ ├── lib/ │ └── aarch64-linux-gnu/ │ ├── libc.so.6 │ ├── libm.so.6 │ ├── ld-linux-aarch64.so.1 │ └── ... └── usr/ ├── include/ │ ├── aarch64-linux-gnu/ │ └── ... └── lib/ ├── aarch64-linux-gnu/ └── ...后续所有编译操作都会用 --sysroot 参数指向这个目录因此建议把它放到稳定的路径例如 /opt/sysroot/aarch64-linux-gnu并且设置一个环境变量方便调用export SYSROOT/opt/sysroot/aarch64-linux-gnu注意sysroot 中必须保留 ld-linux-aarch64.so.1 动态链接器。如果你发现板卡根文件系统里这个文件丢失可以尝试从相同芯片平台的系统镜像中提取也可以直接用工具链中的 /aarch64-linux-gnu/libc/ 拷贝一份但版本必须与板子的 glibc 匹配否则部署出来动态加载直接崩。3. Qt 5.14.2 源码获取与关键编译选项解析3.1 下载源码并校验完整性Qt 5.14.2 的源码包在官方下载站点 archive 目录下当前网络上有大量“qt 下载”“qt 5.15.2 下载”“qt 离线安装包下载5.14”的搜索结果如果你需要访问官方仓库直接去 Qt 官方 Archive 路径查找 qt-everywhere-src-5.14.2.tar.xz 即可。下载之后强烈建议做一次 SHA1 校验避免压缩包断点损坏导致编译过程中莫明其妙报语法错误。wget https://download.qt.io/archive/qt/5.14/5.14.2/qt-everywhere-src-5.14.2.tar.xz sha1sum 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这里多说一句为什么选 5.14.2 而不是更新的 5.15.2 或 6.x主要原因有两个。第一5.14.2 是最后一个支持“传统 qmake 体系 官方离线安装包”组合的 LTS 版本很多第三方的嵌入式 BSP 或老项目代码都在这个版本上验证过第二从 5.15 开始Qt 公司调整了开源版下载渠道和更新策略离线源码包的获取不如 5.14.2 省心。如果你的项目没有硬性要求使用 5.15 的新特性5.14.2 在嵌入式 Linux 场景下会更稳定。3.2 目标平台依赖库的梳理交叉编译 Qt 时最费时间的就是依赖库的准备。对于 aarch64 静态编译关键依赖大致如下zlib基础压缩库几乎必选。libpng / libjpeg图像格式支持Qt GUI 常见依赖。freetype / fontconfig字体渲染很多嵌入式板子不带静态编译时建议编进 Qt 库中。openssl如果需要 https 或加密传输必须提前准备好 aarch64 版本。sqlite3一般嵌入式会用到。libicuTextCodec 和 QLocale 的底层依赖如果你不做国际化需求可以关掉但建议保留。libxcb 系列xcb-xlib、xcb-util 等若你的板子跑的是带 X11 的桌面环境这部分必须保留如果是纯 framebuffer 或者 eglfs则可以跳过。在开始 configure 之前先用文件搜索的方式确认 sysroot 里有没有这些库的 .pc 文件。例如find $SYSROOT -name *.pc如果缺少某个库可以在 sysroot 中从板子的软件源安装也可以在宿主机上交叉编译一份后拷贝进 sysroot。实操上我更推荐后者的进阶版直接把需要的第三方库以源码方式放到 Qt 工程三分支编译目录由 Qt 的 configure 流程统一处理这样最省心。3.3 configure 参数的选择逻辑与完整命令标准 aarch64 静态编译 configure 命令如下mkdir build cd build ../configure \ -prefix /opt/qt-aarch64-static \ -xplatform linux-aarch64-gnu-g \ -release \ -static \ -opensource \ -confirm-license \ -nomake examples \ -nomake tests \ -no-compile-examples \ -skip qtwebengine \ -skip qtwayland \ -skip qtscript \ -skip qtquick3d \ -dbus-linked \ -openssl-linked \ -sql-sqlite \ -qt-zlib \ -qt-libpng \ -qt-libjpeg \ -qt-freetype \ -qt-pcre \ -no-opengl \ -no-eglfs \ -no-linuxfb \ -no-kms \ -no-gbm \ -no-xcb \ -- \ -DCMAKE_SYSROOT$SYSROOT \ -DCMAKE_TOOLCHAIN_FILE../toolchain.cmake参数逐个解释-prefix最终安装路径建议独立目录避免污染系统目录。-xplatform linux-aarch64-gnu-g这是 Qt 内置的 mkspec专门用于 aarch64 交叉编译。在 qtbase/mkspecs 目录下可以看到这个文件。-static核心中的核心没有这个参数其他全部免谈。-release去掉调试符号减少编译时间和产物体积。-opensource -confirm-license开源版许可确认。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre强制 Qt 使用源码包自带的第三方库避免和 sysroot 里的对应库打架。这是静态编译最稳妥的策略不然链接的时候会遇到一堆“duplicate symbol”或“undefined reference”。-no-opengl -no-eglfs -no-linuxfb -no-kms -no-gbm -no-xcb如果你不需要图形显示把这些全部关闭可以大幅降低依赖复杂度。实测目标板上只需要纯逻辑计算 网络通信用这一组参数编出来的 Qt 库体积比开启 xcb 时少了约 30%。-openssl-linked如果目标板代码需要 https 调用用这个选项让 Qt Network 静态链入 OpenSSL。相应地需要提前准备 aarch64 OpenSSL 静态库具体方法见 3.4。-dbus-linkedQt 的 D-Bus 模块使用静态链接。嵌入式应用如果不需要 D-Bus可以改为 -no-dbus省一堆编译时间。另外要准备一个交叉编译 toolchain.cmake 文件内容大致如下set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g) set(CMAKE_SYSROOT $ENV{SYSROOT}) set(CMAKE_FIND_ROOT_PATH $ENV{SYSROOT}) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)这个文件的作用是给 Qt 的 CMake 辅助模块指明交叉编译环境避免它错误找到宿主机的库。虽然 Qt 5.14 主要靠 qmake configure 驱动但内部有些代码检查会调用 CMake 脚本准备好这个文件可以省去不少麻烦。3.4 第三方库的交叉静态编译上面说了依赖库有三种处理方式开源最常用、也是我这套方案采用的方式把关键第三方库编成静态库放进 sysroot。这里只挑最桥关键的两个——OpenSSL 和 ICU——来说明。OpenSSL 交叉编译命令wget https://www.openssl.org/source/openssl-1.1.1w.tar.gz tar xf openssl-1.1.1w.tar.gz cd openssl-1.1.1w ./Configure linux-aarch64 \ --prefix$SYSROOT/usr \ --cross-compile-prefixaarch64-linux-gnu- \ no-shared \ no-tests make -j$(nproc) make install_sw这里的no-shared是必须的Qt 链接 OpensSSL 的方式如果是-openssl-linked就必须提供静态库。如果 Qt 配置的是-openssl-runtime那你的 sysroot 里需要准备动态库同时在板子上部署时也要带上 .so。ICU 的交叉编译比 OpenSSL 麻烦不少64 位平台下需要特别处理 ICU_DATA 的路径。我的实际经验是如果项目中没有涉及 QLocale、QTextCodec 的复杂区域处理需求建议直接把 ICU 关掉。怎么关在 configure 参数里加-no-icu。如果确实需要 ICU那准备工作稍多ICU 官方提供了完整的交叉编译工具链配置示例你可以在 pkgdata 阶段设置PKGDATA_OPTS指向目标平台配置但这对新手不太友好。稳妥的方式是先用宿主机的 ICU 生成数据文件再交叉编译时指定数据文件路径但这套流程复杂度偏高不建议首次做静态交叉编译时混入。3.5 编译安装需要注意的资源与并发问题configure 完成后执行编译make -j$(nproc) make install实际操作中不建议一次性把-j拉满到宿主机 CPU 全部核心因为 aarch64 交叉编译时 gcc 的内存占用比原生编译高不少特别是编译 qvfb、qml 相关的代码时。我的建议物理核心数小于 8 的机器用 -j4大于 8 的用 -j8 或 -j12 都行但要留出至少 2GB 内存余量。编译过程中如果中途失败可以直接make -j4继续断点续传Qt 的构建系统通常不会因为某个模块失败而需要全部重编。但有一个例外如果失败原因是 Qt 源码解压不完整或磁盘空间不足那就必须先清理。安装完成后检查成果ls /opt/qt-aarch64-static/lib静态库文件以 .a 结尾例如 libQt5Core.a、libQt5Gui.a 等。同时确认 bin 目录下的 qmake 是 aarch64 格式file /opt/qt-aarch64-static/bin/qmake正常输出会显示 ELF 64-bit LSB executable, ARM aarch64。4. 编写第一个 aarch64 静态 Qt 程序并完成部署4.1 交叉编译 Qt Creator 构建套件的配置如果你习惯用 Qt Creator 开发需要手动添加一个 aarch64 构建套件。流程为Qt Creator - Tools - Options - Devices 中添加 Generic Linux Device写入板卡 IP 和用户名在 Compilers 页面手动添加 aarch64-linux-gnu-gcc 和 aarch64-linux-gnu-gC 语言和 C 编译器分别对应然后在 Qt Versions 页面选择 /opt/qt-aarch64-static/bin/qmake最后在 Kits 页面新建套件把 Sysroot 指向 $SYSROOT并设置 CMake Toolchain 文件为之前创建的 toolchain.cmake。这些配置做完之后可以新建一个 Empty qmake Project检查 qmake 和编译链是否生效。很多初学者遇到的问题是这个界面配置完成后没有生效我通常的排查思路是先确认 qmake 版本页面显示的是 Qt 5.14.2 for aarch64再看编译输出里的编译器路径是不是 /usr/bin/aarch64-linux-gnu-g最后确认没有混入宿主机 /usr/include 路径。这三点只要确认无误基本就通了。4.2 qmake 工程文件写好静态链接参数在工程 .pro 文件里除了常规的 QT widgets 之类的内容外静态编译场景下需要额外写QMAKE_LFLAGS -static QMAKE_LFLAGS -Wl,-Bstatic QMAKE_LFLAGS -Wl,-Bdynamic需要注意全部静态链接时有可能会把 libc 也静态链进去这时 glibc 会打印警告建议不使用全静态模式。实际最优策略是 Qt 及其依赖库静态链接底层 glibc 保留动态链接。方法是只加-static不行要把 Qt 库做成静态库后链接同时保留 libc、libstdc 动态链接。设置CONFIG static QMAKE_LFLAGS -Wl,-Bstatic -lQt5Core -lQt5Gui ... -Wl,-Bdynamic如果你的 Qt 库是安装在自定义路径还需要QMAKE_INCDIR /opt/qt-aarch64-static/include QMAKE_LIBDIR /opt/qt-aarch64-static/lib为了省事也可以在 .pro 里用QMAKE_LIBDIR把 /opt/qt-aarch64-static/lib 加进去但注意别把宿主机 /usr/lib 加进去不然链接时编译器会优先找到宿主机 x86 库然后报“wrong ELF class”错误。4.3 从源码到二进制可执行文件的完整构建流程以 Qt Widgets 程序为例完整步骤cd myqtapp /opt/qt-aarch64-static/bin/qmake myqtapp.pro -spec linux-aarch64-gnu-g make -j4生成的可执行文件直接用 file 命令确认file myqtapp理论上输出应为 ELF 64-bit LSB executable, ARM aarch64。接下来把它复制到板子scp myqtapp root板卡IP:/usr/local/bin/ chmod x /usr/local/bin/myqtapp然后板子上运行export QT_QPA_PLATFORMoffscreen ./myqtapp如果你的板子有屏幕可以设置 QT_QPA_PLATFORM 为 eglfs 或 linuxfb。等等——我们之前配置 Qt 时用-no-linuxfb -no-eglfs把 framebuffer 插板关掉了那这里应该怎么办这就是典型的前后矛盾的坑。我在此前 configure 中把显示相关全部停掉的策略适用于纯后端服务型 Qt 程序。如果你的程序需要 GUI 界面显示必须在 configure 参数里保留-linuxfb或-eglfs以及对应的-xcb选项。否则运行界面程序会报qt.qpa.plugin: Could not load the Qt platform plugin linuxfb。我建议的做法对于需要界面的项目configure 中至少保留-linuxfb -eglfs -xcb三种平台插件中的一种。如果目标板是树莓派类似的高性能 ARM 板且接有 HDMI 屏幕选用 eglfs如果板子只有 LCD 屏且没有 GPU用 linuxfb 最稳。二者的共性是编译依赖会多一点——linuxfb 需要 libinput 或直接使用内核 input-eventeglfs 需要 OpenGL ES 相关库。4.4 二进制瘦身与审计静态编译出来的可执行程序体积通常会很大因为 Qt Core 和 Qt Widgets 全量初始化代码都被放了进去。一个空窗口程序动辄 15MB 到 30MB 很正常。如果对体积有要求可以启动 strip 去掉符号表aarch64-linux-gnu-strip myqtappstrip 之后体积通常能减少 20% 到 30%。如果还不够可以继续做两件事一是检查可执行文件是否使用了-lQt5*静态库中的全部符号某些项目可以用 Qt 的 feature 系统裁剪模块二是看可执行文件里是否有 x86 架构的可疑依赖块用aarch64-linux-gnu-readelf -d myqtapp检查动态段确认没有意外引用宿主机的库。5. 高频问题排查编译期与运行期实录5.1 cannot find -lGL 与 OpenGL 相关链接错误Qt 的 xcb 插件在有 OpenGL 的情况会尝试链接 libGL而嵌入式板卡上很多没有独立 GPU甚至没有 OpenGL 开发库。解决办法第一确认 configure 阶段是否带上了-no-opengl第二在 sysroot 的 /usr/lib/aarch64-linux-gnu 中建立符号链接 libGL.so 指向 libGL.so.1有些板载 GPU 驱动只提供运行时库链接时需要一个 .so 符号链接。但这里有个细节如果你的板子只有 Mali GPU它的用户态驱动通常带 libMali.so而不是 libGL.so那链接时可以通过在 Qt 的 xcb 模块编译配置中指定-DQT_NO_OPENGL来绕开。这个不是常规操作需要你在板卡 SDK 文档中确认。总之OpenGL 相关错误在所有交叉编译 Qt 的反馈中最常见定位时一定要先区分是链接错误还是运行时错误。5.2 Qt 编译阶段报错 cannot find -lz / -lpngzlib、libpng 等基础库缺失。在静态编译时我推荐用 configure 的-qt-zlib -qt-libpng -qt-libjpeg参数让 Qt 使用源码自带的三方库一劳永逸。如果你确实需要用 sysroot 里的库那提前确保 sysroot 中有对应的 .a 静态库而不仅仅是 .so。因为静态链接模式下 ld 不会去尝试 .so 文件。常见场景是板卡上的 libpng.so.16 存在但 libpng.a 不存在那 configure 阶段能通过但编译阶段会失败原因就在这里。5.3 unknown module(s) in Qt: serialport很多人在新环境里编译 Qt 项目时会遇到这个报错。它代表 Qt 缺少对应的模块文件你需要在 configure 阶段确认没有把 qtserialport 排除掉。Qt 5.14.2 默认源码树中 serialport 模块位于 qtserialport 目录编译前检查这个模块是否存在如果不存在需要单独下载。最稳妥的方法是在 configure 之后进入 qtserialport 目录单独执行qmake make make install。如果你是在完整源码包中一次性编译的需要确认 configure 时没有加-skip qtserialport。这个报错我在 Ubuntu 20.04 自带的 Qt 5.15.3 上遇到得特别多而 5.14.2 源码包自带 serialport 模块一般不会踩这个雷。如果你仍然遇到还有可能是 mkspec 路径没找到在工程 .pro 里添加QT serialport后检查系统环境变量 QMAKEPATH。5.4 cannot mix incompatible Qt library (5.15.3) with this library (5.15.2)这个错误常见于 qmake 和系统安装的 Qt 库版本不一致的情况。静态编译时尤其容易出现因为你可能是手动指定 qmake 到 /opt/qt-aarch64-static/bin/qmake但工程文件里用了系统默认的 Qt 环境变量导致编译时链接到了宿主机 x86 的 Qt 5.15.3 库。解决办法很简单在运行 qmake 时用绝对路径并且检查工程文件里是否有对 Qt 库路径的硬编码另外将宿主机上 /usr/lib/x86_64-linux-gnu/cmake 下的 Qt5Config.cmake 等文件临时挪走避免编译过程 CMake 在国际化检测或其他辅助时误引用。5.5 部署到板子后运行弹出 could not find or load the Qt platform plugin这个错误是最经典的运行期问题。你编出的程序跑起来后需要加载平台插件静态编译模式下插件通常也被编到库里了但由于没有放到插件搜索路径Qt 无法找到。解决方案确认程序里是否设置了QApplication::setLibraryPaths()或者在运行时设置export QT_PLUGIN_PATH/opt/qt-aarch64-static/plugins。把 plugins 目录整体拷贝到板子的同一相对路径下例如 /opt/qt-aarch64-static/plugins。在代码中指定路径QCoreApplication::addLibraryPath(/opt/qt-aarch64-static/plugins);运行时配上QT_QPA_PLATFORM_PLUGIN_PATH环境变量。另外要注意如果你的程序只依赖 core 和 network那 platform plugin 这一项通常不会出现一旦出现了 GUI、Widgets、QML 等模块引用平台插件就必须“存在且可被找到”。5.6 解决宿主与目标 glibc 版本不一致导致的段错误这个坑比较隐蔽。你在宿主机的 sysroot 中拷板子的根文件系统时时间久了板子的 glibc 或 libstdc 被更新了但你的 sysroot 没有同步于是编译出的静态程序在板子上运行时报段错误而不是报缺库。排查方式aarch64-linux-gnu-readelf 查看可执行文件的动态依赖确认 NEEDED 字段中的 libc.so.6 是否指向目标板的链接器路径再用aarch64-linux-gnu-objdump -T检查版本引用。要么同步更新 sysroot要么降低交叉编译工具链版本匹配板子的系统库版本。这个没有完美的通用解唯一的稳定性规则是确保 sysroot 中 glibc 的大版本号与板子运行系统一致。6. 写在最后的几条个人心得这套 Qt 5.14.2 静态交叉编译方案前前后后折腾了大概两个星期才彻底跑通。回头看几个核心问题其实不是技术难度本身而在于很多人会忽略的“路径和版本一致性”。Qt 的 configure 是一个非常灵活的构建系统参数不对、路径不对、工具链版本不统一都可能编译出“看似成功却不能用”的产物。我在实际操作中最受益的做法有两个一是把 sysroot 当成一套资产来管理单独打包备份每次板卡系统更新后重新生成一次 sysroot并记录日期和版本号二是把 configure 参数写成 shell 脚本保存下来而不是每次都靠命令行手敲这样无论是重新编译还是交给同事复现都能保持一致。还有一个容易被忽略的小技巧当你需要在 Qt 工程中嵌入第三方 C/C 模块时尽量保证这些模块也是静态编译的否则你在最后链接阶段还要处理大量“undefined reference”的库顺序问题。静态库在 gcc 链接命令中的顺序很敏感通常建议把依赖底层的库放在后面——比如 libm、libz、libc。如果你在链接阶段遇到莫名其妙的未定义符号优先检查库顺序而不是怀疑 Qt 本身。最后再说一个部署层面的细节静态编译的 Qt 程序虽然摆脱了 Qt 自身 .so 的依赖但不代表它是纯“绿色”的它仍然需要目标板满足两点glibc 版本不能低于 sysroot 中开发时的版本/etc/fonts 或字库目录里需要存在可供 Qt 字体渲染使用的字体文件否则 GUI 程序在板子上显示中文会变成方框。如果你在板子上运行 GUI 程序发现字体不显示不要怀疑 Qt 编译问题直接检查字体文件的安装位置即可。
