Qt5.14.2交叉编译aarch64静态库全程详解

开头先说明，这篇稿子是我结合实际搭建经历整理的，主要面向做嵌入式Linux、需要把Qt5.14.2跑在aarch64（ARM64）平台上的朋友们。目标很具体：在x86_64主机上，用交叉编译工具链把Qt5.14.2编译成aarch64架构下的静态库和静态可执行文件，最终产物可以直接拷到目标板上运行，不依赖目标板上的动态库。

这个需求我在项目里碰到过很多次，尤其是做工业控制器、边缘网关、专用终端的时候。系统是厂家裁剪过的，动态库不稳定、版本乱、缺依赖，每次部署都要反复调库路径。静态编译虽然会带来体积大、许可证要留意这些问题，但省掉的麻烦是真省掉了。

本文会把从零搭建的完整过程拆开讲，包括工具链选型、sysroot准备、Qt源码处理、configure参数逐项解释、make编译、产物验证，以及我踩过的坑。没有跳过任何一步，也没有用“你懂的”之类的省略说法。

1. 为什么是Qt5.14.2、aarch64和静态交叉编译

1.1 版本选择背后的考量

Qt5.14.2是LTS版本。对于嵌入式项目来说，LTS意味着长期维护、社区资源丰富、各种硬件平台上的兼容性问题基本都被趟过了。如果你去查各芯片厂商的BSP包，很多aarch64平台的SDK默认带的都是5.14.x或者5.15.x，说明这个版本段在工业界接受度很高。

5.15以后版本开始收紧开源协议策略，5.14.2是最后一个比较容易获得完整内置模块源码的版本之一。这里不聊协议合规细节，但实际做商业产品的人都知道，选LTS再配合严格的自用编译，风险相对可控。

1.2 aarch64平台的特殊性

aarch64是ARM的64位架构，现在市面上绝大多数新出的嵌入式SoC都是它，比如瑞芯微RK3588、全志T507、飞腾、鲲鹏这些。相比老旧的armv7，aarch64在性能、内存寻址、NEON/SIMD指令上都强很多，但也有几个让开发者头疼的特点：

• 工具链命名复杂。同样是交叉编译器，有人叫aarch64-linux-gnu-gcc，有人叫aarch64-linux-gcc，还有人用aarch64-none-linux-gnu-gcc，前缀不同，库路径就不同。
• 板卡厂商的rootfs差别大。有的用glibc，有的用musl，有的BSP里gcc版本老得可怜。
• 浮点ABI指令集的变体不少，虽然64位基本都是硬浮点，但不同核心对部分扩展指令的支持不一样。

这就导致了一个结果：任何通用教程都不能完全适配你的板子，但只要你理解了编译链路的每一环，具体板子的坑就只是时间问题。

1.3 静态编译到底图什么

静态编译就是把Qt和依赖的第三方库全部打包进最终的可执行文件里。好处三件事：

• 目标板不需要安装Qt运行环境，相当于自带运行时。
• 没有“找不到libQt5Core.so.5”这类经典翻车现场。
• 文件拷到板子上直接运行，部署简化到了极致。

代价也很明显：可执行文件体积大，我这个hello world编译出来18MB起步，带网络模块和UI的完整程序动辄50MB以上。另外，Qt默认是不建议静态链接的，因为静态链接的Qt和OpenSSL、xkb、GPU驱动这些系统组件的交互方式不一样，配置不对会有一堆隐性故障。

但很多工业项目部署的板子只有64MB存储，内存小、用户就那几个，动态版本天天出问题。实测下来，静态版虽然大了点，但跑起来反而更稳定，没有运行时依赖，没有路径地狱。

1.4 整体编译链路

先把整条链路在脑子里拉一遍：

