Linux Qt 5.9.9 静态编译实战：从环境核对到无依赖交付

简介：面向 Linux 平台 Qt 桌面开发者的静态编译库包，针对需要发布免依赖图形界面程序的场景，解决动态链接时目标机器缺少 Qt 运行库、ldd 检查仍带 Qt 依赖的痛点。包内共约 2000 个文件，以 3746 个 .h 头文件、287 个 .qm 翻译文件、183 个 .pri 与 181 个 .cmake 构建脚本、172 个 .prl 与 172 个 .a 静态库为主，另含 .conf、.prf、.pc、.qmltypes 等配置与元数据文件，压缩包约 197.4MB，覆盖 QtCore、QtGui、QtWidgets 及 qt-xcb 平台插件等模块。该库在 CentOS 7.6 x64、GCC 4.8.5、glibc 2.17 环境下编译，链接后程序经 ldd 查看不再依赖 Qt 动态库，便于单文件分发。已有 569 人学习下载，适合需要跨机器部署 Qt 界面程序的中高级开发者参考使用。

1. 拿到 qt-5.9.9-gcc485-libc217-static-qt-xcb.tar.gz 先别急着解压：这套静态包挑环境

上周帮一个做工业上位机的朋友救场，他那边编译机是 CentOS 7，gcc 4.8.5，glibc 2.17，跑的是老掉牙的 Qt 5.9.9。项目要交付到一台没有图形库、没有 X11 开发包、连 Qt 运行库都不让装的现场机器上，只能走 Linux Qt 静态编译这条路。他随手下了个动态版 Qt 包，编出来的程序一拷过去就报libQt5Core.so.5: cannot open shared object file，折腾两天没结果。问题不在代码，在包选错了——静态编译的 Qt 和动态版是两套东西，-qt-xcb这个后缀更是决定了 XCB 平台插件是编进二进制还是运行时去加载。这篇就把 qt-5.9.9-gcc485-libc217-static-qt-xcb.tar.gz 这套包从环境核对、解压落位、qmake 配置到编出第一个静态可执行文件的全过程记一遍，适合正在给老系统做静态交付、又不想在现场装一堆依赖的开发者照着走。

2. 环境核对与包结构：gcc485、libc217、qt-xcb 三个标签各管什么

这套包的名字本身就是一份环境清单，拆开看是四段信息：Qt 版本 5.9.9、编译器 ABI 对应 gcc 4.8.5、C 运行库对应 glibc 2.17、平台插件走 qt-xcb 静态内置。任何一段对不上，后面 qmake 能跑、make 能过，但链接阶段或者运行阶段一定翻车。所以第一步不是解压，是拿目标机器和编译机器的底账去对这三个标签。

2.1 先查编译机的 gcc 与 glibc 版本

静态库对 ABI 极其敏感，gcc 大版本不同，C++ 的 name mangling 和标准库符号就可能对不上。我一般先跑两条命令把底账记下来：

# 查 gcc 版本，确认主版本是 4.8.x gcc --version | head -n 1 # 查 glibc 版本，确认是 2.17 ldd --version | head -n 1 # 顺带确认系统架构，静态包一般是 x86_64 uname -m

gcc --version输出里如果看到 4.8.5，和包名的 gcc485 就对上了；如果是 4.9、5.x、7.x，理论上 ABI 兼容性有差异，实际项目里我见过 gcc 5 链接 gcc 4.8 编的静态库时std::string相关符号报 undefined reference 的情况，所以别赌，版本不一致就换编译机或者换包。ldd --version第一行末尾的 2.17 对应 libc217，这个数字决定了下限——目标机器的 glibc 不能低于 2.17，低于这个版本静态程序里的某些系统调用封装会直接崩。uname -m出 x86_64 才继续，32 位机器这套包用不了。

提示：glibc 是静态程序唯一没法完全静态链接的部分（NSS、dlopen 等场景仍会碰动态库），所以 libc217 这个标签是硬约束，不是参考值。

2.2 解压前先看 tar 包里的目录布局

确认环境对得上，再解压。我习惯先tar -tzf列一下顶层结构，避免解出来一堆文件散在当前目录：

# 只看前 20 行，确认顶层目录名 tar -tzf qt-5.9.9-gcc485-libc217-static-qt-xcb.tar.gz | head -n 20 # 确认包内是否自带 qmake 和平台插件目录 tar -tzf qt-5.9.9-gcc485-libc217-static-qt-xcb.tar.gz | grep -E 'bin/qmake|plugins/platforms'

正常这套包解出来是一个以 Qt 版本命名的顶层目录，里面bin/qmake是配置入口，plugins/platforms/下应该有libqxcb.a这类静态插件文件。如果grep只出 qmake 不出 platforms 下的.a，说明这个包不是完整的静态构建，-qt-xcb可能只是编译选项残留，得回头找发布方确认。这一步花三十秒，能省掉后面两小时的链接报错排查。

2.3 落位路径的选择：别放在带空格或中文的目录

