企业官网建设流程全解析

1. 这个组合有什么讲究：为什么偏偏是5.14.2和静态

嵌入式Linux圈子里的老人应该都有同感：给目标板交叉编译一套Qt，表面上是跑一条configure加make，实际上是在跟版本、架构、依赖链玩排列组合。我最早在ARM32上折腾Qt 5.9，后来换到aarch64，又追过5.15、6.2，绕了一大圈，最后却把工程基线锁在了Qt 5.14.2上，而且是静态编译。不是怀旧，是被现实教育出来的。

先说说版本。Qt 5.14.2属于Qt 5系列的LTS分支，官方对它的维护周期拉得很长，商业支持到2023年之后，社区补丁也持续了相当久。对嵌入式产品来说，"没人追着你升版本"就是最大的幸福感。6.x虽然新，但License和模块划分的变动让很多老工程要重做集成，qml模块的底层渲染架构也换了，旧代码迁移成本不是一般的高。更何况aarch64的交叉编译链对5.14.2的支持早就被无数人验证过，踩坑资料一搜一大把。对做产品的人来说，稳定可复现，比"版本号最新"重要得多。

再说架构。aarch64如今几乎成了新硬件平台的默认选项，瑞芯微RK3568、RK3588，全志T507，树莓派CM4，飞腾、鲲鹏服务器，清一色的AArch64。开发机上x86_64编译，目标板aarch64运行，交叉编译就是绕不开的基本功。而静态编译又是嵌入式部署里的硬需求，为什么要静态？我列个对比你感受一下：

我之前在某个基于Linux的仪表项目上体验过动态编译的痛：研发好的程序移植到产线设备上，前一秒还跑得好好的，换一批硬件批次之后QtQuick渲染直接花屏，查了半天是rootfs里某个so版本被系统更新覆盖了。从那以后，凡是交到现场的嵌入式程序，我默认上静态编译，宁可编译机多吃半小时，也不愿去追一个现场问题。

这套手册我就基于Qt 5.14.2 + aarch64 + 静态编译三个关键点，把从零搭建到产出可运行程序的完整过程掰开揉碎讲完，不绕弯子。

2. 折腾开始前的环境盘整：主机、工具链和sysroot

标题里写着"从零搭建"，那咱们就真的从零开始。我先把我这次搭建用的环境完整交代清楚，你照着做至少不会在第一步就卡住。

2.1 主机环境与注意事项

我用了Ubuntu 20.04 LTS x86_64的干净系统来做编译主机。说实话，Ubuntu 18.04和22.04我也试过——18.04的gcc版本偏老，编译新内核头文件时容易语法报错；22.04的gcc 11在编译旧代码时告警多得眼花。20.04的gcc 9算是兼容性比较好的平衡点。如果你手里已经是其他版本，也没关系，后面我会提到用容器或Sysroot规避差异的办法。

主机上要装的基础依赖，老生常态但必须列全：

sudo apt update sudo apt install -y build-essential flex bison gperf libicu-dev \ libxslt-dev libxkbcommon-dev libgl1-mesa-dev libegl1-mesa-dev \ libfontconfig1-dev libfreetype6-dev libssl-dev python3 \ ninja-build cmake g++-aarch64-linux-gnu

注意最后这个g++-aarch64-linux-gnu——Ubuntu对自己的交叉编译链做了Debian系patch，直接用它是省事的，但后面要小心，系统的交叉编译器如果带了额外的安全加固选项，有概率影响Qt某些模块的编译。我们先以这个工具链为基准，后面如果遇到汇编报错再换Linaro或其他版本。

2.2 交叉编译工具链的取舍：我为什么不用完整自编译

很多教程第一步就是让你下载crosstool-ng自己搓一套编译器，说实话，这有点仪式感过剩了。对于Qt这种应用层框架的交叉编译，你需要的不是一个从零编译的GCC，而是一套和目标板rootfs匹配的Sysroot。

Sysroot这个概念，打个比方：交叉编译就像在图纸上给另一座城市装修房子，你没法去现场量尺寸，就靠一套"户型图集"来做事。Sysroot就是这套图纸，里面存着目标板的头文件、标准库、各种底层依赖库的.so文件，让编译器的链接器知道目标板子上到底有什么。