1. 主机（x86_64的Ubuntu）上安装aarch64交叉编译工具链。
2. 准备一块目标板文件系统（sysroot），里面包含aarch64的libc、libstdc++以及各种静态库文件。
3. 下载Qt5.14.2完整源码。
4. 配置Qt使用“目标为aarch64”的qmake平台规范。
5. 用configure生成Makefile。
6. 执行make编译Qt库和工具。
7. 使用编译出来的qmake去编译你自己的Qt程序，得到静态链接的aarch64可执行文件。

整条链看起来简单，每一步都有细节，下面逐条展开。

2. 环境准备与工具链选型

2.1 主机系统建议

我用的是Ubuntu 20.04，用Ubuntu 18.04也完全可行，只要是64位系统就行。不需要服务器版，桌面版也一样，反正最终也是命令行操作。编译Qt会消耗不少CPU和内存，建议至少4核以上、8GB内存，磁盘预留30GB以上。

主机上需要安装的基础软件：

sudo apt update && sudo apt install -y \ build-essential \ libncurses5-dev \ libglib2.0-dev \ libfontconfig1-dev \ libfreetype6-dev \ libx11-dev \ libxext-dev \ libxrender-dev \ libxcb1-dev \ libx11-xcb-dev \ libxcb-glx0-dev \ libxcb-util0-dev \ python3 \ perl \ gperf \ bison \ flex \ texinfo \ wget \ curl \ vim \ net-tools

有些包是编译Qt源码时脚本检测用的，比如perl、python3、gperf。如果你的系统没有装，configure过程中会自动跳过一些功能，最后编译出来的Qt可能少模块，排查起来很麻烦，所以一次性装齐。

注意：这里是主机原生环境安装的依赖，只用于辅助脚本运行，编译出来的aarch64代码不会链接这些x86库。真正的链接目标是下一节说的sysroot。

2.2 交叉工具链选择

aarch64交叉工具链主流有几种：

• Linaro公司发布的gcc-aarch64-linux-gnu工具链，历史最久、文档最丰富。
• ARM官网的GNU GCC交叉编译器，现在叫AArch64 GNU/Linux工具链。
• 板卡厂商BSP自带的工具链，比如瑞芯微的rk-gcc、全志的aarch64-linux-gnu-gcc。

我的建议是：如果哈板卡厂商提供了配套工具链，优先用板卡厂商的。原因很简单，厂商的交叉工具链和它的BSP rootfs是一起验证过的，版本匹配度最高。如果自己做通用移植，用ARM官方下载的10.3版本或者Linaro 7.5版本都可以。

我自己用下来最顺的是Linaro 7.5-2019.12版本的aarch64-linux-gnu工具链，因为它的sysroot里静态库齐全，Qt配置检测能通过的组件多。下载解压后放到/opt目录：

cd /opt sudo tar -xf gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu.tar.xz sudo mv gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu aarch64-toolchain

然后把工具链的bin目录加进PATH：

export PATH=/opt/aarch64-toolchain/bin:$PATH

验证一下：

aarch64-linux-gnu-gcc --version

看到版本信息输出就说明交叉工具链可以用了。

2.3 sysroot是什么，怎么准备

sysroot就是目标板的根文件系统，里面包含libc、libstdc++、libm、libz等库的头文件、动态库和静态库。交叉编译时，编译器根据--sysroot参数访问这套文件系统，而不是访问主机自己的/usr/include和/lib。

sysroot有三种准备方式：

1. 直接从目标板上拷贝。把开发板的根文件系统分区用tar打包，然后在主机上解压，这是最直接的方式。
2. 使用工具链自带的sysroot。Linaro工具链和ARM官方工具链压缩包里都带一个aarch64-linux-gnu/libc目录，这就是一个基础sysroot。
3. 用buildroot自己构建一块干净的rootfs。这种方式最灵活，但耗时比较多，适合深度定制项目。

我推荐从开发板或者仿真器镜像里提取sysroot，因为这样才能保证Qt编译时看到的头文件和库文件和你运行设备的完全一致。从目标板提取时，至少要包括以下目录：