解压目标路径我一般固定成/opt/qt/5.9.9-static，理由有三：路径短，qmake 生成的 Makefile 里路径不会过长；不带空格和中文，老版本 qmake 对含空格路径的处理有历史问题；权限清晰，/opt下统一管理，卸载时整个目录删掉即可。

# 建目录并解压，--strip-components=1 去掉顶层目录，直接落到目标路径 sudo mkdir -p /opt/qt/5.9.9-static sudo tar -xzf qt-5.9.9-gcc485-libc217-static-qt-xcb.tar.gz \ -C /opt/qt/5.9.9-static --strip-components=1 # 确认 qmake 可执行 /opt/qt/5.9.9-static/bin/qmake -v

--strip-components=1的作用是剥掉压缩包自带的顶层目录，让内容直接铺在/opt/qt/5.9.9-static下，否则会多一层嵌套，后面写QMAKE路径容易多写一级。qmake -v输出里应该能看到Using Qt version 5.9.9，同时注意它打印的安装前缀是不是你解压的路径——如果前缀还是打包时的原始路径，说明这个包是 relocatable 的，qmake 会按自身位置推算，一般没问题，但要在下一步配置里留意。

3. 配置 qmake 与编译参数：静态链接的开关都在哪

包解压好只是有了工具链，真正决定「编出来是不是静态」的是 qmake 的 mkspec 和项目 .pro 里的链接配置。Qt 5.9.9 这套静态包自带linux-g++的静态 mkspec，但默认 qmake 仍可能按动态方式生成链接行，得手动把静态开关打开。这一章把 qmake 选择、.pro 配置、编译验证三段串起来。

3.1 用包内 qmake 而不是系统 qmake

系统里如果装过 Qt，qmake命令很可能指向动态版，编出来的东西表面能跑，一拷到目标机就缺库。所以项目里我强制用绝对路径调用包内 qmake，或者在 Makefile 生成阶段就锁死：

# 用包内 qmake 生成 Makefile，注意绝对路径 /opt/qt/5.9.9-static/bin/qmake /path/to/project.pro -spec linux-g++ CONFIG+=static # 生成后立刻检查 Makefile 里的链接行是否带 -static grep -E '^LFLAGS|^LIBS' Makefile | head -n 5

-spec linux-g++指定 mkspec，静态包里的这个 spec 已经把QMAKE_LFLAGS配成静态模式；CONFIG+=static是双保险，让 qmake 在生成阶段就把QT_CONFIG里的 shared 去掉。生成完必须grep一下LFLAGS，正常应该看到-static字样，如果只有-Wl,-rpath之类动态痕迹，说明 qmake 没吃到静态配置，得回去查-spec路径对不对。

3.2 .pro 文件里必须显式声明的几项

光靠命令行参数不够，.pro 里有些项不写，链接阶段会偷偷拉动态库。我一般在这套静态环境下的 .pro 头部固定加三行：

# 强制静态链接 Qt 库 CONFIG += static CONFIG -= shared # 静态插件需要显式导入，否则 xcb 平台插件不会被链进来 QTPLUGIN += qxcb # 关掉对系统动态 Qt 的探测 QT_NO_GLIB = 1

CONFIG += static和CONFIG -= shared是一对，只加不减在某些 qmake 版本里 shared 仍会残留。QTPLUGIN += qxcb是这套-qt-xcb包的关键——静态构建下平台插件不会自动加载，必须通过 QTPLUGIN 把libqxcb.a链进最终二进制，否则程序启动时报This application failed to start because no Qt platform plugin could be initialized。QT_NO_GLIB = 1是关掉 glib 事件循环集成，静态环境下 glib 的动态探测容易引入意外依赖，老项目里我一般直接关掉。

3.3 编译并确认产物是静态可执行文件

配置对了，make之后要验证产物性质，不能只看它跑没跑起来：

# 编译 make -j$(nproc) # 检查产物是否动态链接了 Qt 库 ldd ./your_app | grep -i qt # 检查文件类型和是否静态链接 file ./your_app

ldd那条如果输出为空，说明没有动态依赖 Qt，是好现象；如果列出libQt5Core.so.5，说明静态配置没生效，回去查 3.1 的-spec和 3.2 的CONFIG。file输出里带statically linked是最理想的结果，但注意 glibc 部分通常仍显示dynamically linked，这是正常的，前面说过 glibc 没法完全静态。真正要盯的是 Qt 库有没有被动态拉进来。

注意：ldd对静态二进制有时会报not a dynamic executable，这恰恰是静态链接成功的信号，别被这句吓到以为编坏了。

4. 静态包落地时的避坑清单：五条踩过的坑

这套包在老系统上落地，坑集中在版本错配、插件漏链、路径污染三块。下面五条是我和同事实际踩过的，按「现象 → 原因 → 解决」记，照着排能省不少时间。

4.1 启动报 no Qt platform plugin could be initialized