我推荐两条稳定的工具链途径：

途径一：Ubuntu自带交叉工具链 + 手动补齐Sysroot

最简单，适合快速验证。安装g++-aarch64-linux-gnu后，工具链自带一份基础的aarch64 Sysroot，路径在/usr/aarch64-linux-gnu，里面有libc、libstdc++等基础库，但缺很多图形和系统相关依赖，需要手动从目标板的rootfs里补齐（比如libfontconfig、libdbus、libxkbcommon等等）。如果你直接用它编Qt，大概率会在configure环节报"missing dependencies"。

途径二：使用配套的交叉编译SDK

比如用Linaro提供的aarch64-linux-gnu工具链，解压出来的文件夹里自带完整的Sysroot，省去手动补齐的麻烦。下载地址这里就不贴了，搜索引擎关键词"Linaro aarch64-linux-gnu toolchain download"就能找到官方release包。我实测下来，Linaro 7.5版本的编译器编译Qt 5.14.2非常顺手，几乎没有坑。

我这次手册以途径一为例展开，因为Ubuntu包管理器安装工具链最方便，同时我会在2.3节把Sysroot补齐的操作讲清楚，这条路线一旦打通，你以后面对任何目标板都心里有数。

2.3 手动补齐Sysroot依赖

不管你是用哪种工具链，核心思路一致：把目标板运行时要调用的库的头文件、.so链接文件，都放到编译器能找到的Sysroot目录里。

这里有一个关键操作，别把目标板的.so直接整个拷进去，-dev包里的.so通常是指向实际版本号文件的软链，而目标板为了省空间往往删掉了这些软链。手动补齐流程大概是这样的：

1. 在目标板上执行dpkg -l | grep lib，列出板子装过的库清单，挨个去对应源里下载-dev版本，统一解包到一个目录。
2. 用rsync把解包出来的usr/include和usr/lib/aarch64-linux-gnu合并到交叉工具链的Sysroot里：

# 将补齐的devel包拷贝进sysroot sudo rsync -av /path/to/collected-rootfs/usr/ /usr/aarch64-linux-gnu/usr/

3. 注意符号链接！在Sysroot里检查一下libstdc++.so是否存在且指向了正确的.so.6：

ls -l /usr/aarch64-linux-gnu/usr/lib/aarch64-linux-gnu/libstdc++.so

如果缺失，ln -sf libstdc++.so.6 libstdc++.so补上。

这一步做得好不好，直接决定后面configure能不能过。很多人的Qt交叉编译死在"libGLESv2.so not found"上，多半就是Sysroot里的链接文件不完整。

3. configure这一步值半篇手册：逐项参数说明

Qt的configure脚本是整个编译流程里最容易被低估的一环。它的成败不取决于你敲了多少参数，而取决于你理解不理解每个参数在干什么。交叉编译配置错了，后面make的时候报错会非常诡异，指向的完全不是真正的问题。所以这一节我打算把核心配置项一个个拆开讲清楚。

3.1 静态编译的核心configure片段

先给一个能直接在Ubuntu 20.04 + aarch64-gnu环境里复现的完整配置命令：

cd /path/to/qt-everywhere-src-5.14.2 ./configure \ -prefix /opt/Qt5.14.2-aarch64-static \ -opensource -confirm-license \ -xplatform linux-aarch64-gnu \ -release \ -static \ -no-feature-glib \ -no-feature-cups \ -no-feature-dbus \ -no-feature-openssl \ -nomake examples -nomake tests -nomake tools \ -skip qtwebengine -skip qtwayland -skip qtscript \ -qt-xcb \ -qt-pcre -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype \ -no-feature-assistant -no-feature-designer \ -fontconfig \ -no-eglfs -no-linuxfb -no-kms -no-opengl \ -I/usr/aarch64-linux-gnu/usr/include \ -L/usr/aarch64-linux-gnu/usr/lib/aarch64-linux-gnu

3.2 几个坑点逐一分析

先看-xplatform linux-aarch64-gnu。这里我踩过一个坑：很多人误以为Qt每个架构都有一套独立的platform文件，其实Qt的qmake/mkspecs目录下只给了少量参考specs。linux-aarch64-gnu在5.14.2里正好有，它内部其实是引用了linux-generic-g++再叠加大端小端、位数等参数，所以不要自作主张去创建自定义specs，除非你确实遇到了非改不可的情况（比如指定musl libc）。

