1. 先把问题定义清楚静态交叉编译到底在解决什么Qt5.14.2 在 aarch64 上的静态交叉编译说白了就是两件事叠在一起第一件是让 x86_64 主机上的一套编译器能产出目标板子ARM64 架构能跑的二进制第二件是让 Qt 的库代码在链接阶段就被焊死进可执行文件里而不是等程序跑起来再去板子上找.so。这两件事单独看都不算难叠在一起就会出现大量的组合坑比如工具链的 sysroot 不干净、qmake 的 mkspec 写得不对、静态插件的导入符号没写全、glibc 和 libstdc 的静态版本选错等等。为什么现在还有人愿意折腾 Qt5.14.2 这个版本因为它在工业 HMI、车载仪表、医疗器械面板、边缘计算盒子这些场景里依然是主力版本很多板卡厂商的 BSP 就是围绕 5.12 到 5.15 这一段做的适配生态和第三方库也跟着这个区间走。你在这种项目上换 Qt6往往意味着整个板子的显示、输入、字体方案都要重新验证一遍成本上不划算。适合阅读这篇内容的人大致是三类。第一类是做嵌入式 Linux 应用开发手上有一块 aarch64 的板子想把自己的 Qt 程序做成拷过去就能跑的单一文件第二类是被动态库的版本冲突折腾过比如板子上已经有一套 Qt 的动态库但你不想动它也不希望自己的程序被它绑定第三类是单纯想把构建链摸清楚的开发者想弄明白 configure 那一长串参数背后各自在干嘛。这三类人关注点不同但需要的底层知识是同一套。我下面写的流程是基于 x86_64 Ubuntu 宿主机 aarch64 交叉工具链 Qt 官方源码包这套最常见的组合来展开的。如果你用的是其他发行版或者其他工具链厂商的包思路一致改的就是路径和名称。整套流程我在实际项目里跑过不止一遍中间踩的坑也会一并写出来省得你重复交学费。2. 方案选型静态、动态、半静态该怎么选2.1 三种交付方式的实际差别在动手之前先想清楚是不是真的需要静态。很多人在项目初期一拍脑袋选了静态结果后面发现某个闭源库只提供动态版本返工代价很大。这三种方式的差别我用一个表格先摆出来。交付方式部署产物优点主要代价全动态可执行文件 一堆 .so体积最小升级单个库方便依赖版本强绑定板子环境一变就崩Qt 库静态单个或少数几个可执行文件部署简单不受板子 Qt 版本影响单文件体积大编译时间长插件要手动导入完全静态含 libc单个完全自包含文件理论上零依赖glibc 静态化有 DNS、NSS 等已知限制慎用实际操作里绝大多数人说的静态 Qt指的是第二行Qt 自身的库静态链接但 libc、libstdc 仍然按动态方式链接或者用-static-libstdc把 C 运行库也静态进去。这是最平衡的做法也是我这篇内容的主线。2.2 为什么 glibc 不建议完全静态化glibc 从设计上就不太欢迎完全静态链接。它的一些功能——比如用户组查询、名称解析——依赖运行时的动态加载机制静态化之后会走降级路径甚至直接失败。你的程序如果只做本地 UI、读写文件、走 socket一般感觉不到但只要有主机名解析、账户体系相关的调用问题就会冒出来。所以配置 Qt 的时候用-static让 Qt 库静态化就够了不要顺手给全局链接选项加-static。-static-runtime这个参数要单独提一句。它在 Qt 的配置脚本里主要服务于 Windows 工具链场景用来静态链接 MSVC 运行时在 Linux 交叉编译的语境下基本不起作用加了也不会报错但别指望它做什么。真正管用的是给编译器传-static-libstdc -static-libgcc把 C 标准库和 GCC 运行时静态进去减少板子上对libstdc.so.6版本的依赖。这一点在板子 rootfs 裁剪得比较狠的时候特别重要我遇到过板子上压根没有 libstdc 的情况程序一跑就提示找不到共享库。2.3 静态化对应用架构的影响选了静态 Qt你的应用侧写法要跟着调整主要在两处。第一是插件系统动态构建时平台插件linuxfb、eglfs、图片格式插件、输入插件都是运行时按需加载 .so静态构建时这些插件代码虽然被编进了库但如果不显式导入链接器不会把对应的目标文件拉进来程序启动就会报 no Qt platform plugin could be initialized。解决办法是用Q_IMPORT_PLUGIN宏或者在 pro 文件里写QTPLUGIN。第二是工程规模静态链接会把用到的所有 Qt 模块的整体拉进来链接阶段能看到明细。所以 pro 文件里QT 那一行要克制只加真正用到的模块。我见过有人习惯性写上QT widgets network sql xml multimedia静态编译出来一个简单的配置工具就有八九十兆strip 完还有四十多兆其实砍掉 sql 和 multimedia 能省掉一大半。3. 宿主机环境与依赖清单准备3.1 宿主机系统与基础包宿主机我用的是 Ubuntu 20.04 LTS x86_648 核 16G。这个配置编译整个 qt-everywhere-src-5.14.2跳过 webengine大约需要 40 到 70 分钟取决于跳过了多少模块。如果机器只有 4 核 8G时间要往两小时以上估而且必须把并行度压下来否则很容易在编译 qtdeclarative 的时候被 OOM Killer 干掉。基础依赖包这一块很多人照着零散的教程装装漏了几个也没什么提示直到 configure 阶段报一堆莫名其妙的错。我把宿主机该装的整理成一条命令Ubuntu 系直接可以跑sudo apt-get update sudo apt-get install -y \ build-essential perl python3 git \ bison flex gperf \ libxcb1-dev libx11-dev libxext-dev libxrender-dev \ libxkbcommon-dev libxkbcommon-x11-dev \ libfontconfig1-dev libfreetype6-dev \ libssl-dev libglib2.0-dev \ pkg-config rsync wget xz-utils这些包分两类一类是编译 Qt 自身需要的bison、flex、gperf、perl、python3另一类是让 configure 阶段的自检能通过的xcb 系列、fontconfig、freetype。即便你最终的目标平台是 linuxfb、完全用不到 X11宿主机上装这些 xcb 相关的包仍然有用因为 configure 脚本在做特性检测时会尝试编译一段小程序缺头文件它会直接判定特性不可用然后在某些参数组合下把编译中断。3.2 交叉工具链的选择与验证工具链的选择有几个常见来源芯片厂商 BSP 里带的、Linaro 发布的、ARM 官方发布的、发行版仓库里的gcc-aarch64-linux-gnu。我一般的建议是优先用芯片厂商 BSP 里的那一套因为它和目标板 rootfs 里的 libc 版本是对齐的能避掉大量 ABI 层面的麻烦。如果是通用开发板或者自己攒的 rootfs用 Linaro 或者发行版自带的都可以。拿到工具链之后第一件事是验证它能单独跑通一个 hello world别急着上 Qt。验证步骤如下export CROSS_COMPILE/opt/gcc-linaro-7.5.0/bin/aarch64-linux-gnu- export PATH$PATH:/opt/gcc-linaro-7.5.0/bin ${CROSS_COMPILE}gcc --version echo int main(){return 0;} t.c ${CROSS_COMPILE}gcc t.c -o t.elf file t.elffile的输出里应该能看到ELF 64-bit LSB executable, ARM aarch64字样。如果这一步就报错后面所有的 Qt 配置都是白搭。这一步过了之后再确认一件事工具链里有没有静态版本的 libstdc 和 libgcc。这决定了你能不能安全地加-static-libstdc。find /opt/gcc-linaro-7.5.0 -name libstdc.a -o -name libgcc.a -o -name libgcc_eh.a三个文件都能找到说明具备静态链接 C 运行时的条件。找不到 libstdc.a 的话-static-libstdc会直接链接失败这时候要么换工具链要么放弃静态运行库这条路。3.3 sysroot 的准备与坑点sysroot 是交叉编译里最容易出事的地方。它的作用是给编译器和链接器提供一个目标系统的根目录视图让它们能在里面找到目标平台的头文件和库。两种常见做法一是直接用工具链自带的 sysroot通常在aarch64-linux-gnu/libc这类路径下二是从目标板拷贝一份完整的根文件系统出来。我偏向第一种因为干净、可复现。工具链自带的 sysroot 里已经包含了 libc、libm、libpthread 的头文件和库Qt 需要的绝大部分东西都在里面。只有在需要链接板子上特有的第三方库比如厂商提供的硬件加速库时才考虑第二种做法而且建议用--sysroot指向主 sysroot再用-I和-L单独指向额外目录而不是把整个板子的 rootfs 拖进来当 sysroot。后者看起来省事实际上会把板子上过期的头文件一起带进来引发难以定位的类型冲突。从板子上拷贝 rootfs 的正确姿势是这样注意保留软链接、排除掉/proc、/sys、/dev这些虚拟目录再把/lib下的绝对路径软链接修成相对路径sudo rsync -avz --numeric-ids \ --exclude/proc/* --exclude/sys/* --exclude/dev/* \ --exclude/run/* --exclude/tmp/* \ rootboard-ip:/ \ /opt/sysroot-aarch64/拷完之后必做的一步是检查软链接。板子上的/lib/libc.so.6往往是指向/lib/aarch64-linux-gnu/libc.so.6的绝对链接拷到宿主机上这个路径就不存在了。用下面这条命令找出来并改成相对链接find /opt/sysroot-aarch64 -type l -lname /* -printf %p - %l\n4. 手写 mkspec让 qmake 真正认识你的工具链4.1 为什么不建议直接改现有的 mkspecQt 源码里qtbase/mkspecs/下面有一堆现成的平台描述文件其中linux-aarch64-gnu-g这个目录有的版本有、有的版本没有而且内容通常相当简略默认假设工具链前缀就是aarch64-linux-gnu-并且在 PATH 里找得到。实际项目里我们经常需要指定 sysroot、指定名字奇怪的工具链前缀、指定默认的 QPA 平台直接改现成的帧文件会污染源码树下次解压一份新源码又得重改一遍。所以我习惯的做法是在qtbase/mkspecs/下新建一个自己的目录比如linux-aarch64-static-g把内容写全。这样源码树是可复现的配置文件也能单独归档进版本库。cd qt-everywhere-src-5.14.2/qtbase/mkspecs mkdir -p linux-aarch64-static-g cd linux-aarch64-static-g4.2 qmake.conf 的完整内容与逐项说明这个文件是整个交叉编译的核心写错了后面全是错。我把它拆成几块讲。第一块是包含基础的公共配置让 qmake 知道这是一个类 Unix 平台、使用 GCC 编译器和 C 编译器MAKEFILE_GENERATOR UNIX CONFIG incremental QMAKE_INCREMENTAL_STYLE sublib include(../common/linux.conf) include(../common/gcc-base-unix.conf) include(../common/g-unix.conf)第二块是指定默认的平台插件。如果你的板子走 framebuffer就写linuxfb如果板子有 GPU 且想用 EGL 直出就写eglfs。这个值会影响 Qt 构建时哪些插件被编进来QT_QPA_DEFAULT_PLATFORM linuxfb第三块是交叉工具链的具体名称。注意这里的名字必须和你的实际工具链完全一致包括那个结尾的短横线QMAKE_CC aarch64-linux-gnu-gcc QMAKE_CXX aarch64-linux-gnu-g QMAKE_LINK aarch64-linux-gnu-g QMAKE_LINK_SHLIB aarch64-linux-gnu-g QMAKE_AR aarch64-linux-gnu-ar cqs QMAKE_OBJCOPY aarch64-linux-gnu-objcopy QMAKE_NM aarch64-linux-gnu-nm -P QMAKE_STRIP aarch64-linux-gnu-strip第四块是编译选项和 sysroot。这里我把 sysroot 直接写进 mkspec 而不是依赖--sysroot参数好处是后续编译应用时 qmake 生成的 Makefile 会自动带上这些选项应用侧不需要再手动配一遍SYSROOT /opt/gcc-linaro-7.5.0/aarch64-linux-gnu/libc QMAKE_CFLAGS --sysroot$$SYSROOT QMAKE_CXXFLAGS --sysroot$$SYSROOT QMAKE_LFLAGS --sysroot$$SYSROOT QMAKE_CFLAGS -pipe -O2 QMAKE_CXXFLAGS -pipe -O2 QMAKE_CFLAGS_RELEASE -O2 QMAKE_CXXFLAGS_RELEASE -O2 QMAKE_INCDIR $$SYSROOT/usr/include QMAKE_LIBDIR $$SYSROOT/usr/lib $$SYSROOT/lib load(qt_config)注意QMAKE_CFLAGS里千万不要顺手加-static。这个选项会作用于所有编译单元包括 configure 阶段跑的那些特性自检小程序一旦把 glibc 静态化自检程序可能直接跑不起来configure 会给你一堆莫名其妙的 test failed。4.3 一个容易忽略的细节C 标准Qt 5.14.2 要求 C11 及以上。工具链版本比较老的时候比如 GCC 5.x默认标准可能是 gnu98编译 Qt 时会报大量语法错误。稳妥的做法是在 mkspec 里显式指定QMAKE_CXXFLAGS -stdgnu11不过要注意Qt 自身的构建系统在部分模块里会覆盖这个选项所以更保险的位置是在 configure 命令里加-cstd c11让它统一生效而不是只写在 mkspec 里。这一点我是在一次编译 qtdeclarative 报了几百个auto相关的错误之后才总结出来的。5. configure 参数逐个拆解与编译实操5.1 我实际使用的一组完整参数参数这一块是最容易被抄来抄去抄错的。网上流行的版本往往针对特定板子直接拿来用会在别的板子上翻车。下面这一组是我在 linuxfb 场景下的通用版本你可以按需裁剪./configure \ -prefix /opt/qt5.14.2-aarch64-static \ -opensource -confirm-license \ -release \ -static \ -xplatform linux-aarch64-static-g \ -cstd c11 \ -no-pch \ -nomake examples -nomake tests -no-compile-examples \ -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre -qt-harfbuzz \ -no-icu -no-glib -no-cups \ -no-dbus -no-openssl -no-sql-* \ -no-xcb -no-opengl -no-eglfs -no-kms -no-linuxfb-fbdev \ -no-fontconfig \ -skip qtwebengine -skip qtlocation -skip qtgamepad \ -skip qtsensors -skip qtconnectivity -skip qtwayland \ -skip qtquickcontrols -skip qtquickcontrols2 \ -skip qtserialbus -skip qtserialport -skip qtwebsockets \ -skip qtvirtualkeyboard -skip qt3d -skip qtcharts \ -no-feature-accessibility \ -no-feature-printer \ -no-feature-concurrent上面这段参数里-no-sql-*和-no-linuxfb-fbdev这两处是示意写法实际执行时要去掉带星号的、展开成具体名称或者干脆不写、让 configure 报错时告诉你正确写法。configure 对未知参数很敏感写错了它会直接拒绝执行并提示相近的合法参数名这一点做得还算友好。5.2 关键参数背后的逻辑逐条解释几个容易搞混的-static让 Qt 库以静态库形式构建这是整个方案的核心开关。加上它之后make install出来的lib/目录里全是.a文件没有.so。-no-pch关掉预编译头。静态构建下预编译头有时会引入一些奇怪的问题而且在交叉编译环境里 PCH 的收益本身就不明显关掉能省掉一类偶发报错。-qt-*系列这一组zlib、libpng、libjpeg、freetype、pcre、harfbuzz的意思是使用 Qt 源码里自带的第三方库副本而不是去 sysroot 里找系统的。这么做的直接好处是减少了对目标板运行环境的依赖——因为静态链接之后这些库的代码也在你的可执行文件里。如果这里用系统库静态链接虽然也能链但一旦系统库又是动态的就等于白折腾了。-qt-freetype对中文界面尤其重要少了它字体会渲染成一堆方块。-no-icu关掉国际化组件能省掉几十兆的体积。代价是 Qt 的部分文本处理功能会走简化路径比如排序、断词在非拉丁语系下不那么精确。纯英文界面或者中文界面但不需要复杂排序的项目可以放心关掉。-no-xcb -no-opengl目标板走 framebuffer、没有 X 服务、没有 GPU 的情况下这两个都要关。-no-xcb关掉 X11 平台插件-no-opengl关掉 OpenGL 依赖。注意-no-opengl会连带影响 QtQuick 相关模块如果你的界面是 QML 写的需要重新评估——QtQuick 的软件渲染后端是存在的但要确认你用的模块在这个配置下还能编出来。-no-feature-*这一系列是细粒度的特性裁剪。-no-feature-accessibility关掉无障碍支持-no-feature-printer关掉打印-no-feature-concurrent关掉 QtConcurrent 模块。这些不是必须的但每关一个都能实打实地减少最终体积尤其是在 Flash 容量只有几十兆的板子上一寸空间一寸金。5.3 编译过程与并行度控制configure 跑完之后会打印一份配置摘要这个摘要别急着翻过去认真看两处一是 Build type 是不是 release二是 Static build 是不是 yes。这两处不对后面白干。编译阶段用make -j$(nproc) 21 | tee build.log这里我强烈建议把输出重定向到日志文件。Qt 的编译输出量非常大中途报错的时候如果只盯着终端前面几条关键错误可能已经滚过去了。有了日志grep -n error: build.log | head -20一秒钟定位问题。并行度这一块要注意。$(nproc)在 16 核机器上会给到-j16某些模块尤其是 qtdeclarative 里的 qml 编译阶段单个编译单元的峰值内存能到 2G 以上16 个并行很容易把 16G 内存打满。稳妥的做法是看机器的内存来定内存 GB 数除以 2和核数取较小值。16G 8 核就用-j88G 4 核就用-j3宁可慢一点也不要让编译中途被杀。编译完成之后make install ls /opt/qt5.14.2-aarch64-static/lib正常情况下你看到的应该是一堆.a、.prl文件加上pkgconfig/目录。.prl文件是 Qt 特有的记录了每个静态库的依赖关系链接的时候 qmake 会读它。如果这个目录里出现了.so文件说明-static没生效回去检查 configure 参数。6. 用静态 Qt 编译应用插件、体积与部署验证6.1 pro 文件里必须写的几行装好静态 Qt 之后在宿主机上另建一个工程目录用qmake生成 Makefile 的时候指定刚装好的这份/opt/qt5.14.2-aarch64-static/bin/qmake \ -spec linux-aarch64-static-g \ myapp.pro注意-spec这里用的是我们在源码树里建的那个 mkspec 名字qmake 会去qtbase/mkspecs的安装副本里找它。装完之后这个目录在/opt/qt5.14.2-aarch64-static/mkspecs/下所以提前把自定义的 mkspec 也一并复制过去或者在安装前确保它已经在qtbase/mkspecs里。pro 文件的内容关键在 plugins 这一段QT core gui widgets TARGET myapp TEMPLATE app CONFIG release static QTPLUGIN qlinuxfb qevdevmouse qevdevkeyboard qevdevtouch SOURCES main.cpp DEFINES QT_STATICPLUGINQTPLUGIN那一行是静态构建的命门。它告诉链接器把这些插件对应的目标文件也拉进可执行文件。少写了qlinuxfb程序启动就会直接失败报的还是那句让人头大的 This application failed to start because no Qt platform plugin could be initialized。qevdev*三个是输入插件板子上如果是触摸屏qevdevtouch必须有否则触摸没反应。如果你不想在 pro 里写也可以在 C 代码里手动导入效果等价#include QtPlugin #include QApplication Q_IMPORT_PLUGIN(QLinuxFbIntegrationPlugin) Q_IMPORT_PLUGIN(QEvdevMousePlugin) Q_IMPORT_PLUGIN(QEvdevKeyboardPlugin) Q_IMPORT_PLUGIN(QEvdevTouchScreenPlugin) int main(int argc, char *argv[]) { QApplication app(argc, argv); // ... return app.exec(); }提示插件类名的大小写和拼写必须精确。QLinuxFbIntegrationPlugin里的 Fb 是大写 F 小写 b写成QLinuxFBIntegrationPlugin会链接失败。这类错误很难从报错信息里一眼看出来我建议直接在qtbase/plugins/platforms/目录里搜Q_PLUGIN_METADATA附近的类声明确认。6.2 体积裁剪的几招静态链接出来的文件体积是绕不开的话题。一个只带 widgets 的空窗口程序如果不是 release 构建、没有 strip能到 100M 以上。几个实招先确认构建类型是 release。debug 构建在静态场景下几乎没有意义符号表和调试信息会占掉一半以上体积。这一点在 pro 里CONFIG release或者 qmake 时传CONFIGrelease都行。再是 strip。交叉工具链里的 strip 要指定目标架构用宿主机自带的 strip 会把文件搞坏aarch64-linux-gnu-strip myapp我个人习惯的编译链接一条龙是aarch64-linux-gnu-strip --strip-all myapp -o myapp.stripped ls -lh myapp myapp.stripped file myapp.stripped readelf -d myapp.stripped | head -30readelf -d的输出是关键验证步骤。一个静态 Qt 应用的动态段里NEEDED项应该只剩下 libc、libm、libpthread、libdl 这几项如果你看到了libQt5Widgets.so.5之类的条目说明静态化没生效。如果连NEEDED都没有那就是把 glibc 也静态了这种情况要么是好事真的零依赖要么是踩了 glibc 静态化的坑要看程序运行行为。还有一个技巧是在链接选项里加-Wl,--gc-sections配合编译时的-ffunction-sections -fdata-sections让链接器把没用到的函数段直接丢掉。这一招在静态链接场景下的收益比较明显我测过的一个中型工程能减掉 15% 左右的体积。缺点是如果代码里有靠链接器段定位实现的功能比如某些自定义的插件注册机制可能被误删需要自己权衡。6.3 字体与资源的内嵌处理静态构建下还有一类问题容易被忽略字体。宿主机上 Qt 会通过 fontconfig 找系统字体板子上没有 fontconfig我们前面用-no-fontconfig关了也没有系统字体目录程序跑起来中文全是方块。三种处理方式按推荐顺序第一种用QFontDatabase::addApplicationFont在程序启动时加载一个 ttf 文件。需要把 ttf 一起部署到板子上路径要写对int id QFontDatabase::addApplicationFont(/usr/share/fonts/wqy-microhei.ttc); if (id ! -1) { QStringList families QFontDatabase::applicationFontFamilies(id); if (!families.isEmpty()) { QApplication::setFont(QFont(families.at(0), 12)); } }第二种用 Qt 的资源系统把字体编进可执行文件。在 .qrc 里加入 ttf然后用:/路径加载。好处是真正实现了单文件部署代价是可执行文件变大——一个中文字体动辄十几兆这个代价不小。第三种在板子的 rootfs 里放一份字体文件然后用环境变量QT_QPA_FONTDIR指过去。这是最省的方案但依赖板子上的目录结构部署上不够干净。注意静态 Qt 构建下QFontDatabase::families()返回空列表是很常见的情况不要用它来判断字体系统是否正常。直接用 addApplicationFont 的返回值判断更可靠。6.4 在目标板上验证的完整流程验证环节我一般按这个顺序走每一步都能把问题范围缩小。第一步确认二进制本身架构正确file myapp应该输出ELF 64-bit LSB executable, ARM aarch64。如果输出里带dynamically linked后面跟着一堆 Qt 库那就是链接阶段出了问题。第二步把文件拷到板子上先不跑用readelf -d myapp | grep NEEDED看依赖。理想情况下只有 libc 一类的系统库。第三步带上环境变量启动。linuxfb 场景下export QT_QPA_PLATFORMlinuxfb export QT_QPA_FB_DRM0 export QT_LOGGING_RULESqt.qpa.*true ./myappQT_LOGGING_RULES那一行会打开 QPA 的调试输出插件加载失败、framebuffer 打开失败、输入设备没找到这些问题都能在日志里看到具体原因比干瞪眼强太多。第四步如果 framebuffer 能打开但界面不显示检查/dev/fb0的权限和板子上的 console 是否占用了这个设备。很多板子默认把内核 console 和 framebuffer 绑在一起需要在内核启动参数里处理一下或者在 Qt 侧换用别的输出方式。7. 踩坑实录与排查速查7.1 配置和编译阶段的典型报错报错一Project ERROR: Cannot run compiler aarch64-linux-gnu-g这个错误的字面意思容易误导人实际上大概率不是编译器不存在而是它跑不起来——往往是缺宿主机上的 32 位运行库或者工具链的路径没进 PATH。先手动执行aarch64-linux-gnu-g --version确认再检查工具链二进制是不是有可执行权限、有没有被解压工具破坏。报错二fatal error: bits/libc-header-start.h: No such file or directory这是 sysroot 配置错了的典型症状。编译器在默认位置找到了 gcc 的头文件但找不到 sysroot 里的 libc 头文件。检查 mkspec 里的SYSROOT变量是否指向了正确的路径以及那个路径下有没有usr/include/bits/目录。如果用的是工具链自带 sysroot路径通常形如toolchain/aarch64-linux-gnu/libc。报错三error: auto changes meaning in C11之类的语法错误C 标准没生效。前面提过要在 configure 里加-cstd c11光在 mkspec 里加不够。报错四cannot find -lstdc或cannot find -lgcc_s-static-libstdc或者-static-libgcc打开了但工具链里没有对应的静态库。用前面那条find命令确认没有的话就把这两个开关去掉或者换一套工具链。报错五编译到某个模块时进程被 Killed内存不够OOM Killer 出手了。降并行度或者单独编那个模块make -j1 -C qtbase/src/declarative7.2 运行阶段的问题定位现象一This application failed to start because no Qt platform plugin could be initialized静态构建下九成九是插件没导入。检查 pro 文件里的QTPLUGIN有没有写全或者代码里的Q_IMPORT_PLUGIN有没有写对类名。补上之后必须重新链接光重新编译不够。现象二程序启动了但没有输出屏幕全黑先确认QT_QPA_PLATFORM环境变量设对了。如果板子上 framebuffer 是/dev/fb1而不是默认的/dev/fb0需要指定QT_QPA_FB_DRM或者对应的环境变量。打开 QPA 日志是最快的方式。现象三中文显示成方块上面字体那一节讲过加字体加载逻辑。快速验证的办法是把宿主机上的字体拷到板子上用QT_QPA_FONTDIR指过去看是否正常如果能显示就说明后面要做的是把字体内嵌进程序。现象四触摸有反应但坐标偏了触摸屏的校准问题和 Qt 没关系是 evdev 报的坐标范围和屏幕分辨率不匹配。可以在/etc/pointercal或者 Qt 的QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS里处理也可以在内核设备树层面修正。7.3 排查速查表阶段症状关键词大概率原因处理方向配置Cannot run compiler工具链路径或权限手动执行验证检查 PATH配置libc-header-start.hsysroot 错误检查 SYSROOT 变量和目录结构配置auto changes meaningC 标准未生效configure 加 -cstd c11编译Killed内存不足降低 -j 并行度链接cannot find -lstdc缺静态运行库去掉开关或换工具链链接undefined reference to dlopen缺系统库补 -ldl -lpthread运行no Qt platform plugin插件未导入补 QTPLUGIN 或 Q_IMPORT_PLUGIN运行黑屏无输出QPA 平台或 fb 设备设 QT_QPA_PLATFORM开 QPA 日志运行中文方块字体缺失addApplicationFont 或内嵌字体运行找不到共享库libstdc 未静态加 -static-libstdc8. 关于这套流程我自己踩出来的几点体会静态交叉编译这件事最大的敌人不是技术难度而是信息不完整。网上能搜到的配置命令大多缺上下文不知道对方用的是什么工具链、什么板子、什么 Qt 版本抄过来报错了也不知道往哪查。我现在做这类事情的习惯是先花半天时间把工具链和 sysroot 这两样单独验证透写一个 hello world 能跑通为止再上 Qt。这半天省下来的时间是后面几天排查时间的十倍。另一个体会是关于 configure 参数。不要一次加满所有裁剪选项。第一次跑通的时候用最小参数集把-static、-xplatform、-prefix、-release这几个核心的写上就够了其他裁剪项等第一遍跑通、程序能在板子上跑起来之后再一条一条加、加一条验证一次。一次加十几条报错了你根本不知道是哪条的锅。还有一点是版本管理。自定义的 mkspec、configure 命令行、sysroot 的来源和版本、工具链的版本这四样东西一定要在一个地方记下来最好写进项目仓库的docs/build.md。半年后你要复现这个构建或者要给新同事交接没有这份记录就得从头再来一遍。我吃过这个亏第二次构建的时候工具链换了小版本静态库的符号差异导致链接报错排查了一整天才定位到版本变化上。