现象：程序编译通过，拷到目标机一跑就弹这句，退出码 134。原因：静态构建下 xcb 平台插件没被链进二进制，运行时又找不到plugins/platforms/libqxcb.a。解决：回到 .pro 加QTPLUGIN += qxcb，重新 qmake 生成 Makefile 再 make；如果还不行，检查包内plugins/platforms/下是否真有libqxcb.a，没有就是包不完整。

4.2 链接阶段报 undefined reference tostd::__cxx11::basic_string

现象：make 到最后链接步骤，一堆std::__cxx11相关符号找不到。原因：编译机 gcc 是 5.x 以上，默认走新 ABI（_GLIBCXX_USE_CXX11_ABI=1），而静态包是 gcc 4.8.5 编的，走旧 ABI。解决：编译时加-D_GLIBCXX_USE_CXX11_ABI=0，或者在 .pro 里QMAKE_CXXFLAGS += -D_GLIBCXX_USE_CXX11_ABI=0，让整个项目回到旧 ABI 编译。

4.3 目标机 glibc 低于 2.17 直接段错误

现象：程序在编译机跑得好好的，拷到目标机启动即 segfault，无任何输出。原因：目标机 glibc 是 2.12 或更低，静态程序里链接的 2.17 符号在运行时解析失败。解决：这套包的下限就是 2.17，目标机低于这个版本只能换编译环境重新构建，或者改用容器化交付，别指望改链接参数绕过。

4.4 qmake 报 Could not find qmake spec 'linux-g++'

现象：执行qmake -spec linux-g++时报找不到 spec。原因：-spec后面跟的是 mkspec 目录名，qmake 会去$QTDIR/mkspecs/下找，如果解压时--strip-components用错导致 mkspecs 目录层级不对，就找不到。解决：ls /opt/qt/5.9.9-static/mkspecs/linux-g++确认目录存在，不存在就重新解压，别手动挪目录。

4.5 编译机 PATH 里有系统 qmake 导致混用

现象：明明用了绝对路径 qmake，生成的 Makefile 里QMAKE变量却指向/usr/bin/qmake。原因：.pro 里如果调用了qmake子进程或者某些构建脚本里写死了qmake，会走 PATH。解决：构建脚本里统一用QMAKE=/opt/qt/5.9.9-static/bin/qmake环境变量传递，或者在 shell 里export PATH=/opt/qt/5.9.9-static/bin:$PATH把包内 qmake 提到最前，编完再恢复。

5. 装完怎么验证跑通：三步确认静态交付真的成立

配置和编译都过了，最后一步是把「能编」变成「能交付」。静态编译的价值全在目标机上，所以验证必须在干净环境里做，不能只在编译机自测。我一般走三步：查依赖、查插件、查运行。

5.1 用 ldd 和 readelf 双重确认无 Qt 动态依赖

# 第一步：确认没有动态 Qt 库 ldd ./your_app | grep -iE 'qt|xcb' # 第二步：看动态段里有没有 Qt 相关 NEEDED 项 readelf -d ./your_app | grep NEEDED

ldd输出为空或者只有 libc、libm、libpthread 这类系统库，说明 Qt 部分已经静态化。readelf -d的NEEDED列表更权威，如果里面出现libQt5Core.so.5、libqxcb.so，说明还有动态残留，得回 .pro 补QTPLUGIN或者检查是不是某个第三方库偷偷链了动态 Qt。这两条命令我每次交付前都跑，比肉眼翻 Makefile 靠谱。

5.2 在无 Qt 环境的目标机上做冒烟测试

把二进制拷到一台没装 Qt、没装 X11 开发包的目标机，直接运行。这一步是静态交付的终审：

# 目标机上确认没有 Qt 运行库 ls /usr/lib/x86_64-linux-gnu/ | grep -i qt # 直接运行，观察是否正常起窗口或输出 ./your_app --version

如果ls确认目标机没有 Qt 库，程序还能正常启动并打印版本，静态交付就成立了。如果报平台插件错误，回到 4.1 排查；如果报 glibc 符号错误，回到 4.3 确认目标机版本。冒烟测试别只跑--version，最好让程序真正初始化一次 GUI 主循环，因为平台插件的问题往往在窗口创建时才暴露。

5.3 用 strings 抽查插件是否真的编进去了

有时候ldd干净但运行仍报插件问题，这时用strings抽查二进制里有没有 xcb 插件的特征字符串：

# 抽查二进制里是否含 xcb 平台插件标识 strings ./your_app | grep -i 'qxcb\|xcb'

正常应该能看到qxcb相关的元数据字符串，说明插件确实被链进去了。如果一条都没有，即使ldd干净，运行时也会因为找不到平台插件而失败——这种情况多半是QTPLUGIN写了但 qmake 没重新生成 Makefile，增量 make 没把插件链进去，得make clean后全量重编。

从那以后我每次交付静态 Qt 程序，都强制在目标机跑一遍 5.1 到 5.3 这三步，哪怕编译机自测已经通过——静态编译的坑大多藏在「编译机有、目标机没有」的差异里，只有干净环境才能把问题逼出来。希望这套流程帮到你，少走我当年那两天的弯路。

本文还有配套的精品资源，点击获取