bin boot dev etc lib lib64 opt root sbin usr usr/include usr/lib usr/lib64 usr/local

把提取出来的rootfs放到主机目录下，比如/opt/sysroot-aarch64。然后重点检查几个库文件的静态版本是否存在：

ls /opt/sysroot-aarch64/usr/lib/aarch64-linux-gnu/libc.a ls /opt/sysroot-aarch64/usr/lib/aarch64-linux-gnu/libstdc++.a ls /opt/sysroot-aarch64/usr/lib/aarch64-linux-gnu/libz.a

这三个静态库缺一不可。libstdc++.a在工具链的lib/gcc目录下也有，但建议用sysroot里的版本，避免编译器路径问题。如果只有动态库没有静态库，需要在板子上安装对应的-dev包后重新提取sysroot。

提示：检查静态库一定要看是aarch64架构还是x86架构的，用file命令验证。我曾经拿错一个x86的libc.a，编译时错误信息十分迷惑。

2.4 Qt源码下载

Qt5.14.2的源码包是qt-everywhere-src-5.14.2.tar.xz，体积大约800MB。下载方式有几种，可以用官方在线安装器，也可以直接下载离线源码包。命令行直接下载的方式最爽快：

cd ~ wget https://download.qt.io/archive/qt/5.14/5.14.2/qt-everywhere-src-5.14.2.tar.xz

下载需要一段时间，如果觉得慢，可以找国内镜像源，网易、清华、华为云都有Qt镜像。这里要说明一下，在线安装器并不强制需要额外工具，和某些需要特殊通道的软件是两个概念，只是普通的HTTP下载。

解压源码：

tar -xf qt-everywhere-src-5.14.2.tar.xz cd qt-everywhere-src-5.14.2/

3. 配置qmake平台规范与工具链文件

3.1 mkspecs是什么

Qt源码里有一个目录叫qmake/mkspecs，它管理不同平台下的编译规范。比如在x86_64的Linux上，Qt默认用linux-g++这一套；在ARM Linux上，有linux-aarch64-gnu-g++、linux-arm-gnueabi-g++这些预设的规范。

mkspecs里最重要的文件是qmake.conf，它告诉qmake三件事：

• 用什么编译器，也就是CROSS_COMPILE环境变量对应的前缀。
• 编译器、链接器的参数。
• 头文件和库文件搜索路径。

如果Qt源码里没有你想要的平台规范，也可以自己新建一个目录。我在搭建过程中直接修改了linux-aarch64-gnu-g++这个mkspecs，这个目录在Qt5.14.2源码里本身就是存在的：

ls qmake/mkspecs/devices/linux-aarch64-gnu-g++/

如果用的不是Linaro工具链，而是板卡厂商的工具链，建议新建一个专属的mkspecs目录：

cp -r qmake/mkspecs/devices/linux-aarch64-gnu-g++ qmake/mkspecs/devices/linux-aarch64-myboard-g++

然后修改里面的qmake.conf。

3.2 qmake.conf内容详解

我实际使用的qmake.conf如下，这里逐项解释关键参数：

