简介面向 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 7gcc 4.8.5glibc 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 -mgcc --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-components1 去掉顶层目录直接落到目标路径 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-components1 # 确认 qmake 可执行 /opt/qt/5.9.9-static/bin/qmake -v--strip-components1的作用是剥掉压缩包自带的顶层目录让内容直接铺在/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系统里如果装过 Qtqmake命令很可能指向动态版编出来的东西表面能跑一拷到目标机就缺库。所以项目里我强制用绝对路径调用包内 qmake或者在 Makefile 生成阶段就锁死# 用包内 qmake 生成 Makefile注意绝对路径 /opt/qt/5.9.9-static/bin/qmake /path/to/project.pro -spec linux-g CONFIGstatic # 生成后立刻检查 Makefile 里的链接行是否带 -static grep -E ^LFLAGS|^LIBS Makefile | head -n 5-spec linux-g指定 mkspec静态包里的这个 spec 已经把QMAKE_LFLAGS配成静态模式CONFIGstatic是双保险让 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 1CONFIG 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_appldd那条如果输出为空说明没有动态依赖 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_ABI1而静态包是 gcc 4.8.5 编的走旧 ABI。解决编译时加-D_GLIBCXX_USE_CXX11_ABI0或者在 .pro 里QMAKE_CXXFLAGS -D_GLIBCXX_USE_CXX11_ABI0让整个项目回到旧 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 NEEDEDldd输出为空或者只有 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 动态依赖ldd ./app | grep -i qt输出为空动态段 NEEDEDreadelf -d ./app | grep NEEDED无 libQt5*.so插件内置strings ./app | grep qxcb有 qxcb 特征串目标机冒烟无 Qt 环境直接运行正常启动无插件报错从那以后我每次交付静态 Qt 程序都强制在目标机跑一遍 5.1 到 5.3 这三步哪怕编译机自测已经通过——静态编译的坑大多藏在「编译机有、目标机没有」的差异里只有干净环境才能把问题逼出来。希望这套流程帮到你少走我当年那两天的弯路。本文还有配套的精品资源点击获取