然后是-static。这一个参数会让Qt内部所有模块都以静态库的方式编译。这里有个隐藏逻辑：-static打开后，默认的-qt-xcb变成了硬依赖，因为Qt不能再用动态方式加载xcb的插件。所以上面命令里我专门加了-qt-xcb，并且补了-qt-pcre -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype，全部用Qt源码树里自带的三方库做静态链接——千万不要省略这组-qt-*参数，否则configure会在检测系统版本库时，因为Sysroot里的库版本不匹配而报错或者编译出行为诡异的程序。

关于模块裁剪-skip qtwebengine -skip qtwayland -skip qtscript，这三个我建议必加。WebEngine是出了名的重，本身依赖一堆系统库，而且静态编译时它对GPU和沙箱的要求会直接导致链接失败，普通人没必要碰。Wayland在纯X11环境下完全用不上，剪掉能省下十几分钟的编译时间。Script模块我遇到过一次编译错误，后来直接跳过，省心。

接着看-no-eglfs -no-linuxfb -no-kms -no-opengl，这几个是很多人纠结的地方。如果你的目标板子上没有GPU、没有OpenGL支持，那就老老实实全关。如果板子上有Mali核心或者Vivante，那才需要针对性打开eglfs和opengl。我这次手册针对的是那些只跑业务逻辑、界面上不需要3D加速的设备场景。静态编译加OpenGL是另一个深坑，这里先绕开它，后面有空我会单独写一篇OpenGL ES的交叉编译笔记。

-no-feature-glib -no-feature-cups -no-feature-dbus分别关掉glib主循环集成、打印机支持、D-Bus总线。关D-Bus这条要说明一下：不是所有Qt程序都需要D-Bus，只有用systemd或者桌面组件深度集成才需要，嵌入式板卡上多数是纯业务程序，关掉后编译和运行都更稳。

最后单说-fontconfig。我保留了fontconfig，因为它对文本渲染太重要了，特别是中文环境。日常项目里至少要用到中文字体，如果关掉fontconfig，你就只能依靠Qt自己的freetypeDirectFontDatabase，字体匹配和回退规则会痛苦很多。保留fontconfig的同时要确保Sysroot里有libfontconfig1-dev。上面的configure命令里我把-I和-L都指向Sysroot路径，就是为了让configure检测fontconfig时能找到头文件。

3.3 configure的输出检查清单

configure跑完后不要急着往下走，先检查打印日志。我总结了几个值得关注的标记：

1. Qt is now configured for building：确认出现这一行，说明基本通过。
2. 检查生成的config.summary，主要看以下几行：
   • Build .................. static
   • Platform ................ linux-aarch64-gnu
   • Xcb .................... yes
   • FontConfig ............. yes
3. 检查有没有出现"WARNING: ... is not available"之类的警告，尤其xkbcommon和xcb-xlib。如果这两个出现no，最后的程序可能连界面窗口都弹不出来。

出现"WARNING"级别的问题倒不用慌，日志里会告诉你缺的是运行时依赖还是编译依赖，照着补齐Sysroot再重新configure即可。

4. 编译期间的坎：实际报错与完整定位链路

configure过了，make的时候才算真正进入"从零搭建"的战场。我把自己在这条路上真实踩过的三个典型报错，连同完整排查思路写出来，这段内容是网上教程最缺乏的部分。每个报错我不会直接给答案，先把排查链路摆出来，你再对照自己的情况判断。

4.1 报错一：/usr/lib/gcc-cross/aarch64-linux-gnu/7/../../../../aarch64-linux-gnu/bin/ld: cannot find -lGL

这个报错几乎是交叉编译Qt的"打卡题"。字面意思是链接器在Sysroot里找不到libGL库。但要注意，这个GL不是OpenGL的GL，很多时候是Qt的xcb插件代码默认要链接OpenGL库（即使你关闭了OpenGL功能，某些共享代码块还是写死了GL头文件和库）。

排查链路是这样走的：

• 第一步，确认Sysroot里到底有没有libGL相关的库：

find /usr/aarch64-linux-gnu -name "*libGL*"