# qmake.conf for aarch64 static build MAKEFILE_GENERATOR = UNIX CONFIG += incremental QMAKE_INCREMENTAL_STYLE = sublib include(../common/linux_device_pre.conf) QMAKE_CFLAGS += -fPIC -O2 -pipe QMAKE_CXXFLAGS += -fPIC -O2 -pipe # 交叉编译器的前缀 CROSS_COMPILE = aarch64-linux-gnu- # 编译器、汇编器、链接器 QMAKE_CC = $${CROSS_COMPILE}gcc QMAKE_CXX = $${CROSS_COMPILE}g++ QMAKE_LINK = $${CROSS_COMPILE}g++ QMAKE_LINK_SHLIB = $${CROSS_COMPILE}g++ QMAKE_AR = $${CROSS_COMPILE}ar cqs QMAKE_RANLIB = $${CROSS_COMPILE}ranlib # sysroot路径 QMAKE_CFLAGS += --sysroot=/opt/sysroot-aarch64 QMAKE_CXXFLAGS += --sysroot=/opt/sysroot-aarch64 QMAKE_LFLAGS += --sysroot=/opt/sysroot-aarch64 # 头文件和库路径 QMAKE_INCDIR += /opt/sysroot-aarch64/usr/include QMAKE_INCDIR += /opt/sysroot-aarch64/usr/include/aarch64-linux-gnu QMAKE_LIBDIR += /opt/sysroot-aarch64/usr/lib/aarch64-linux-gnu QMAKE_LIBDIR += /opt/sysroot-aarch64/lib/aarch64-linux-gnu # 静态构建需要加上的选项 QMAKE_LFLAGS += -static-libgcc -static-libstdc++ include(../common/linux_device_post.conf) load(qt_config)

有几个点必须重点说：

QMAKE_LINK_SHLIB说清楚了才能理解为什么要特意加这一行。默认情况下，Qt构建共享库时使用的链接器可能不是g++，而是gcc或者ld，这会导致C++标准库链接异常。交叉编译时指定这一行，能避免很多莫名其妙的“undefined reference”错误。

CROSS_COMPILE这个变量名在Qt5.14.2里被严格依赖，不要自作聪明改成aarch64-linux-gnu-全路径。qmake内部很多地方拿着CROSS_COMPILE拼字符串，改了这个变量的语义会崩。

--sysroot是GCC的参数，不是qmake的参数。这里必须显式加在CFLAGS和LFLAGS里，不能只依赖工具链编译时的默认配置，因为Qt的configure阶段和后续模块编译阶段对sysroot的传递并不总是可靠，手动指定最稳妥。

-static-libgcc -static-libstdc++这两个参数是给最终Qt程序链接时用的，确保最后的可执行文件不依赖目标板的libstdc++.so。

3.3 注意glibc与工具链的版本匹配

sysroot里libc的头文件版本不能高于工具链自带的头文件版本。比如工具链是gcc-linaro-7.5.0，它自带的glibc头文件比较旧，如果你从目标板提取的sysroot里libc是2.35的新版本，编译时可能会报“glibc version mismatch”的错误。

判断方法很简单：

/opt/sysroot-aarch64/lib/aarch64-linux-gnu/libc.so.6 | head -n1 /opt/aarch64-toolchain/aarch64-linux-gnu/libc/lib/aarch64-linux-gnu/libc.so.6 | head -n1

如果两个版本相差太大，建议要么换更新版本的工具链，要么手动用系统的老版本libc替换sysroot里的libc。不过后者操作起来很麻烦。最省事的方法是：先确认板子的glibc版本，然后选对应年代的工具链。比如板子是2020年之前的系统，选7.5工具链没问题；板子是2023年的系统，选ARM官方10.3工具链更稳妥。

4. configure配置与关键参数说明

4.1 configure命令全文

写好消息，前期的辛苦在这一个命令上集中体现。以下是我验证过可以顺利编译的configure参数：

./configure \ -prefix /opt/qt-5.14.2-aarch64-static \ -opensource \ -confirm-license \ -release \ -static \ -xplatform linux-aarch64-gnu-g++ \ -nomake examples \ -nomake tests \ -no-opengl \ -no-eglfs \ -no-gtk \ -no-xcb \ -no-wayland \ -no-cups \ -no-tslib \ -no-feature-vulkan \ -no-feature-xcb \ -qt-zlib \ -qt-libpng \ -qt-libjpeg \ -qt-freetype \ -no-fontconfig \ -no-harfbuzz \ -no-dbus \ -no-iconv \ -skip qtwebengine \ -skip qtwebchannel \ -skip qtwebsockets \ -skip qtwebview \ -skip qtdoc \ -skip qtlocation \ -skip qttools \ -skip qttranslations \ -skip qtserialport \ -skip qtquick3d \ -skip qtvirtualkeyboard \ -skip qtmqtt

