1. 换台机器就报 xcb 缺失:代码开发工具打包到底在解决什么
本机跑得好好的 Qt 工具,拷到同事机器上双击就弹 qt.qpa.plugin: Could not find the Qt platform plugin "xcb",这种翻车在 Ubuntu 下太常见。linuxdeployqt 这类代码开发工具要解决的不是编译,而是把可执行文件、Qt 库、平台插件和系统级 so 依赖收进一个目录,让目标机器不装 Qt 也能跑。这篇操作指南按依赖来源、收库命令、验证、避坑的顺序走,适合用 Qt 5.15.2 或 Qt 6 做桌面工具、需要发给客户或部署到无开发环境机器的开发者。新手能照着敲,熟手可以拿后面的检查表当排查清单。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 依赖从哪来:代码开发工具的收库逻辑与 ldd 排查
linuxdeployqt 不是魔法,它做的事情可以拆成三步:找到可执行文件真正链接了哪些库,把 Qt 库和插件按相对路径摆进 AppDir,再改写可执行文件的 RUNPATH,让运行时优先从打包目录加载。理解这三步,后面命令参数才不会乱填。
2.1 一次编译通过不等于换机可跑:依赖链的三层
在开发机上 make 通过,只证明编译器能找到头文件和库。程序真正跑起来要过三层:第一层是动态链接器,它按 DT_NEEDED 找 .so;第二层是 Qt 的插件加载器,它要在 platforms/ 目录下找到 libqxcb.so;第三层是系统级 so,比如 libxcb-*、libfontconfig、libGL。很多打包失败不是 Qt 库没带,而是第二层或第三层断了。
材料里那个报错 cannot mix incompatible Qt library (version 0x50601) with this library 属于第一层和第二层之间的冲突:程序加载了 A 套 Qt 库,插件却来自 B 套 Qt 库。0x50601 是 Qt 5.6.1 的版本编码,说明两边版本号对不上。打包时如果只把 libQt5Widgets.so.5 拷进去,却让插件从系统路径加载,就会出这种问题。
所以判断一个 Qt 程序能不能脱离开发机,不能只看 ldd 有没有 not found,还要看 ldd 解析出来的路径是不是指向打包目录,以及插件目录是否存在、qt.conf 有没有把插件路径指错。
2.2 用 ldd 和 readelf 摸清依赖来源
先拿一个已编译好的可执行文件做体检。不要一上来就跑 linuxdeployqt,先看它现在依赖什么:
bash复制# 查看可执行文件的动态库依赖,重点看 Qt 库指向哪里
ldd build/myapp | grep -i qt
# 查看 RUNPATH / RPATH,判断运行时优先搜索哪些目录
readelf -d build/myapp | grep -E 'RPATH|RUNPATH'
ldd 输出里如果出现 /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5,说明它当前链接的是系统 Qt。打包后要变成类似 $ORIGIN/../lib/libQt5Widgets.so.5 的相对路径。readelf -d 里的 RUNPATH 就是动态链接器搜索库的目录列表,linuxdeployqt 收库后会把它改成 $ORIGIN/../lib 这种形式,$ORIGIN 表示可执行文件所在目录,这样整个目录拷到哪都能算相对路径。
如果是自己编译的 Qt,还要确认编译器和 Qt 套件是同一套。比如用 Qt 5.15.2 的 qmake 编出来的程序,却用系统 Qt 5.15.3 的插件去跑,也可能出现版本混用。排查时把 ldd 和 readelf 的输出各存一份,后面打包完做对比,能快速看出哪些库被收进去了、哪些还在指向系统。
2.3 Qt 插件目录与 qt.conf 的作用
Qt 的平台插件不是普通动态库,它由 Qt 的插件加载器按目录规则查找。默认情况下,加载器会去 Qt 安装路径下的 plugins/platforms 找 libqxcb.so;如果程序被拷到别的机器,Qt 安装路径不存在,加载器就报 Could not find the Qt platform plugin "xcb"。
常见做法是在可执行文件旁边放一个 qt.conf,把插件路径固定到相对目录:
ini复制[Paths]
Prefix = ..
Plugins = plugins
Libraries = lib
这段配置的意思是:以可执行文件所在目录的上一级为前缀,插件去 plugins 下找,库去 lib 下找。配合 AppDir 的目录结构,运行时就不会再回退到系统 Qt 路径。
需要强调的是,qt.conf 只解决“去哪找”,不解决“找不找得到”。如果 plugins/platforms/libqxcb.so 本身没被收进 AppDir,配置写得再对也没用。所以收库和写配置要一起做,不能只做一半。
3. linuxdeployqt 上手:把 Qt 程序收进 AppDir 的命令与参数
这一章按一次完整的打包流程走:先准备 AppDir 目录,再写 desktop 入口文件,最后调用 linuxdeployqt 收库。命令里的路径都按实际项目改,不要照抄目录名。
3.1 准备 AppDir 目录结构
AppDir 是一个符合桌面应用发布习惯的目录,核心结构如下:
text复制AppDir/
├── usr/
│ ├── bin/
│ │ └── myapp
│ ├── lib/
│ ├── plugins/
│ └── share/
│ ├── applications/
│ │ └── myapp.desktop
│ └── icons/
先把编译产物放进去:
bash复制# 创建 AppDir 基础目录,把可执行文件放进去
mkdir -p AppDir/usr/bin
cp build/myapp AppDir/usr/bin/myapp
chmod +x AppDir/usr/bin/myapp
chmod +x 不能省。后面用脚本或压缩包分发时,执行位很容易丢,用户双击没反应,第一反应会以为程序坏了,其实是权限问题。
接着写 desktop 文件。linuxdeployqt 通过 desktop 文件里的 Exec 找到可执行文件,所以这个文件不是摆设:
ini复制[Desktop Entry]
Type=Application
Name=MyApp
Exec=myapp
Icon=myapp
Categories=Utility;
Exec=myapp 写相对名称,不要写 /home/xxx/build/myapp 这种绝对路径。绝对路径在开发机上能跑,换台机器就失效。图标名称要和后面放进 icons 目录的文件名对应,否则桌面环境找不到图标。
3.2 调用 linuxdeployqt 的核心命令
把 desktop 文件放到 AppDir/usr/share/applications/ 下,然后执行:
bash复制# 以 desktop 文件为入口,收 Qt 库和非 Qt 依赖,并生成 AppImage
linuxdeployqt AppDir/usr/share/applications/myapp.desktop \
-bundle-non-qt-libs \
-appimage
这条命令里几个参数各有分工:
AppDir/usr/share/applications/myapp.desktop:入口参数。工具会解析Exec,找到AppDir/usr/bin/myapp,再顺着依赖收库。-bundle-non-qt-libs:把非 Qt 的系统库也收进来,比如libxcb-*、libfontconfig这类。不加这个参数,Qt 库可能收全了,但系统 so 还指着开发机。-appimage:在收库完成后生成 AppImage。如果只想发一个目录,可以不加这个参数,手动打包AppDir。
如果项目用了 QML,还要加 -qmldir 指向 QML 源码目录,否则 QML 运行时依赖可能漏收。如果不需要翻译文件,可以加 -no-translations 减小体积。参数不是越多越好,先保证核心依赖收全,再考虑裁剪。
执行过程中要盯输出。工具会打印它复制了哪些库、跳过了哪些库。看到 ERROR: Could not find 或 WARNING: Skipping 要停下来看,不要直接拿产物去发布。
3.3 参数取舍与常见误用
一个常见误用是把整个 build 目录当成 AppDir 传给 linuxdeployqt。工具需要的是 desktop 入口和规范目录,不是编译中间产物。build 目录里可能有 CMake 缓存、对象文件、测试程序,收进去只会让包变大,还容易把错误的库带进来。
第二个误用是混用 Qt 套件。开发机上可能同时装了系统 Qt 和自编译 Qt,PATH 里先找到哪个,linuxdeployqt 就可能用哪个。打包前用 which linuxdeployqt 和 qmake -v 确认工具与 Qt 套件来自同一套环境。材料里的 cannot mix incompatible Qt library 很多时候就是这一步没对齐。
第三个取舍是发 AppImage 还是发目录。AppImage 对用户友好,双击就能跑,但体积大,启动时要做挂载;发目录更轻,适合内部工具,但要求目录结构完整,用户不能只拷一个可执行文件。我的习惯是内部发布用目录加分发包,外部客户用 AppImage,两者都保留同一份 AppDir 作为源。
4. 打包后怎么验:链接层、加载层、运行层三步自证
打包完成不等于能交付。验证要分三层走:链接层看库指向,加载层看插件能不能被找到,运行层看真实环境能不能启动。三层都过,才算落地。
4.1 链接层验证:ldd 与 readelf 检查相对路径
先检查可执行文件的依赖有没有收进 AppDir:
bash复制# 检查是否还有 Qt 库指向系统路径
ldd AppDir/usr/bin/myapp | grep -i qt
# 检查 RUNPATH 是否已经指向相对目录
readelf -d AppDir/usr/bin/myapp | grep -E 'RPATH|RUNPATH'
期望的结果是 Qt 库指向 AppDir/usr/lib/ 下的文件,RUNPATH 里出现 $ORIGIN/../lib。如果 ldd 仍然输出 /usr/lib/x86_64-linux-gnu/libQt5*.so,说明收库没生效,或者程序本身的 RUNPATH 被覆盖了。
还要检查有没有 not found:
bash复制# 找出所有未解析的依赖
ldd AppDir/usr/bin/myapp | grep 'not found'
有输出就逐个补。不要只看 Qt 库,libxcb-xinerama.so.0、libxkbcommon-x11.so.0 这类 xcb 相关库漏掉,程序启动时一样会崩。
4.2 加载层验证:用 QT_DEBUG_PLUGINS 看插件路径
Qt 提供了一个很直接的调试开关:
bash复制# 打开插件加载日志,观察 xcb 插件从哪个路径加载
QT_DEBUG_PLUGINS=1 ./AppDir/usr/bin/myapp
输出里会打印 Qt 搜索插件的目录列表,以及每个插件加载成功或失败的原因。重点看 platforms/libqxcb.so 这一行:如果它从 AppDir/usr/plugins/platforms/ 加载,说明 qt.conf 和目录结构都对;如果它还在找 /usr/lib/.../plugins/platforms,说明 qt.conf 没生效或路径写错。
这一步能提前发现 Could not find the Qt platform plugin "xcb"。不要等用户报错再查,打包机上先跑一遍,把日志留档。
4.3 运行层验证:干净目录与最小环境变量
最后模拟用户机器:把 AppDir 拷到一个干净目录,清掉可能干扰的 Qt 环境变量,再启动:
bash复制# 用最小环境变量运行,避免开发机上的 Qt 路径干扰
env -i HOME="$HOME" DISPLAY="$DISPLAY" \
./AppDir/usr/bin/myapp
env -i 会清空环境变量,只保留显示和 HOME。如果这样能启动,说明程序不依赖开发机上的 QT_PLUGIN_PATH、LD_LIBRARY_PATH 这类变量。如果启动失败,再看错误信息:是缺库、缺插件,还是权限问题。
三层验证都过了,再把整个目录拷到另一台没有 Qt 开发环境的 Ubuntu 机器上试一次。开发机上的“干净目录”仍然可能带着系统 Qt,真实目标机才是最终考场。
5. 避坑记录:五类打包翻车现场与排查顺序
下面这些坑都能从依赖链和插件机制推出来,按“现象 → 原因 → 解决”记录,排查时按顺序看,不要一上来就重装 Qt。
5.1 现象:cannot mix incompatible Qt library
现象:程序启动直接报 fatal: cannot mix incompatible Qt library (version 0x50601) with this library,或者加载插件时崩溃。
原因:可执行文件链接了一套 Qt,插件或依赖库来自另一套 Qt。常见于开发机同时存在系统 Qt 和自编译 Qt,打包时 linuxdeployqt 找到的库与程序实际链接的库不是同一套。
解决:先 ldd 看程序链接的 Qt 库路径,再 QT_DEBUG_PLUGINS=1 看插件从哪加载。两边必须指向同一套 Qt。打包前用 qmake -v 确认套件版本,清理 LD_LIBRARY_PATH、QT_PLUGIN_PATH 等变量,重新收库。不要手工把两套 Qt 的库混拷进同一个 lib 目录。
5.2 现象:Could not find the Qt platform plugin "xcb"
现象:双击程序弹窗提示 qt.qpa.plugin: Could not find the Qt platform plugin "xcb",程序无法创建窗口。
原因:platforms/libqxcb.so 没有收进 AppDir,或者 qt.conf 的 Plugins 路径指错。也可能是 libqxcb.so 收进去了,但它依赖的 libxcb-* 没齐全。
解决:检查 AppDir/usr/plugins/platforms/libqxcb.so 是否存在;在 AppDir/usr/bin/qt.conf 里写 Plugins = ../plugins 或 Prefix = .. 加 Plugins = plugins;用 ldd AppDir/usr/plugins/platforms/libqxcb.so | grep 'not found' 补依赖。最后用 QT_DEBUG_PLUGINS=1 确认加载路径。
5.3 现象:打包后体积正常,但启动报缺 so
现象:ldd 显示某个 libxcb-*.so 或 libfontconfig.so 为 not found,程序启动失败。
原因:只收了 Qt 库,没有收非 Qt 的系统依赖;或者 -bundle-non-qt-libs 没有加,工具跳过了这些库。
解决:重新执行 linuxdeployqt ... -bundle-non-qt-libs,把非 Qt 依赖收进 AppDir/usr/lib。收完再跑 ldd 全量检查,不要只 grep Qt。对于 libGL 这类与显卡驱动相关的库,不要盲目打包,优先依赖目标系统的驱动,否则容易出现渲染问题。
5.4 现象:换台机器后 desktop 图标或启动项失效
现象:程序能跑,但桌面图标不显示,或者从应用菜单启动时找不到可执行文件。
原因:desktop 文件里的 Exec 写了绝对路径,或者 Icon 名称与 icons 目录里的文件名不一致。
解决:Exec 只写可执行文件名,例如 Exec=myapp;图标文件按 myapp.png 或 myapp.svg 命名,放到 AppDir/usr/share/icons/hicolor/ 对应尺寸目录下。打包后检查 desktop 文件里没有 /home/... 这类路径。
5.5 现象:双击没反应,命令行能跑
现象:在文件管理器里双击可执行文件没反应,终端里 ./myapp 能启动。
原因:拷贝或压缩解压后执行位丢失,或者 desktop 文件没有执行权限。
解决:chmod +x AppDir/usr/bin/myapp,desktop 文件也补上执行位。分发压缩包时用 tar 保留权限,不要用某些会丢权限的打包方式。这个坑很低级,但血泪经验是每次发布前都跑一遍 test -x。
6. 发布前最后一道闸:脚本化自检与可回滚的打包习惯
手工检查容易漏,我习惯把关键检查写进脚本,每次打包后跑一遍:
bash复制#!/usr/bin/env bash
set -euo pipefail
APP_DIR="AppDir"
BIN="$APP_DIR/usr/bin/myapp"
# 1. 可执行位
test -x "$BIN" || { echo "缺少执行权限"; exit 1; }
# 2. 是否仍链接系统 Qt
if ldd "$BIN" | grep -q '/usr/lib.*Qt'; then
echo "仍在链接系统 Qt 库"
exit 1
fi
# 3. xcb 平台插件是否收进目录
test -f "$APP_DIR/usr/plugins/platforms/libqxcb.so" \
|| { echo "xcb 插件缺失"; exit 1; }
# 4. 未解析依赖
if ldd "$BIN" | grep -q 'not found'; then
echo "存在未解析依赖"
exit 1
fi
echo "自检通过"
脚本只做硬性拦截,不替代真实机器验证。发布前我还会按目录名带版本号保存上一版,比如 release-20240521,新版本启动异常时能直接回退,不用连夜重打。检查表里至少留三项:ldd 无系统 Qt、libqxcb.so 存在、干净目录能启动。从那以后我每次打包都强制走一遍这个脚本,宁可多花两分钟,也不把“本机能跑”当成“用户能用”。希望帮到你。