• 我实测的时候发现Ubuntu的交叉Sysroot里确实没有libGL.so（因为桌面主机的libGL是Mesa的，交叉Sysroot没有对应包）。这就是根源。

解决的办法有两种：

一个是干脆把Qt源码里xcb的OpenGL挂钩去掉，打开qtbase/src/plugins/platforms/xcb/xcb.pro，搜索GL相关行，把xcb-glx相关的SOURCES注释掉。二是直接造一个空的libGL软链：

sudo ln -s /usr/aarch64-linux-gnu/usr/lib/aarch64-linux-gnu/libGL.so /usr/aarch64-linux-gnu/usr/lib/aarch64-linux-gnu/libGL.so.1

第一个方案更干净，因为应用本身用不到GL，但是折腾源码不够优雅；第二个方案在Sysroot里放一个"安慰剂"，10秒解决问题，非常实用。我实际用了第二个方案，后续没有再出现GL报错。

4.2 报错二：error: unknown type name 'char16_t'或者'u8_string' has not been declared

这个报错出现的位置通常在Qt的src/corelib/text/qstring.h附近，大概长这样：

qstring.h:113: error: unknown type name 'char16_t'

刚看到时我愣住了，因为char16_t是C++11标准里就有的东西。仔细一想，问题在于交叉编译链的默认语言标准。Qt 5.14.2的某些头文件没有显式用std::u16string，直接裸用了char16_t，如果编译命令里没有带上-std=c++11或者更高标准，古老的GCC版本就会报这个错。

排查时我先验证了一下交叉编译器的标准支持：

aarch64-linux-gnu-g++ -std=c++11 test_char16.cpp -o /dev/null

结果通过。说明编译器没问题，是configure阶段没把-std传进去。然后我去看了Qt生成的qmake.conf，发现QMAKE_CXXFLAGS里没有-std。我直接在环境变量里给编译选项加料：

export CXXFLAGS="-std=c++11" export CFLAGS="-std=c11"

加完重新configure、make，这个报错消失。事后复盘，很可能是Ubuntu自带的g++-aarch64-linux-gnu patch版本把默认标准改了，导致Qt的检测逻辑误判。如果你用的是Linaro工具链，大概率不会碰到这条。

4.3 报错三：Qt虚拟键盘模块编译时Assimp相关错误

严格说这不是必须装的模块，但如果你在configure里用了-skip没完全跳干净，某些子模块还是会带出隐性依赖。我遇到的是qtvirtualkeyboard在静态编译下尝试链接assimp，报了一堆类型推导错误。

这个问题的完整排查链路是：先去qtvirtualkeyboard/src/virtualkeyboard/virtualkeyboard.pro里面看样式，发现它contains(QT_CONFIG, opengl)的地方才启用assimp。因为我在configure里已经-no-opengl，理论上不该走到这里。后来检查了一下我命令行里的-skip，发现只跳了webengine、wayland、script，确实没跳virtualkeyboard。

根本原因是：configure检测opengl虽然关了，但是Qt的主题模块里virtualkeyboard的pro文件有bug，在无opengl时检测条件没有正确短路。

解决方式是加一条环境变量：

export QT_BUILD_PARTS=""

或者更直接把这个模块跳过去，把-skip qtvirtualkeyboard加进configure参数列表，重新跑一次configure。

把这三条报错排完，make基本就能一路半通畅了。我自己完整make的时间大约需要40到60分钟，取决于机器核心数。建议用make -j$(nproc)，但如果你内存小于16G，建议-j4，别把编译机跑死。

4.4 编译产物的结构解读

编译结束后在/opt/Qt5.14.2-aarch64-static下会看到一个典型的Qt目录结构。特别提醒一下：静态编译模式下，lib/目录下的.a文件才是主角，比如libQt5Core.a、libQt5Widgets.a、libQt5Gui.a，它们的大小加起来可能超过800MB。bin目录下有一些工具如moc、rcc、uic，这些是主机架构的，不是目标板的，交叉编译应用时需要显式把/opt/Qt5.14.2-aarch64-static/bin加入PATH。

另外，qmake文件路径在/opt/Qt5.14.2-aarch64-static/bin/qmake，这个文件本身是主机可执行的，用来生成目标板的Makefile，别把它拷到板子上（这也是一个天然陷阱，我见过新人把qmake拷到板子上运行的）。