这个命令看起来很长，实际每个参数都有存在的理由。逐条过一下：

• -prefix：安装到哪个目录，编译完成后make install会拷贝到那里。这个路径会被写入qmake自己的配置里，后续编译你的应用程序时，qmake就知道Qt的库文件头文件在哪个位置。
• -static：核心参数，告诉Qt生成静态库.a文件，而不是.so动态库文件。
• -xplatform linux-aarch64-gnu-g++：指定用哪个mkspecs。这里如果板子是新的，要写成你自定义的mkspecs目录名。
• -release：去掉调试符号，静态版本特别需要，不然体积分分钟翻倍。
• -no-opengl -no-eglfs -no-xcb -no-wayland -no-gtk：这几个都是图形平台后端。如果是纯无界面或者用framebuffer/最小linuxfb后端的应用，可以直接关掉。
• -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype：让Qt使用自带的第三方库源码，而不是依赖sysroot里可能不存在的版本。这样能保证静态编译时这些库的.a文件一定存在。
• -no-fontconfig：关掉字库配置工具。静态编译字体渲染本来就很麻烦，如果只是显示数字和简单的英文，直接用Qt内置的freetype和最简单字体加载即可。
• -no-dbus -no-iconv：关掉DBus和iconv。这对大部分嵌入式应用都无所谓，但能少编译几个模块。
• -skip qtwebengine：务必跳过webengine，这个模块太大了，而且是动态链接钉子户，静态编译它基本是自讨苦吃。

4.2 configure执行过程与源码处理

执行configure之前，一定确保前面的PATH和sysroot环境变量设置好了。建议把这些写到一个环境脚本里，每次打开终端source一下：

#!/bin/bash export PATH=/opt/aarch64-toolchain/bin:$PATH export SYSROOT=/opt/sysroot-aarch64 export CROSS_COMPILE=aarch64-linux-gnu-

执行configure以后，几分钟内会打印出大量检测信息。重点盯几个关键字：

• “The specified system/compiler is not supported” 说明mkspecs配置有问题。
• “Missing dependencies” 说明某些库检测失败，要根据日志去补sysroot里的库。
• “Configure summary” 最后会列一长串feature的启用禁用情况，重点看QtCore、QtGui、QtNetwork是否启用了。

其中一个常见报错是找不到c++11标准库头文件。解决办法是检查sysroot里的c++头文件路径是否在QMAKE_INCDIR里。Linaro工具链自带C++头文件在工具链目录下的aarch64-linux-gnu/include/c++/7.5.0，需要把这一路径也加到qmake.conf的QMAKE_INCDIR里。我在实际配置时加了这么一行：

QMAKE_INCDIR += /opt/aarch64-toolchain/aarch64-linux-gnu/include/c++/7.5.0 QMAKE_INCDIR += /opt/aarch64-toolchain/aarch64-linux-gnu/include/c++/7.5.0/aarch64-linux-gnu

不然后面QtCore编译时会报找不到cstdint、cstdlib、bits/...这些头文件，发现一个补一个非常痛苦。

4.3 configure重要输出的阅读方法

configure执行完毕后，会生成一个config.summary文件，这是你判断整个编译是否可用的第一手证据。我建议重点阅读这几段：

• “Build type”确认是linux-g++还是linux-aarch64-gnu-g++。
• “Using static linking”确认是yes。
• “Qt Network”模块里的SSL支持状态。如果SSL显示no，你的Qt程序要用HTTPS就得先解决OpenSSL的交叉编译，这单独就是一篇教程。
• “Qt Gui”里的freetype、png、jpeg状态，如果不是“yes”，说明configure命令里的-qt-freetype没生效，回去检查是否有拼写错误。

