做过嵌入式Qt交付的人应该都体会过这种尴尬应用在x86宿主机上跑得欢一到ARM64目标板上就面临两难——要么在目标板上现装一大堆运行时依赖要么把整套Qt环境连库带插件拷过去然后被磁盘空间、依赖版本冲突整到怀疑人生。我这次是在一块RK3399平台的板子上部署Qt程序磁盘只有4GB可用还要求程序能随固件一起烧录、不依赖板卡上额外的库文件于是决定走Qt5.14.2的aarch64静态交叉编译路线把这套从零搭建的完整流程记录下来。既然是从零搭建我不会默认你已经有交叉编译经验但也不会啰嗦到从Linux命令讲起。整个流程大致分为概念澄清、环境准备、configure调参、mkspec定制、静态链接排坑、目标板验证、工程配置扩展这几个阶段。每个阶段都有我当时踩过的坑和最终确定的做法你可以直接照着抄也可以在关键节点根据自己的板卡特性调整。1. 静态Qt和完全静态可执行文件之间还差一个libc先说一个最容易被误解的概念。很多人听到-static就以为最终产物应该是一个不依赖任何库的单文件跑到任何Linux上都能运行。真实情况远没有这么理想至少有三个层面的静态需要分清。第一层是Qt库本身静态编译。Qt的模块以.a静态库形式产出链接进你的可执行文件。这是标题里Qt静态编译的核心含义。第二层是libgcc和libstdc的静态链接。GCC的这两个运行库可以静态链入避免目标板GCC版本不匹配的问题。第三层是glibc的完全静态也就是最终二进制不依赖任何.so连libc、libm、libpthread都打包进去。这一层理论上能做但实际中我强烈建议不要做。为什么glibc官方自己都不推荐完全静态链接核心问题在于NSSName Service Switch机制。像getaddrinfo这种DNS解析函数在静态glibc下会变得很不可靠你的程序一旦涉及网络域名解析就可能出现偶发性的解析失败而且这种失败在不同busybox版本、不同嵌入式系统的表现还不一样排查起来非常痛苦。所以常规的嵌入式Qt落地方案是Qt库静态编译libgcc和libstdc静态链入glibc保持动态依赖。最终产物对libc.so.6有依赖但目标板只要有一个正常的glibc基础系统就能跑。如果你连glibc版本都不想对齐还有一种路线是改用musl libc做交叉编译。musl的历史包袱小静态链接生态相对干净。但Qt 5.14.2对musl的支持不算成熟尤其是Qt Quick、QPA插件这些组件在musl环境下经常要打补丁或改mkspec投入产出比不高。我这次项目的板卡跑的是标准Ubuntu系统glibc版本和我交叉编译环境完全一致所以直接采用Qt静态libc动态的混合方案这也是目前嵌入式Qt交付最常见、最稳的选择。明白了这个概念后面所有操作就都有的放矢了。我们的目标产物是一个依赖极少、但并非完全静态的ARM64可执行文件依赖列表基本只剩libc.so.6、libm.so.6、libdl.so.2、libpthread.so.0、librt.so.1这一级别的系统库。这类库在任何标准aarch64 Linux系统上都是必然存在的。2. 宿主机、toolchain、sysroot三方对齐多数交叉编译失败都死在这一步交叉编译的环境准备不是装一个交叉编译器那么简单。最关键的思维转变是你编译时看到的头文件和库文件必须来自目标板的rootfs而不是来自x86宿主机。这套目标板根文件系统就叫sysroot。2.1 宿主机选型与交叉编译器安装宿主机我建议直接用Ubuntu 20.04或22.04理论上Ubuntu 18.04也能用但工具链版本偏老处理某些C17特性时会遇到奇怪问题。我最终用的是Ubuntu 20.04配的是系统自带的gcc 9交叉工具链和Qt 5.14.2时代的编译器生态比较匹配。安装交叉编译器很简单一条命令的事sudo apt update sudo apt install -y gcc-aarch64-linux-gnu g-aarch64-linux-gnu安装完成后工具链前缀是aarch64-linux-gnu-实际编译器就是aarch64-linux-gnu-gcc和aarch64-linux-gnu-g。装完先验证一下aarch64-linux-gnu-gcc -v注意看输出里的Target: aarch64-linux-gnu以及gcc version后面的版本号。这个版本号非常关键因为目标板上如果跑的是旧版glibc新版GCC编译出的二进制可能默认使用目标板glibc不支持的符号版本运行时直接给你一个GLIBCXX_3.4.25 not found。2.2 sysroot的两种获取方式编译器装好之后自带了一个默认sysroot通常在/usr/aarch64-linux-gnu。但这个默认sysroot只包含最基本的libc、libstdc头文件和库远远不足以编译带GUI的Qt应用。你需要一个更完整的目标板根文件系统。获取sysroot有两条路我两条都走过。第一条是从真实板卡上提取。这个方法最贴切因为你和目标系统完全一致。前提是目标板能临时跑起来并且能通过SSH或者串口访问。然后用rsync把板卡上的/lib、/usr/lib、/usr/include同步到宿主机一个目录下mkdir -p ~/aarch64-sysroot rsync -avzP rootboard-ip:/lib ~/aarch64-sysroot/ rsync -avzP rootboard-ip:/usr/include ~/aarch64-sysroot/usr/ rsync -avzP rootboard-ip:/usr/lib ~/aarch64-sysroot/usr/注意目标板和宿主机之间如果系统架构不同rsync同步时要保持目录结构不要在中间做过多的--exclude过滤。我当时因为想精简体积排除了很多dev和debug符号结果后面编译Qt的某些模块时因为找不到libc.so解引用符号而失败。sysroot不是越小越好稳定性优先。第二条是用debootstrap在宿主机上构建一个纯aarch64的rootfs。这个方法适合目标板系统还没完全定型、或者板卡不方便SSH访问的情况。做法上需要用到qemu-user-static让x86宿主机可以chroot进aarch64环境sudo apt install -y debootstrap qemu-user-static sudo debootstrap --archarm64 --foreign focal ~/aarch64-rootfs sudo cp /usr/bin/qemu-aarch64-static ~/aarch64-rootfs/usr/bin/ sudo chroot ~/aarch64-rootfs /debootstrap/debootstrap --second-stagefocal是Ubuntu 20.04的代号也可以用jammy对应22.04。这个rootfs构建完成后它的/lib、/usr/lib、/usr/include就是你编译Qt要用的sysroot。2.3 sysroot与编译器的对齐问题有了sysroot下一步是确保交叉编译器使用的头文件、库和你指定的sysroot是一致的。默认情况下aarch64-linux-gnu-gcc会使用/usr/aarch64-linux-gnu作为sysroot如果你用自己的rootfs需要在编译器的--sysroot参数里显式指定。后面的Qt configure和mkspec配置里都会用到这个参数。检查sysroot是否正常的一个技巧是直接问编译器它的默认路径aarch64-linux-gnu-gcc -print-sysroot aarch64-linux-gnu-gcc -print-file-namelibc.so如果你打算完全用自定义sysroot那么-print-sysroot返回的路径最好别用直接在所有编译参数里用--sysroot/path/to/your/sysroot统一覆盖。Qt的configure命令支持-sysroot参数mkspec里也必须在QMAKE_CFLAGS里加上--sysroot这个我们后面细说。这里强烈的建议是整个编译期间宿主机上不要混装多版本交叉编译器也不要让Qt builder去自动探测x86的pkg-config。凡是牵扯到目标板库的探测全部强制走sysroot。Linux桌面开发习惯里的pkg-config --cflags这类命令在交叉编译里经常是毒药因为它拿到的路径还是宿主机的这是后面所有找不到头文件链接到x86库问题的根源。3. configure这一步决定成败参数不是越多越好是越准越好Qt从源码构建的第一道大门就是configure。很多人习惯从网上抄一大段configure参数也不管自己项目到底用不用那些功能结果要么在之后某个步骤遇到诡异的编译失败要么编译了一个体积巨大且用不到的Qt。我建议把configure参数按基础和路径功能裁剪第三方依赖目标平台特性四组来理解动态调整。3.1 源码的获取与校验Qt 5.14.2的完整源码包叫qt-everywhere-src-5.14.2.tar.xz官方下载地址是download.qt.io。如果从国内访问官方源比较慢用清华大学或中科大的Qt镜像站点下载都可以文件名和校验值一致。下载后建议核对一下MD5或SHA1校验值源码损坏导致的编译报错非常隐蔽会让你误以为是配置问题。wget https://mirrors.tuna.tsinghua.edu.cn/qt/archive/qt/5.14/5.14.2/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源码包很大完整解压后有好几个GB包含qtbase、qtdeclarative、qtquickcontrols2、qtmultimedia、qtwebengine等所有模块。编译时不需要全部构建后续可以用-skip参数跳过不需要的模块。3.2 configure参数拆解表下面这张表是我这次最终使用的参数按用途分组参数作用我的建议-staticQt库以静态库编译本项目的核心目的-release只编译release版本交叉编译时尤其省时间-opensource -confirm-license接受开源协议必须否则configure卡住-prefix /opt/Qt5.14.2/aarch64-static安装路径后续编译依赖它找Qt路径统一避免空格-xplatform linux-aarch64-gnu-g指定交叉平台mkspecQt自带aarch64 spec先用它不够再改-sysroot /home/user/aarch64-sysroot指定目标板rootfs核心路径必须准确-no-xcb不编译xcb平台插件嵌入式板绝大多数没有X11-linuxfb启用linuxfb作为QPA后端没有GPU时的最稳方案-eglfs启用eglfs QPA后端有GPU/DRM时的推荐方案-no-opengl不编译桌面OpenGL除非你确定要OpenGL渲染-qt-zlib -qt-libpng -qt-libjpeg使用Qt内置的压缩与图片库减少sysroot里的第三方依赖-no-icu不编译ICUICU交叉编译复杂且大多数控件用不上-no-glib不依赖glib嵌入式常见做法-openssl-linked或-no-openssl链接OpenSSL或禁用取决于是否用HTTPS见下文-nomake examples -nomake tests -nomake tools不编译示例和测试大量节省时间-skip qtwebengine -skip qt3d -skip qtcanvas3d ...跳过难编译或不需要的模块按需跳过3.3 一份可以直接抄的configure命令以我之前那套环境为例完整命令是这样cd qt-everywhere-src-5.14.2 ./configure \ -static \ -release \ -opensource \ -confirm-license \ -prefix /opt/Qt5.14.2/aarch64-static \ -xplatform linux-aarch64-gnu-g \ -sysroot /home/user/aarch64-sysroot \ -no-xcb \ -linuxfb \ -eglfs \ -no-opengl \ -qt-zlib \ -qt-libpng \ -qt-libjpeg \ -no-icu \ -no-glib \ -no-openssl \ -nomake examples \ -nomake tests \ -nomake tools \ -skip qtwebengine \ -skip qtwebview \ -skip qt3d \ -skip qtcharts \ -skip qtdatavis3d \ -skip qtdoc \ -skip qtgamepad \ -skip qtlocation \ -skip qtpurchasing \ -skip qtscript \ -skip qtserialbus \ -skip qtspeech \ -skip qtvirtualkeyboard \ -skip qtwayland \ -skip qtwebglplugin \ -skip qtwinextras \ -skip qtwebsockets关于-no-openssl可能会有人质疑Qt网络模块不开SSL访问HTTPS接口不是废了吗这个要根据项目实际来。如果你的目标板只是跑内网服务、走HTTP协议-no-openssl能省掉OpenSSL交叉编译这一大堆事。如果确实需要HTTPS那么就先把OpenSSL源码交叉编译成aarch64静态库./Configure linux-aarch64 -static然后configure时把-no-openssl换成-openssl-linked再通过QMAKE_INCDIR和QMAKE_LIBDIR或者mkspec里的头文件库路径指过去。这里我建议先用-no-openssl把整套流程跑通再回头加SSL分步推进的排查成本要低得多。3.4 configure的日志一定要看configure执行完毕后不要急着直接make。强烈建议花两分钟看一眼输出的日志重点是识别WARNING和Note。Qt的configure在交叉编译时经常出现某个模块因为探测失败而被自动跳过的情况比如Qt Multimedia可能因为无法检测到ALSA而自动禁用。你当时没发现后面写代码用到QMediaPlayer才发现模块整个不存在再回去改配置重新编译一次全量编译的耗时都要好几个小时非常亏。另外一个隐藏点-qt-zlib这类参数在静态编译下尤其有用。因为zlib很可能和sysroot里其他库有版本耦合如果用系统的-lz到时链接进Qt的是动态库如果是Qt内置的zlib则会被打进.a里。你这时的选择直接决定目标板要不要额外带libz.so。嵌入式资源紧张时凡是Qt能自带的第三方库一律让它自带。4. mkspec与构建队列qtbase先行其他模块按需跟上configure通过之后开始正式编译。这一阶段有两个关键点一个是mkspec是否真的描述了正确的交叉编译环境另一个是构建顺序不能乱。4.1 Qt自带的aarch64 mkspec与自建spec的选择Qt 5.14.2的qtbase/mkspecs目录下有一个linux-aarch64-gnu-g子目录它继承自linux-g默认调用的编译器前缀是aarch64-linux-gnu-。理论上直接指定-xplatform linux-aarch64-gnu-g就够了。但实际上如果你使用了自定义sysroot就很可能需要在这个mkspec里显式加上sysroot标志因为Qt的qmake默认配置不一定把你的sysroot传给每一行编译命令。最稳妥的做法是复制一份mkspec并自己命名比如叫linux-aarch64-myspeccp -r qtbase/mkspecs/linux-aarch64-gnu-g qtbase/mkspecs/linux-aarch64-myspec然后编辑qtbase/mkspecs/linux-aarch64-myspec/qmake.conf核心内容修改成类似这样MAKEFILE_GENERATOR UNIX CONFIG incremental QMAKE_INCREMENTAL_STYLE sublib include(../common/linux.conf) include(../common/gcc-base-unix.conf) include(../common/g-unix.conf) 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_CFLAGS --sysroot/home/user/aarch64-sysroot QMAKE_CXXFLAGS --sysroot/home/user/aarch64-sysroot QMAKE_LFLAGS --sysroot/home/user/aarch64-sysroot QMAKE_AR aarch64-linux-gnu-ar cqs QMAKE_STRIP aarch64-linux-gnu-strip注意这里的--sysroot路径必须和configure时用的-sysroot保持一致。如果是用debootstrap生成的rootfs路径也要指向rootfs目录。QMAKE_LFLAGS不加sysroot的典型后果是编译能过但最后链接阶段找不到libm.so.6或者crt1.o报错信息非常迷惑。如果你不想修改自带的spec也可以在configure时传-device-option来自定义比如-device-option CROSS_COMPILEaarch64-linux-gnu-。但在定制较多的项目中我建议直接用自建spec因为后面加第三方静态库链接参数会更灵活。4.2 构建顺序与并行度控制Qt5的全量构建是分模块的核心是qtbase其他模块像qtdeclarative、qtmultimedia都依赖qtbase先安装好。正确的顺序是make -j4 make install先把qtbase安装到/opt/Qt5.14.2/aarch64-static然后用这个已经安装好的qmake去编译其他模块。全量一次构建全部模块的耗时以小时计所以省时间的核心策略是先只构建qtbase然后对照你实际使用的Qt模块清单一个个补。编译并行度也是内存杀手。make -j$(nproc)在16核的机器上会很激进gcc处理Qt这种巨型C项目时每个编译进程都可能吃几百MB内存用满核比较危险。我一般保守用-j4或-j8。如果编译时出现internal compiler error: Killed大概率是内存不足降低并行度即可。qtbase安装完成后用以下方式验证一下qmake是否正常/opt/Qt5.14.2/aarch64-static/bin/qmake -query看输出里的QT_INSTALL_PREFIX、QT_INSTALL_LIBS等路径是否正确同时确认qmake版本是5.14.2。路径全部正常后再继续编译其他模块比如cd qtdeclarative /opt/Qt5.14.2/aarch64-static/bin/qmake make -j4 make installqtsvg、qtimageformats、qtmultimedia、qtquickcontrols2这几个模块按同样的套路处理。建议把要编译的模块列成一个清单逐个执行不要一次性全自动构建因为某个模块报错时能快速定位。5. 静态链接触雷区平台插件、.a顺序和悄悄消失的依赖你想让最终的程序用静态Qt库跑起来编译过程只是第一关链接阶段才是重灾区。下面这几个问题我敢说做Qt静态交叉编译的人十个有八个会遇到。5.1 QPA平台插件的静态导入Qt的架构里图形界面不是硬编码进QtGui的而是通过QPAQt Platform Abstraction插件机制来支持不同的显示后端。在动态编译时插件是独立的.so运行时按需从platforms目录加载。但在静态编译下插件库被打包成.a并且不会自动链接进你的程序。这就是为什么很多人的静态Qt程序一运行就报qt.qpa.plugin: Could not find the Qt platform plugin eglfs in 解决方案是在你的工程文件里显式声明需要导入的平台插件。qmake工程里可以用QTPLUGINQTPLUGIN qeglfs qlinuxfb同时为了在代码层面强制导入需要在main函数之前加上插件声明#include QtPlugin Q_IMPORT_PLUGIN(qlinuxfb) Q_IMPORT_PLUGIN(qeglfs)如果你只用linuxfb那声明qlinuxfb就够。用了eglfs还涉及libEGL和libgbm的依赖链接失败时再对症下药。5.2 静态库的链接顺序问题这是一个非常经典且折磨人的问题。动态库链接时代不需要关心库的前后顺序但静态库不一样。链接器扫描libA.a时如果发现里面有未解析的符号它会再扫描后续的libB.a去找如果libB.a恰好出现在libA.a之前就找不到直接报undefined reference。Qt静态库数量多模块间依赖错综复杂所以链接时通常需要把一堆.a打包成一个大组让链接器反复扫描。在Makefile或工程的链接参数里可以这样处理-lQt5Gui -lQt5Core -lQt5Widgets如果还报缺符号检查链接参数里有没有把-ldl -lpthread -lm放在最后。Qt底层很多反射和线程机制依赖这几个系统库顺序一旦不对会报undefined reference to dlopen或undefined reference to pthread_create。更复杂的场景比如你同时链接了OpenSSL静态库就可能会遇到zlib、dl、pthread之间的循环依赖这时需要在链接参数里包一层-Wl,--start-group -lQt5Network -lssl -lcrypto -Wl,--end-group这个--start-group会强制链接器在这几个静态库之间循环查找符号直到不再有新符号被解析。代价是链接时间变长但对于静态交叉编译来说稳定优先。5.3 ICU和OpenSSL的隐藏影响开configure时如果直接用了-no-icuQt某些文本处理能力会降级影响最大的是QTextBoundaryFinder的断词逻辑以及某些语言的排序、大小写转换规则。如果你的产品界面以中文为主基本无感但如果涉及多语言分词和搜索排序就要评估好再砍掉。OpenSSL如果后期通过-openssl-linked静态编进来除了编译链接要折腾运行期还有一个隐藏坑静态链接的OpenSSL不会再从/etc/ssl/certs自动加载系统CA证书你需要显式设置证书路径QSslConfiguration::setDefaultCaCertificates(QSslConfiguration::systemCaCertificates());或者运行时设置环境变量SSL_CERT_FILE指向你的证书文件。这个问题在板子上测试HTTPS接口时会突然冒出来别问我怎么知道的。5.4 第三方库的头文件污染交叉编译时pkg-config探测到的默认路径是宿主机的/usr/lib/x86_64-linux-gnu/pkgconfig一旦某个模块的configure脚本错误地调用了系统的gcc或者pkg-config它就会看到x86的头文件然后在编译时出现一堆unknown type name或file not found的报错。解决办法是设置环境的PKG_CONFIG_LIBDIR让它只搜索sysroot下的pkgconfig目录export PKG_CONFIG_LIBDIR/home/user/aarch64-sysroot/usr/lib/aarch64-linux-gnu/pkgconfig同时确认PATH里的aarch64-linux-gnu-gcc是唯一被使用的gcc。这一条能帮你挡掉一大半莫名的编译错误。6. 目标板实测从readelf检查到第一个GUI窗口的排查清单交叉编译完成不等于事情结束把程序拷到目标板上能不能跑才是真正的考验。我建议按下面这个顺序做验证每一步都能快速定位问题。6.1 先静态检查产物在宿主机上先对可执行文件做一轮体检file build/bin/myapp输出应该是ELF 64-bit LSB executable, ARM aarch64。如果你的输出是x86-64说明你编译时没有用对编译器或者是链接时用了宿主机的某个工具直接回炉。然后查动态库依赖aarch64-linux-gnu-readelf -d build/bin/myapp | grep NEEDED正常情况下列出的只会有libc.so.6、libm.so.6、libpthread.so.0、libdl.so.2、librt.so.1这些基础系统库。如果出现了libQt5Core.so.5说明你链接的是动态Qt库而不是静态库回顾一下qmake的CONFIG和-static配置。如果有libstdc.so.6说明libstdc也没有被静态链入如果你的目标板环境和编译环境libstdc版本不匹配运行时会报GLIBCXX_3.4.x not found。6.2 常见运行期失败信号与处理拷到目标板后常见的运行期失败信号和应对方法我整理了一张表失败现象大概率原因处理办法GLIBCXX_3.4.29 not foundlibstdc版本不一致编译时加-static-libstdc -static-libgcccannot open shared object file: libQt5Core.so.5链接了动态Qt确认整个链路的-static生效qt.qpa.plugin: Could not find the Qt platform plugin eglfsQPA插件未静态导入在代码里加Q_IMPORT_PLUGINpro里加QTPLUGINThis application failed to start because no Qt platform plugin could be initialized没有可用平台插件或显示设备不可用先用-platform minimal或-platform linuxfb验证No such file or directory但文件明明存在通常是动态库解释器路径问题说明有动态依赖用readelf检查确认依赖列表运行时Segmentation Fault可能是字体、GPU驱动或sysroot不匹配开了QT_DEBUG_PLUGINS1看日志再定位第二行的问题尤其隐蔽。你以为是静态编译成功了实际上如果某些第三方库是动态链接的或者qmake的lib路径配置里残留了动态Qt库路径最终产物会在运行时去找libQt5Core.so.5。检查NEEDED时最直观。6.3 一个最小的验证程序我建议在目标板上先用一个最简单的Qt Widgets程序验证环境不要上来就跑复杂的QML应用。一个包含一个QLabel的程序代码不到二十行编译成静态产物后拷贝到板子上export QT_QPA_PLATFORMlinuxfb ./helloworld -platform linuxfb如果屏幕上出现一个窗口说明Qt静态库本身没问题。如果黑屏或者报错再看QT_QPA_PLATFORMminimal ./helloworld是否正常输出到标准输出。minimal平台插件不做任何显示能启动就说明Qt核心初始化链路是通的问题缩小到了显示后端。字体问题也在这个阶段会暴露。Linux下Qt默认会在/usr/lib/fonts、/usr/share/fonts等目录找字体。很多精简系统没有中文字体界面出来的就是方块。这时候要么把字体文件放进程序目录要么设置环境变量export QT_QPA_FONTDIR/opt/myapp/fonts在代码里也可以设置字体路径但环境变量是最快验证手段。别忘了静态程序不会自动帮你打包任何资源文件字号字体、QML文件、图片都要在设计部署方案时单独考虑。6.4 几个实用的调试环境变量静态链接之后程序像一个黑盒好在Qt提供了几个环境变量可以打开运行时日志排查时无比好用export QT_DEBUG_PLUGINS1 export QML_IMPORT_TRACE1 export QT_LOGGING_RULESqt.qpa.*trueQT_DEBUG_PLUGINS会打印Qt在启动阶段尝试加载了哪些插件、为什么失败是QPA问题的第一手线索。QML_IMPORT_TRACE会打印QML模块的导入搜索路径快速定位module not found的问题。QT_LOGGING_RULES可以针对某类日志单独开启debug输出比全局日志干净得多。7. 工程配置与sysroot复用让一套交叉环境服务多个项目走到这一步单个程序的交叉编译链路已经通了。但真实项目不会是孤零零一个可执行文件你还要把这套环境整理成可持续使用的基础设施。7.1 qmake工程文件的静态配置qtbase安装好之后你的qmake已经能正常工作。在新的工程里pro文件至少要有以下几项CONFIG static QT core gui widgets # 如果需要静态插件 QTPLUGIN qlinuxfb # 静态链接libstdc和libgcc QMAKE_LFLAGS -static-libgcc -static-libstdcCONFIG static会告诉qmake优先链接.a版本的Qt库。同时建议在pro里显式声明TEMPLATE app避免qmake在库项目和应用项目之间产生歧义。7.2 CMake工程的注意事项如果你的项目用CMake思路一样但有三个点需要额外注意。第一需要给CMake指定Qt的交叉编译路径cmake \ -DCMAKE_TOOLCHAIN_FILEtoolchain-aarch64.cmake \ -DCMAKE_PREFIX_PATH/opt/Qt5.14.2/aarch64-static \ ..第二toolchain-aarch64.cmake文件里要声明编译器、sysroot、交叉编译的pkg-config路径否则find_package时会去宿主机目录搜Qt。第三静态链接的Qt依赖链有时需要手动补find_package(Qt5 REQUIRED COMPONENTS Core Gui Widgets) find_package(OpenGL REQUIRED) target_link_libraries(myapp PRIVATE Qt5::Core Qt5::Gui Qt5::Widgets ${CMAKE_DL_LIBS} pthread )QtGui在有些构建配置下会隐式依赖OpenGL即使你用linuxfb也可能在最后链接时因为缺少-lGL或-lEGL而失败。这个取决于你的configure参数遇上了就在target_link_libraries里显式补上。7.3 同一套sysroot的复用价值最后说一个很容易被忽视的点。你为Qt准备的那套aarch64 sysroot不只是Qt专用。凡是需要在ARM64目标板上运行的第三方库比如openssl、libcurl、甚至nginx都可以在这套sysroot下交叉编译。我这次项目的板子上除了Qt程序还放了一个轻量级的HTTP服务就是用同一套aarch64-linux-gnu-gcc和sysroot编译的静态可执行文件最终连同Qt GUI程序一起打包进固件。这提醒你在构建sysroot时不要只想着Qt尽量保持rootfs的完整性。我从板卡上同步sysroot时保留了完整的usr/include和usr/lib虽然占用了几百MB宿主机的磁盘但它让后续所有其他组件的交叉编译都免去了重新构建rootfs的功夫。git里保存一份sysroot的构建脚本或rsync命令新同事加入时一键同步环境比自己手动复现整套流程靠谱得多。另外我实测下来发现一个有用的习惯把configure时的完整命令、mkspec的修改、以及每次模块的编译顺序都写成一个shell脚本放在项目仓库里。这样即使过几个月你换了机器、忘了参数也能顺着脚本快速恢复出一模一样的交叉编译环境。Qt静态交叉编译的全链路踩坑大多是不可见的能沉淀下来的只有一份清晰的、可复现的构建记录。