简介Qt 5.9.9 Linux 静态编译库面向需要在目标 Linux 环境无 Qt 运行时依赖下部署图形界面程序的开发者。基于 CentOS 7.6 x64、GCC 4.8.5、glibc 2.17 构建编译出的程序经 ldd 查看不再依赖 Qt 动态库并已启用 -qt-xcb 支持。压缩包约 197.4MB共 2000 个文件包含 h 头文件、pri/prf 工程配置、cmake 模块、a 静态库及 prl 链接描述文件等同时还有 qm 翻译资源与 conf 配置库结构完整可直接集成或参考自带 configure 参数复现静态构建。目前已有 569 人学习浏览适合需要发布免安装 Qt 图形程序、或在受限 Linux 环境中进行软件部署的开发者使用省去自行交叉编译依赖的繁琐过程。1. 为什么我最后选了qt-5.9.9-gcc485-libc217-static-qt-xcb静态编译包把一段Qt程序从开发机拷到客户那台CentOS 7服务器上运行时报错找不到libQt5Core.so.5那一刻我就知道动态链接的Qt程序在旧Linux上部署是一场灾难。后来我找到qt-5.9.9-gcc485-libc217-static-qt-xcb这个静态编译包gcc 4.8.5、glibc 2.17正好匹配那台老系统。这篇文章记录了我从解压、配置到部署验证的完整过程。如果你也被Linux上的Qt动态库依赖搞得焦头烂额或者想把Qt程序打包成单个二进制文件拷到没装Qt的机器上这篇笔记应该能帮你少走弯路。我会把环境检查、目录配置、qmake设置、典型报错都拆开讲每一步都是实际执行过的命令不是纸上谈兵。2. 环境准备与版本适配gcc 4.8.5和glibc 2.17的坑2.1 先确认目标系统的gcc和glibc版本这不是走形式。Qt是C写的编译时用的GCC版本和glibc版本直接决定二进制能不能在目标机器上跑。GCC 4.8.5是CentOS 7自带的版本如果你编译用的gcc比目标系统更新的版本比如5.x或7.x生成的二进制很可能在目标系统上报错。同样的道理glibc 2.17对应CentOS 7新glibc上编译的程序放到老glibc上通常会报GLIBC_XX not found反之则没问题。所以拿到一个qt-5.9.9-gcc485-libc217这样的包第一件事不是解压而是确认你的目标系统版本。我一般用三条命令cat /etc/redhat-release gcc --version ldd --version/etc/redhat-release确认是CentOS 7还是别的发行版直接看大版本。gcc --version确认编译器版本。这里有个细节gcc --version显示的可能是系统默认编译器比如4.8.5但如果你手动装过devtoolset实际用的可能是7.x。要用which gcc看一下当前生效的路径。ldd --version显示glibc版本注意它显示的第一行就是版本号。如果你的系统glibc低于2.17比如CentOS 6那这个libc217包就不适合需要找对应的libc版本低一点的静态包。如果glibc是2.17或更高那兼容性基本没问题。gcc版本倒是不太需要担心静态编译包的库本身已经编译好了只要你的编译器不会尝试去链接老版本的头文件即可但最好还是保持gcc主版本不变避免莫名其妙地在头文件兼容性上翻车。2.2 下载并解压qt-5.9.9静态包下载这步我建议放到内网镜像站或者用官方渠道反正别从奇怪的论坛拉包。下完之后先校验一下文件完整性避免下载过程中文件损坏尤其是几百MB的包传输中途断一下没感觉出来解压时才报错就很烦。md5sum qt-5.9.9-gcc485-libc217-static-qt-xcb.tar.gz建议解压前先查一下官方或内网给的校验值对不上就直接重新下。我一般会解压到/opt目录这是一个约定俗成的放第三方库的地方。sudo tar -zxvf qt-5.9.9-gcc485-libc217-static-qt-xcb.tar.gz -C /opt/解压完目录名很长我建议给创建一个软链接方便后面配置环境变量的时候少写几个字符sudo ln -s /opt/qt-5.9.9-gcc485-libc217-static-qt-xcb /opt/qt-static之后所有配置都用/opt/qt-static如果将来要切换版本只需要把软链接指到另一个目录即可不用改一大堆配置。2.3 解压后的目录结构有什么讲究这个静态包解压后里面主要就是几个目录bin/包含qmake和moc,rcc等Qt工具注意qmake在bin目录下不是lib目录。lib/静态库文件比如libQt5Core.a,libQt5Widgets.a以及各种插件。include/头文件目录里面是按模块分的比如QtWidgets,QtCore。plugins/平台插件最重要的是platforms/libqxcb.a这个在静态编译里很关键等下会单独说。mkspecs/qmake的规范文件里面定义了编译器、链接器的参数。你可能会问既然是静态包为什么不把所有插件都编到库里实际上静态Qt包里的插件比如qxcb也是以静态库形式提供的但需要在编译你的程序时指定QTPLUGIN qxcb它才会链接进去。如果忘了加程序运行时会报找不到xcb插件这个坑我后面细讲。解压完之后先不要急着设环境变量先去/opt/qt-static/bin下直接跑一下qmake看它能不能正常执行/opt/qt-static/bin/qmake -v正常情况下会显示QMake version 3.1和Using Qt version 5.9.9 in /opt/qt-static/lib之类的信息。如果这里就报错说明包本身损坏或者系统缺一些基础库这时候就得回头检查。3. 配置环境变量与qmake三个最容易写错的路径3.1 设置QTDIR和PATH解压没问题之后配置环境变量看起来是小事但这里踩过太多坑了。我先给出推荐写法然后解释为什么顺序很重要。export QTDIR/opt/qt-static export PATH$QTDIR/bin:$PATHQTDIR不是Qt官方强制要求的但很多第三方的构建工具和脚本会读取这个变量最好还是设置上。PATH必须把$QTDIR/bin放在最前面这样执行qmake时找的是静态包里的qmake而不是系统自带的qmake。如果你把PATH写成export PATH$PATH:$QTDIR/bin那恰好系统自带了qmake就用错版本了到时候编译出来的程序是动态链接的白白浪费一晚上。这段配置最好写进~/.bashrc而不是临时在终端敲。写进bashrc后以后每次登录shell都会自动加载不用每次手动source。注意如果你当前终端已经有旧的PATH可以通过hash -r刷新一下命令路径缓存不然有时候which qmake还是显示旧路径。另一个容易写错的点是QTDIR末尾不要写成一个带版本号的路径再套一层。比如有人会写export QTDIR/opt/qt-static/lib这就错了因为qmake会基于QTDIR去推断lib和include的位置你指定到lib它就会去找lib/lib结果莫名其妙。正确做法是让QTDIR指向Qt安装的根目录也就是bin和lib同级的那个目录。3.2 验证qmake版本和平台插件配置完环境变量之后验证一下qmake -v which qmake第一行应该显示Qt 5.9.9第二行应该输出/opt/qt-static/bin/qmake。如果which qmake显示的是/usr/lib64/qt5/bin/qmake说明PATH顺序有问题回头检查bashrc。接下来检查这个qmake默认使用的平台插件也就是xcb相关配置。执行qmake -query QT_INSTALL_PLUGINS qmake -query QT_VERSIONQT_INSTALL_PLUGINS应该指向包内的plugins目录如果它指向系统目录说明qmake本身路径有问题或者环境变量没有生效。我遇到过一种情况QT_INSTALL_PLUGINS被系统环境变量覆盖指向了/usr/lib64/qt5/plugins结果静态包根本没被用上折腾了半天。3.3 在.pro文件中正确处理静态Qt新建一个最简单的Qt项目比如test_static.pro内容如下TEMPLATE app QT widgets CONFIG static QTPLUGIN qxcb SOURCES main.cppCONFIG static有时候不是必须的因为qmake本身已经知道了这个Qt是静态编译的但在旧版本qmake中显式声明能避免一些怪异链接行为加上没坏处。QTPLUGIN qxcb是重点。Qt的xcb平台插件正常情况下是动态加载的但静态编译之后插件也变成了静态库必须通过这个变量把它链接进程序。如果你的程序不需要GUI可以去掉Qt widgets但QTPLUGIN仍然需要。如果忘了写QTPLUGIN qxcb编译过程不会有任何报错但运行时就会提示could not find the Qt platform plugin xcb这个错误我在第4章详细说。然后在main.cpp里还需要手动导入插件这是静态Qt特有的要求#include QApplication #include QLabel #include QtPlugin Q_IMPORT_PLUGIN(qxcb) int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Hello static qt); label.show(); return app.exec(); }Q_IMPORT_PLUGIN(qxcb)这行编译时必须写否则即使QTPLUGIN配置了插件也不会被链接进去。不理解的话你可以把它理解为告诉链接器“我这个程序需要xcb这个静态插件别在链接时优化掉了。”4. 常见问题与排查静态Qt的五个典型坑4.1 现象一编译时找不到Qt5XcbQpa头文件现象在FQNSF_UPDATE.h或某些xcb相关代码中编译报错fatal error: QtXcbQpa/qtxcbqpa.h: No such file or directory。原因这个头文件在静态包中是存在的但路径比较特殊。有时候是因为你的INCLUDEPATH少写了静态包装的include目录或者QTDIR配置成了错误的路径。实际上Qt头文件默认分两层一层是include/QtXcbQpa另一层是include/QtXcbQpa/private有些代码需要引用私有头文件如果INCLUDEPATH没有指向$QTDIR/include就找不到。解决先确认环境变量QTDIR是否生效然后在.pro文件里显式添加INCLUDEPATH $QTDIR/include DEPENDPATH $QTDIR/include如果问题依旧可能是qmake没有正确识别这个包。我会执行qmake -v看输出里的Qt版本路径是不是/opt/qt-static如果不是那就说明PATH优先级还是错的需要用which qmake逐一检查。4.2 现象二链接时报错undefined reference to XOpenDisplay现象编译链接阶段报错大量undefined reference to XOpenDisplay、XTestFakeMotionEvent之类的X11符号。原因Qt的xcb插件本质上依赖X11库。动态链接时Qt本身会帮你把X11库一起带上但静态链接时不会自动传导链接依赖需要你手动在.pro文件里加入X11相关的库。解决在.pro文件末尾加上LIBS -lX11 -lXext -lXcb -lXcursor -lXfixes -lXrandr LIBS -lGL -lfontconfig -lfreetype注意不同系统可能还需要-lXrender如果继续报缺什么就补什么。这种“缺一个加一个”的做法看起来比较原始但在这个场景里确实是最可靠的。还有一点如果你用的gcc是4.8.5而静态Qt包里的Qt库是用更高版本gcc编译的链接器的顺序也会导致符号缺失最好把LIBS放在QTPLUGIN之后。4.3 现象三运行报错could not find or load the Qt platform plugin xcb现象编译成功但在干净环境或开发机上运行时提示qt.qpa.plugin: Could not find the Qt platform plugin xcb in 然后程序崩溃。原因这是静态Qt最典型的翻车点。在动态Qt下程序运行时去plugins/platforms/目录找libqxcb.so但静态编译后不存在插件目录必须把插件直接链接进可执行文件。如果你只写了QTPLUGIN qxcb却没有在main.cpp里Q_IMPORT_PLUGIN(qxcb)或者反过来都会出现这种情况。解决#include QtPlugin Q_IMPORT_PLUGIN(qxcb)同时.pro文件里保留QTPLUGIN qxcb然后清理项目重新编译make distclean再make。还有一种情况是你设置了环境变量QT_QPA_PLATFORM_PLUGIN_PATH指向了错误的位置静态程序会尝试从这个路径加载插件但插件本身已链接进程序反而会混淆最好把这类环境变量删掉。编译完成后验证strings ./myapp | grep -i xcb如果能看到类似qxcb或libqxcb.a的路径信息说明插件已经被链接进去了。这个方法很土但很有效基本一眼就能看出插件有没有编进去。4.4 现象四用ldd检查程序发现还是依赖libQt5Core.so.5现象刚写完静态编译自我感觉良好但运行前用ldd ./myapp一看显示libQt5Core.so.5 /usr/lib64/libQt5Core.so.5。原因这说明你编译时用的还是系统的动态Qt而不是静态包里的qmake。最常见的原因就是PATH顺序问题或者.pro文件里显式链接了-lQt5Core动态库。另一种可能你调用了系统里的qmake而这个qmake指向了系统Qt。静态包里的qmake生成的Makefile会去链接libQt5Core.a而不是.so。解决which qmake确认是/opt/qt-static/bin/qmake后强制用绝对路径重新生成Makefilerm -rf Makefile /opt/qt-static/bin/qmake -o Makefile myapp.pro make clean make如果之前编译过务必先make clean否则旧的动态库对象文件还躺在那里链接时会优先用旧产品。还有可以检查生成的Makefile里有没有-lQt5Core如果是-lQt5Core一般来说动态链接如果是libQt5Core.a的路径或者-Wl,-Bstatic才是静态链接。4.5 现象五二进制太大运行占用内存过高怀疑静态编译亏了现象终于编译成功可执行文件有几十MB运行起来内存占用也比动态版高很多心里不踏实觉得是不是哪里配错了。原因这其实是静态编译的正常代价。Qt本身就有一定的体积再加上xcb插件、opengl fontconfig等依赖几十MB是很常见的。内存占用高可能是因为静态了所有模块包括你可能用不到的Qt Graphics、Qt XML等。最有效的办法是只启用你需要的Qt模块把多余的QT 删掉尤其是QT xml、QT network这些用不到的。解决QT - xml network如果程序真的用不到某些模块减掉的体积立竿见影。另外用strip去掉符号表strip --strip-unneeded ./myapp这一步通常能缩小20%以上的体积而且完全不影响运行。从那以后我每次编译完都会顺手strip一下已经成习惯了。5. 装完怎么验证跑通从一个最小窗口程序到部署验证静态Qt环境是否真正跑通我习惯走一套固定的流程从最简单的窗口程序开始到最后确认能在完全没有Qt的干净系统上运行。先建一个干净的目录mkdir -p /tmp/qttest cd /tmp/qttest写一个最简单的main.cpp打开一个窗口显示一句话不需要任何业务逻辑。用一个最小化的.pro文件TEMPLATE app TARGET hellostatic QT widgets CONFIG static QTPLUGIN qxcb SOURCES main.cpp然后编译/opt/qt-static/bin/qmake make注意这里我直接执行make没有用make -j因为某些旧内核上并行编译偶尔会出奇怪错误一台机器跑一次老老实实单线程就好。编译完成后先在当前机器上运行一次./hellostatic如果弹出一个空白窗口说明本机运行没问题但这并不代表环境配好了。接下来才是关键ldd ./hellostatic理想的输出中应该没有任何Qt相关的动态库依赖。libc,libX11这类系统基础库存在是正常的但不能有libQt5Core.so.5、libQt5Widgets.so.5这样的输出。一旦出现说明之前的第4章那些坑你踩了回头去改qmake路径。确认没有Qt动态库后我一般会在虚拟机里起一个干净的CentOS 7不带任何Qt安装然后把hellostatic文件拷过去直接运行。这个环境能跑起来才叫真正合格。如果只在开发机上验证平时自己的机器可能已经装过Qt库所以在开发机上跑通根本不代表别的地方能跑通。最后一步我习惯检查一下xcb插件到底有没有被正确链接用前面提到的strings命令strings ./hellostatic | grep -i qxcb如果看到qxcb说明插件已经在可执行文件里部署到任何有X11的环境都没问题。注意这里说的是X11环境如果你的目标机是纯命令行无显示环境那窗口程序本来就跑不起来这跟xcb插件无关是显示服务器的问题。到这里静态Qt环境的验证就跑通了。从那以后我每次部署Qt程序都强制走一遍这套流程qmake绝对路径确认、make clean重编、ldd检查动态依赖、干净虚拟机实测。虽然看起来多花了几分钟但省去的往往是到客户现场才发现运行不了的尴尬。希望帮到你。本文还有配套的精品资源点击获取