这些信息如果用错了，编译出来照样能过，但你的程序跑起来就是缺字体、缺图片解码、网络连不上。这不叫“可用的Qt”，这叫“浪费时间”。

5. 开始交叉编译Qt源码

5.1 make编译与分模块策略

经过上面这些配置，现在终于可以按下编译的启动按钮。这一步最耗时，也最容易出问题。直接执行：

make -j$(nproc)

$(nproc)会自动获取CPU核心数。如果是8核16线程的机器，-j8会比较顺畅。不建议盲目-j12以上，Qt的构建系统对并行度偶发有竞态问题，一旦出现莫名其妙的崩溃，可以先降低并行数重试。

如果内存只有8GB，建议加到16GB或者用-j4。Qt5.14.2的编译峰值内存占用还是比较高的，尤其是Qml和WebEngine模块。我试过一次用-j12编译到一半系统直接OOM，然后所有中间文件都没了，只能从头再来，那感觉太酸爽。

由于我在configure阶段用-skip跳过了大量重模块，实际编译时间在8核i7机器上大约40分钟。如果全模块编译，轻松两小时以上。

5.2 编译过程中的典型报错与应对

编译过程中最典型的报错来自三个地方。

第一个是qmake配置错误，经常在编译QtCore这个最底层模块时集中爆发。报错一般是“fatal error: cstddef: No such file or directory”，或者“stdio.h: No such file or directory”。出现这种问题，基本就是sysroot的usr/include目录没配对。解决办法：

ls /opt/sysroot-aarch64/usr/include/stdio.h ls /opt/sysroot-aarch64/usr/include/aarch64-linux-gnu

如果stdio.h找到了但编译器依然报找不到，大概率是--sysroot参数没进到编译命令里。在qmake.conf里再加一个硬编码的CFLAGS项，或者在configure之前export CFLAGS和CXXFLAGS：

export CFLAGS="--sysroot=/opt/sysroot-aarch64" export CXXFLAGS="--sysroot=/opt/sysroot-aarch64"

第二个是链接阶段报“cannot find -lts”，原因是configure阶段没有把tslib关干净。解决方法是回到configure命令，确认有没有-no-tslib参数。如果忘了，只能重跑configure再make distclean。

第三个是“libgcc_s.so.1 must be installed for pthread_cancel to work”。这是典型的静态链接pthread残留问题，解决办法是确保qmake.conf里有-static-libgcc和-static-libstdc++，并且在make install时确认目标板的libpthread.a存在。

5.3 make install安装到前缀目录

编译结束后执行：

make install

安装过程会往/opt/qt-5.14.2-aarch64-static目录写入头文件、库文件、qmake、mkspecs和一堆辅助工具。

安装完成后，检查关键文件：

ls /opt/qt-5.14.2-aarch64-static/lib/ ls /opt/qt-5.14.2-aarch64-static/bin/qmake

如果是静态编译，lib目录下应该有一大批.a文件，比如libQt5Core.a、libQt5Gui.a、libQt5Widgets.a等。

此时需要把qmake路径加到PATH里，后续编译你的应用程序都要用它：

export PATH=/opt/qt-5.14.2-aarch64-static/bin:$PATH

6. 用编译好的Qt编译你的第一个aarch64静态程序

6.1 创建最小Qt工程

创建一个最简单的测试工程，验证整条链路是否通。

mkdir ~/qt-test && cd ~/qt-test

写test.pro：

QT += core gui widgets TARGET = testapp TEMPLATE = app CONFIG += c++11 SOURCES += main.cpp

写main.cpp：

#include <QApplication> #include <QLabel> int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label("Hello aarch64 Qt5.14.2 static"); label.show(); return app.exec(); }

6.2 使用交叉qmake编译

这里有个坑必须避开：不能用系统自带的qmake，必须用刚才交叉编译出来的qmake。它内部的库路径是arm64的，用系统的x86 qmake编译出来的程序在架构上就是错的。