5. 产物的部署验证：ldd、qt.conf和板端运行

静态编译最终目标就一句话：产出一个file显示为ELF 64-bit LSB executable, ARM aarch64的可执行文件，丢到板子上就能跑。但拿到可执行文件不代表结束了，部署验证的过程里依然有暗坑。

5.1 用file和ldd做第一轮体检

编译完一个简单的Qt Widgets应用后，先在本机做体检：

file ./hello_world # 应该输出 ELF 64-bit LSB executable, ARM aarch64 aarch64-linux-gnu-readelf -d ./hello_world | grep NEEDED

readelf打印出来的NEEDED列表里，如果干干净净只剩libc.so.6、libm.so.6、libstdc++.so.6这类系统基础库，说明静态链接成功。如果还看到libQt5Core.so.5之类的影子，那说明链接用的qmake配置没生效，回头检查是不是PATH里的qmake还是主机版本。

这一步经常被忽略，但它能提前拦下一大批"部署到板子上崩了"的问题。在Linux终端上静态链接Qt应用，其实还有一个隐藏风险：部分系统库可能被gcc隐式链接成动态版本。排查时我用readelf认真确认了NEEDED列表，结果发现竟然还有一个libdl.so.2，这通常是正常的，因为C++运行时库的内部实现依赖dlopen，即使静态链接也会隐式带上。

5.2 qt.conf是静态应用的救星

很多人在板子上跑Qt程序，遇到的经典报错是：

qt.qpa.plugin: Could not find the Qt platform plugin "xcb" in ""

动态编译时换个路径就得改环境变量，但静态编译更尴尬——如果你configure时指定了-prefix /opt/Qt5.14.2-aarch64-static，那么qmake会在编译期把这个绝对路径编译到Qt的QLibraryInfo内部机制里，运行时它仍会去/opt/Qt5.14.2-aarch64-static/plugins找平台插件。可你的板子上根本不存在这个目录。

解决方案就是在可执行文件同级目录下放一个qt.conf文件：

[Paths] Prefix = . Libraries = lib Plugins = plugins Imports = imports Qml2Imports = qml

这个qt.conf的作用是告诉Qt运行时，所有资源都从当前目录开始搜索。静态编译模式下，其实所有Qt库都已经链接进可执行文件了，plugin目录也基本用不到（除非你用了需要编译进二进制的插件机制），但写上它能让Qt内部那些基于QLibraryInfo的路径判断全部短路，省掉90%的运行时路径问题。

5.3 板端验证：跑起来只是第一步

把编译好的二进制和qt.conf一并拷到板子，运行前先用chmod +x保证权限，然后执行：

./hello_world -platform xcb

如果板子是纯headless环境（无屏幕、无X11），这里会报连接失败。我之前做的就是带屏设备，所以没问题。跑完窗口弹出来之后，再执行一个简单的自检：

while true; do ./hello_world -platform xcb & sleep 5; kill $!; done

连续启停20次，观察内存有没有泄漏、有没有段错误。静态链接的应用虽然在启动速度上有优势，但若代码里使用了Qt的全局静态对象，在exit时偶尔会遇到析构顺序问题，提前这样压力测一下能筛掉大部分部署隐患。

6. 再往深走一步：模块裁剪与体积优化

静态编译最大的槽点就是"体积爆炸"，动不动一个hello world都要十几MB，带着QtWidgets的完整业务程序随随便便50MB起步。如果你的板子flash只有128MB，就要考虑做体积优化了。这块内容在基础手册里常常被放在最后，但我个人认为它反而是产品化之前最关键的一步。

6.1 用feature机制去掉用不到的模块

Qt 5.14.2的configure脚本支持大量-no-feature-*开关，可以精准禁用Qt特性。有些特性在嵌入式场景里毫无用处，禁掉可以让代码规模和运行时内存同时下降。我在实际项目中已经验证过的安全裁剪项包括：

-no-feature-texthtmlparser \ -no-feature-textodfwriter \ -no-feature-printdialog \ -no-feature-printpreviewwidget \ -no-feature-imageformat_bmp \ -no-feature-imageformat_ppm \ -no-feature-imageformat_xbm \ -no-feature-imageformat_xpm \ -no-feature-dns-lookup \ -no-feature-ftp \ -no-feature-http