/opt/qt-5.14.2-aarch64-static/bin/qmake test.pro make

如果一切顺利，会生成一个testapp可执行文件。用file命令验证架构：

file testapp

输出应该包含：

ELF 64-bit LSB executable, ARM aarch64, dynamically linked (uses shared libs)

看到“statically linked”或者至少“dynamically linked”里的库列表没有Qt库。

6.3 静态链接的验证

判断静态链接是否成功，不能光看file命令，还要用readelf或者ldd检查。

aarch64-linux-gnu-readelf -d testapp | grep NEEDED

一个真正的Qt静态可执行文件，NEEDED列表里应该只剩下一堆系统库，比如libc.so.6、libstdc++.so.6、libm.so.6、libgcc_s.so.1，绝对不能出现libQt5Core.so.5、libQt5Gui.so.5。

或者直接看ldd，不过要记住这只能交叉查看：

aarch64-linux-gnu-readelf -l testapp | grep INTERP

如果输出里没有“dynamic linker”相关信息，说明连动态解释器都没有，是纯静态。

6.4 目标板上运行的注意事项

把testapp从主机拷贝到目标板，注意两点：

• 权限要加执行权限：chmod +x testapp。
• 如果目标板系统是定制裁剪过的，可能连libc.so.6都没有。静态版本能跑是因为它把大部分内容都打包进去了，但libc.a里面仍有可能引用到动态加载器，如果目标板连/lib/ld-linux-aarch64.so.1都不存在，就需要进一步处理。

实际上要在目标板上跑起来，最靠谱的验证方式就是scp到板子上直接运行。

scp testapp root@192.168.1.100:/root/ ssh root@192.168.1.100 "chmod +x /root/testapp && /root/testapp"

如果看到窗口弹出来或者终端有Qt启动日志，就说明整条静态交叉编译链路全通了。

7. 依赖库静态打包的思路与注意事项

7.1 核心依赖库的选取

如果你开发的程序用到了Qt Network里的SSL、Qt SQL里的sqlite、Qt GUI里的字体和图片，就需要额外交叉编译这些依赖库，并保证它们的.a版本在sysroot里。

静态链接依赖库的顺序问题在这里尤其突出。链接时，库的先后顺序决定符号解析是否能成功。以前我用Qt自带网络模块连接HTTPS，结果一直报OpenSSL符号未定义，后来发现是openssl.a放的位置不对。Qt生成的Makefile里LIBS顺序通常是：

-L/opt/qt-5.14.2-aarch64-static/lib -lQt5Network -L/opt/openssl-aarch64/lib -lssl -lcrypto

如果openssl.a放在Qt5Network.a前面，链接器会先遇到ssl库但当时还不知道需要什么符号，等Qt5Network符号解析完再回头找ssl，但链接器已经不会回去处理已经扫描过的库了。解决办法是尽量把依赖的外部静态库放在Qt库后面。

7.2 字体与图形后端

纯静态编译时，fontconfig一关，字体的加载方式就变了。Qt默认用Fontconfig找系统字体，这依赖一堆动态库，静态编译基本不现实。我在配置里用了-qt-freetype和-no-fontconfig，这样Qt会直接用自己的freetype读取字体文件。目标板上必须在能访问到的路径放一个字体文件，比如/usr/share/fonts/或者程序工作目录。

如果程序需要显示中文，但目标板没有中文字体，Qt会显示一堆方块。解决方法是把字体文件打包到程序资源里，在main函数里加Qt字体加载代码：

QFontDatabase::addApplicationFont(":/fonts/DroidSansFallback.ttf"); QApplication::setFont(QFont("Droid Sans Fallback"));

7.3 OpenSSL的交叉编译

Qt静态链接OpenSSL是另一个常见任务。这里简化一下流程，交叉编译OpenSSL并生成.a文件：

./Configure linux-aarch64 \ --prefix=/opt/openssl-aarch64 \ --cross-compile-prefix=aarch64-linux-gnu- \ shared static make make install

注意OpenSSL的configure脚本用的是Configure而不是config，而且必须加“static”参数。编译完成后，在qmake.conf的QMAKE_LIBDIR里加上openssl的lib目录：

QMAKE_LIBDIR += /opt/openssl-aarch64/lib

然后在Qt源码的configure阶段，或者修改Qt的mkspecs里加上：

QMAKE_INCDIR += /opt/openssl-aarch64/include

为了确保Qt检测到OpenSSL，configure时还可以加：

-I/opt/openssl-aarch64/include -L/opt/openssl-aarch64/lib -lssl -lcrypto

不过这个比较折腾，大多数场景下如果你只是做简单的网络访问，直接放弃HTTPS、用TCP或者HTTP，反而省事得多。

8. 常见问题速查表

我把实际搭建过程中遇到的坑和网上的高频问题整理成一张速查表。

9. 静态编译体积控制与部署技巧

9.1 减小体积的基本手段

静态编译出来的Qt程序普遍偏大，这是固有的代价。好在有一些手段可以把体积从80MB压到30MB左右：

• 编译时使用-release加-O2，去掉调试信息：在qmake里加CONFIG += release。
• strip符号表。编译完成后执行strip --strip-unneeded testapp，这个操作常常能砍掉20%-40%体积。
• 跳过不用的模块。configure阶段的-skip参数能省下一大批模块，静态编译时每多一个Qt模块，最终可执行文件就会大好几MB。我最小配置时只用core、gui、widgets三个模块，程序最终16MB。
• 使用Qt的feature削减宏。比如不需要拖拽、剪贴板这些功能，可以通过-QT_NO_CLIPBOARD这类编译宏排除。

9.2 部署时的建议

部署阶段有几个经验值得分享：

• 静态编译的可执行文件最好存放在只读分区，避免被意外覆盖。
• 如果程序使用配置文件，建议把配置文件路径和程序路径分开，这样升级时只替换可执行文件即可。
• 字体文件单独放，不要打进可执行文件里，除非你有严格的单一文件部署需求。打进程序里每次改字体都要重新编译，太不方便。

10. 从无到有的整体经验总结与扩展思路

10.1 我的实操体会

这条链路从头到尾走一遍，最大的感受是：静态交叉编译Qt的关键不在Qt源码本身，而在sysroot的质量和工具链的匹配度。Qt的configure只是把那套依赖关系暴露出来的工具。很多初学者遇到编译失败，在Configure参数里反复试，其实是舍本逐末。先把工具链和sysroot搞干净，Configure一次过的概率会高很多。

如果你要做的项目和我的情况类似，我建议第一次搭建时不要追求一次性全功能编译，先把最小化配置编译通，确保core、gui能出来，再去逐步添加模块。我的做法是：

1. 先编译一个只有QtCore的最小配置。
2. 编译一个测试程序，确认静态链接成立。
3. 再开启QtGui和QtWidgets。
4. 最后才考虑网络、数据库这些重量级模块。

这样每次只增加一个新的变量，出了错也知道是哪个模块引起的，不会一改一堆最后全乱套。

10.2 后续还能扩展什么

搭建完成以后，这套环境能做的事情就很多了。你可以在这套静态编译的Qt上接着做：

• Qt Quick/QML模块的交叉编译，不过体积会显著增加。
• 集成OpenSSL做HTTPS设备客户端。
• 集成SQLite模块做本地数据存储。
• 加tslib支持触摸屏输入。
• 将整个系统做成镜像，用buildroot或者Yocto集成进去，实现一键量产。

静态编译Qt只是手段，真正重要的是那种“一次构建、随处运行”的稳定体验。在工业现场，设备三五年不关机，部署一次以后再也不用跑过去改库路径、补依赖，那才能真正体会到当时花这些时间搭环境的回报。