每裁剪一个特性，静态链接时那个模块的代码就从二进制里消失，体积能明显下降几MB。但要注意，这些开关必须以Qt官方特性名称为准，需要先跑./configure -list-features查看完整列表，再逐个确认，不要凭感觉瞎猜。

6.2 编译器和链接器的优化参数

除了Qt层面的裁剪，GCC侧的优化也不能放过。我在qmake工程文件里加入了这几个flag：

QMAKE_CXXFLAGS_RELEASE += -Os -fno-keep-inline-dllexport -fvisibility=hidden -fvisibility-inlines-hidden QMAKE_LFLAGS_RELEASE += -s

-Os针对体积优化（不是-O2），-fvisibility=hidden把默认导出符号全部隐藏，链出来的二进制里只保留必要符号，-s更是直接strip掉符号表。这几个参数加完，我的一个短线通讯小程序体积从25MB缩小到13MB，效果立竿见影。

不过别把链接器剥得太狠，-s会把调试符号全删掉，板子上如果崩溃了，addr2line都解析不出来。真实项目的做法是：保留一份带符号的原始二进制，部署时用strip过的版本。

6.3 字体和资源的后期瘦身

静态链接之后，字体的体积往往超过二进制本身。Qt的fontconfig会搜索系统字体目录，如果你的板子上没有对应字体，程序界面的中文全部变成豆腐块。解决方案是把需要的字体子集化，我用过pyftsubset裁字体：保留常用3500个汉字和标点，一个原本18MB的思源黑体，裁完之后只有2.3MB，画质肉眼看不出区别。具体命令：

pyftsubset SourceHanSansCN-Regular.otf \ --text-file=chinese_common.txt \ --output-file=SourceHanSansCN-Subset.otf \ --layout-features='*' \ --glyph-names \ --symbol-cmap \ --legacy-cmap

然后在程序里显式指定字体文件路径，或者放到板子的/usr/share/fonts下让fontconfig自动识别。

7. 换个思路：把这套流程沉淀成可复用的编译脚本

最后一节我想聊点"手册之外"的东西。整套流程跑通之后，如果每次重编都手动敲configure那2000个字的命令，迟早会出错。我在项目里把它沉淀成了一个bash脚本，如今从零到出二进制，只需要一个参数指定源码路径即可。

脚本主体逻辑很直白：

#!/bin/bash TARGET_ROOT=/opt/Qt5.14.2-aarch64-static SYSROOT=/usr/aarch64-linux-gnu/usr QT_SRC=/path/to/qt-everywhere-src-5.14.2 export PATH=/opt/Qt5.14.2-aarch64-static/bin:$PATH export CROSS_COMPILE=aarch64-linux-gnu- export CXXFLAGS="-std=c++11" export CFLAGS="-std=c11" cd $QT_SRC ./configure \ -prefix $TARGET_ROOT \ ...（一系列参数）... make -j$(nproc) make install

这个脚本我放在公司的内部代码仓库里持续维护，每次换一台新编译机，跑一遍脚本就能复现完全一致的Qt环境。对于做嵌入式产品的人来说，"环境可复现"比"技术选型时髦"重要得多，因为产线人员不需要理解configure的每个参数，他们要的只是一个可靠的流水线。

我个人在实际操作中还养成了一个习惯，每次configure之前都会先跑一次git diff确认Qt源码有没有被本地patch污染过。有一次我发现同事为了修一个字体渲染问题，直接改了qfontengine_ft.cpp源头文件，后来升级Qt版本时把这个改动丢了，字体问题神秘复发，排查了很久才发现是源码被本地改过。Qt框架这种量级的代码库，有任何本地patch都要归入版本管理，留好记录，不然"从零搭建"最后会变成"从玄学搭建"。

再分享一个扩展方向：qt-everywhere里其实还带qtquickcontrols2等模块，如果你需要做富媒体界面，也可以交叉编译QML相关的部分，静态链接下QML的plugin机制是打包进QRC资源文件里的，部署方式会更统一，这个后续值得专门开一篇写。

这篇手册到这里，该记录的坑都记录了，该给的建议也都给了。希望你能在第一次configure就顺利通过。