简介围绕Ubuntu下使用linuxdeployqt打包Qt程序的全流程排障资料适合需要将Qt应用部署到未安装Qt环境的机器上的开发者。内容从配置Qt环境变量、在.bashrc中写入PATH、LD_LIBRARY_PATH、QT_PLUGIN_PATH等变量到编译linuxdeployqt源码并生成可执行程序均有说明同时针对高版本Ubuntu编译前需注释main.cpp中的系统版本检查、打包时出现patchelf未安装和libjasper.so.1缺失等典型错误给出了对应解决办法并延伸出通过ldd输出查找缺失库、再用apt补齐依赖的通用思路。文中以Qt5.9.2路径为示例提醒读者按实际安装环境调整落地性强此外对Qt插件、字体、图标、QML模块等非库依赖也有说明若自动处理仍有遗漏可手动补充缺失文件或配合其他部署方式。资源包共1个文件为PDF文档大小约58KB内容紧凑、便于查阅。已有2723人学习下载适合需要快速掌握Qt打包排错的开发者参考。1. Ubuntu 下用 linuxdeployqt 打包 Qt为什么本地能跑换台机器就崩在 Ubuntu 上把 Qt 程序交给别人最经典的一幕是自己机器上双击运行一切正常拷到同事电脑上要么提示libQt5Core.so.5: cannot open shared object file要么报could not load platform plugin xcb。linuxdeployqt 就是用来解决这类分发问题的它把可执行文件依赖的 Qt 库、插件和第三方 so 收集到一个 AppDir 里再打包成 AppImage。但这个工具在 Ubuntu 下并不是一条命令跑完就万事大吉坑集中在环境选择、xcb 依赖和 glibc 兼容性三处。这篇笔记按我实际打包的经验从原理讲到命令再列出 5 个高频报错帮你少走弯路。2. linuxdeployqt 打包原理与 Ubuntu 环境下的失败根源在动手敲命令以前建议你先花五分钟把 linuxdeployqt 的定位想清楚。它解决的是“Qt 程序跑在别人机器上”的问题而不是“程序能不能编译”的问题。很多人在 Ubuntu 上打包失败是把这一步和开发环境混在一起拿开发机的 Qt 安装路径、系统库路径直接喂给工具结果工具按照另一套假设去收集依赖最后出来的包自然就跑不起来。下面先讲清楚工具的工作方式再讲 Ubuntu 特有的三个坑。2.1 linuxdeployqt 到底在做什么ldd、patchelf、RPATH 与 AppDirlinuxdeployqt 表面上看是一条命令收尾实际内部是按固定流水线工作的。第一步是解析你传入的可执行文件用ldd读出它依赖的所有共享库第二步把 Qt 库和插件复制到 AppDir 的usr/lib、usr/plugins等目录第三步用patchelf修改可执行文件与这些 so 的 RPATH/RUNPATH让它们优先从$ORIGIN/../lib这类相对路径找库而不是继续去/opt/Qt里找最后生成一个名为 AppRun 的启动脚本并把整个 AppDir 用 mksquashfs 压成 AppImage。这四步里任何一步出问题表现都不一样。找不到 qmake 经常死在第一步之前因为工具需要先读 qmake 的安装前缀xcb 插件跑不起来往往死在第二步因为复制过程中漏掉了平台插件的系统依赖程序运行时还在找/opt/Qt的绝对路径则说明第三步 patchelf 没生效或生效之后又被覆盖了。理解这条流水线比背命令有用得多。还要记住一点linuxdeployqt 不是把所有东西都静态塞进包里。glibc、libstdc 这些最底层的运行库它默认不收集仍然依赖目标机器。所以它收集的是“Qt 相关的东西”而把系统的 glibc 当作既成事实。这就是为什么打包环境选得太新会让 AppImage 变成一个只能在“比你更新的系统”上跑的产物方向完全反了。打包完成后你会看到 AppDir 里多出这些目录usr/bin放主程序usr/lib放动态库usr/plugins放 Qt 平台插件和 imageformatsusr/qml放 QML 模块usr/share/applications放 .desktop 文件AppRun是入口脚本。如果你手动改过 AppRun一定要保证它设置了LD_LIBRARY_PATH和QT_QPA_PLATFORM_PLUGIN_PATH很多奇怪的问题其实出在这个文件被覆盖后漏了环境变量。2.2 Ubuntu 下打包翻车的三个根源Qt 路径、xcb 依赖、宿主系统太新第一个坑是 Qt 路径不统一。Ubuntu 上获取 Qt 的渠道很杂官网在线安装器装在/opt/Qtapt 装到/usr/lib/x86_64-linux-gnu/qt5还有人用命令行工具装到自定义目录。linuxdeployqt 需要借助 qmake 来获取 Qt 的库路径、插件路径和 QML 路径。如果你传入的 qmake 与实际编译用的不一致它复制出来的插件版本就可能和程序不匹配。我见过最隐蔽的例子程序是在 Qt 5.15.2 编译的但 linuxdeployqt 找到的是系统 Qt 5.12复制了 5.12 的libQt5Core.so.5程序一启动就报version Qt_5.15 not found。所以打包脚本里第一件事就是要固定 qmake 路径。第二个坑是 xcb 平台插件的系统依赖缺失。Qt 的 Linux 窗口系统插件libqxcb.so不是孤立的它链接了libxcb-icccm.so.4、libxcb-keysyms.so.1、libxcb-image.so.0、libxcb-randr.so.0、libxcb-render-util.so.0、libxcb-xkb.so.1、libxcb-xinerama.so.0以及libxkbcommon-x11.so.0等一串小库。Ubuntu 桌面版通常带全了但从 Docker 镜像、WSL 或精简云主机上打包时这些库很可能没装。linuxdeployqt 复制依赖时以宿主机现有的库为准主机没有它不会去外网取。结果就是 AppDir 里有了libqxcb.so但它在目标机器上缺少依赖运行时只能报could not load platform plugin xcb。第三个根源也是 Ubuntu 用户最容易忽略的是打包机 glibc 太新。linuxdeployqt 的理念是“基于低版本系统打包让产物兼容高版本系统”。低版本系统里链接出来的程序引用的 glibc 符号版本低到高版本机器上照跑反过来在 Ubuntu 22.04glibc 2.35上打包程序里就带着 2.34、2.35 的符号拿到 Ubuntu 18.04glibc 2.27上一跑直接报GLIBC_2.34 not found。很多人在新机器上打包反而翻车原因就在这。这不是 linuxdeployqt 的 bug而是它的设计边界它管 Qt不管 libc。2.3 选对工作环境Ubuntu 版本、Qt 版本与 glibc 兼容性所以我把打包环境当成一个固定工具链来维护而不是随手用当前开发机。最省事的方案是用 Docker 容器跑一个 Ubuntu 18.04在容器里装 Qt、linuxdeployqt 和所有 xcb 依赖库然后每次发布都在这个容器里执行打包脚本。这样 AppImage 的 glibc 基线是 2.27发给 Ubuntu 20.04、22.04、Debian 11/12 甚至 CentOS 8 基本都能跑。如果只在内部小范围分发用 20.04 或 22.04 也可以但你要在发布说明里写清楚“要求 glibc 2.x”别什么都不写。查看本机 glibc 版本很简单ldd --version | head -n1输出里GLIBC 2.31之类就是当前基线。另外Qt 版本不是越新越好linuxdeployqt 对 Qt 5.9 到 5.15 支持最成熟Qt 6 的插件路径和 QML 布局有变化如果你用 Qt 6先确认手里的 linuxdeployqt 版本有没有对应的适配否则可能复制完插件仍加载失败。我的建议能用 Qt 5.15.2 LTS 就先用这个组合这也是目前大量 Linux 桌面项目在用的搭配等打包链路完全摸透再往 Qt 6 迁也不迟。如果不想维护一套带图形界面的容器可以在容器里只做命令行打包。常见做法是把宿主机的 Qt 目录直接挂载进去docker run --rm -it \ -v /opt/Qt:/opt/Qt \ -v $(pwd):/src \ ubuntu:18.04 bash进入容器后先安装依赖再运行打包脚本。挂载进来的 Qt 基本可以跨版本移动但建议在容器里先用ldd /opt/Qt/5.15.2/gcc_64/bin/qmake检查一遍确认它没有依赖宿主机的特殊路径。环境准备好之后剩下的就是重复劳动。3. 搭建打包环境Qt、linuxdeployqt 与 Release 构建三步到位打包环境的搭建本质上是在固定“三样东西”Qt 工具链、linuxdeployqt 版本、系统基础库。三者一旦固定之后每次打包结果才有可比性。不要今天用 Qt 5.15明天换成 5.12也不要今天在 22.04 打包明天换到 20.04否则出了问题很难判断是代码回归还是环境漂移。这一章的三步做完你会得到一个可重复执行的打包基础。3.1 安装依赖与获取 linuxdeployqt先更新 apt 索引再装编译和运行阶段都会用到的包。下面这条命令在 Ubuntu 20.04/22.04 上通用Ubuntu 18.04 里包名也基本一致sudo apt update sudo apt install -y build-essential libgl1-mesa-dev \ libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 \ libxcb-image0 libxcb-randr0 libxcb-render-util0 \ libxcb-xkb1 libxkbcommon-x11-0 \ patchelf file fusebuild-essential提供 gcc/g 和 make编译 Qt 程序绕不开libgl1-mesa-dev是 OpenGL 相关的开发头文件Qt Widgets 里用到 OpenGL 或 QML 的软件渲染时需要。后面一串libxcb-*和libxkbcommon-x11-0是libqxcb.so的运行时依赖先装齐可以让 linuxdeployqt 在复制时直接收集到它们。patchelf是 linuxdeployqt 修改 RPATH 的底层工具file用于识别 AppImage 格式fuse是用来挂载 AppImage 的。Ubuntu 24.04 对 FUSE 的包改成了libfuse2t64如果fuse找不到就装这个名字。linuxdeployqt 本身不是 apt 包需要从它的 GitHub Releases 页面下载 AppImage。选择 x86_64 版本下载后先给执行权限再放到/usr/local/binchmod x linuxdeployqt-*.AppImage sudo mv linuxdeployqt-*.AppImage /usr/local/bin/linuxdeployqt如果你的环境没有 FUSE比如某些容器里直接运行 AppImage 会提示 fuse 权限问题。不用急AppImage 支持解压模式./linuxdeployqt-*.AppImage --appimage-extract sudo mv squashfs-root/usr/bin/linuxdeployqt /usr/local/bin/解压出来的二进制还能顺带把 linuxdeployqt 本身的 Qt 库留在 squashfs-root 里不影响使用。下载工具链这件事建议在打包机里固定一个版本不要每次用最新的因为新版本可能改插件复制行为造成“上周还能打这周突然缺模块”的玄学问题。全部装完后先跑一次linuxdeployqt --version能输出版本说明可执行文件没问题。如果提示缺少 Qt 库说明你下载的这个 AppImage 在解压后依赖了宿主系统的 Qt考虑换一个 AppImage 版本或手动把需要的 Qt 库放到/usr/local/lib下。这种问题在精简环境里不罕见别等打包报错时再回头看工具。3.2 编译一个 Release 版 Qt 程序qmake 命令行与 shadow build打包的第一个前提是手里有一份 Release 构建。如果用 Qt Creator 点过“运行”可执行文件在build-项目名-Desktop_Qt_5_15_2_...-Release/里但 Qt Creator 可能会为了调试给 Makefile 注入额外环境变量所以我更习惯用终端重新构建一遍确保产物干净。先设置 Qt 的 PATH 和库路径再建一个独立目录做 shadow buildexport QT_BIN/opt/Qt/5.15.2/gcc_64/bin export PATH$QT_BIN:$PATH export LD_LIBRARY_PATH/opt/Qt/5.15.2/gcc_64/lib:$LD_LIBRARY_PATH mkdir -p build-release cd build-release qmake ../myapp.pro -spec linux-g CONFIGrelease make -j$(nproc)qmake ../myapp.pro指定项目文件-spec linux-g告诉 qmake 使用 linux-g 这套 mkspec而不是交叉编译配置。CONFIGrelease强制切到 Release 模式如果 .pro 里写死了CONFIG debug这一行可能不起作用需要去 .pro 里改。make -j$(nproc)用本机所有核心并行编译第一次构建会慢一些。编译前先确认 qmake 是不是你期待的那一个qmake -v输出里应当显示/opt/Qt/5.15.2/gcc_64/bin/qmake和对应版本。如果你看到的是/usr/bin/qmake并且版本不对说明 PATH 没有生效检查export那行有没有写错。编译完成后用file确认可执行文件类型file build-release/myapp输出里应该能看到ELF 64-bit LSB executable, dynamically linked。如果出现statically linked反而要检查是不是链接了静态库后面 linuxdeployqt 会少复制很多东西。还要用ldd build-release/myapp | grep Qt看一下它链接的 Qt 库路径确保来自/opt/Qt/5.15.2/gcc_64/lib而不是/usr/lib/x86_64-linux-gnu。路径不对时回到环境变量检查 QT_BIN 是否真的生效。3.3 初始化 AppDir 结构和 .desktop 文件linuxdeployqt 的可执行文件参数可以指向任意路径但生成 AppImage 时要求文件位于 AppDir 的标准布局里。常见做法是提前把目录建好。主程序放usr/bin动态库由 linuxdeployqt 自动复制但目录先建好没坏处rm -rf appdir mkdir -p appdir/usr/bin mkdir -p appdir/usr/lib mkdir -p appdir/usr/share/applications mkdir -p appdir/usr/share/icons/hicolor/256x256/apps install -m 755 build-release/myapp appdir/usr/bin/myapp install -m 644 resources/myapp.desktop appdir/usr/share/applications/ install -m 644 resources/myapp.png appdir/usr/share/icons/hicolor/256x256/apps/用install而不是cp可以顺手把主程序权限设为 755。很多“AppImage 能解压但点开没反应”的案例就是主程序或者 AppRun 少了执行权限。.desktop 文件是 AppImage 的“证件”至少要包含这几项[Desktop Entry] TypeApplication NameMyApp CommentA cross-platform Qt application Execmyapp Iconmyapp CategoriesUtility; X-AppImage-Version1.0.0Exec只写可执行文件名不要写绝对路径或./AppRun 会在运行时把它拼到$APPDIR/usr/bin/下面。Icon对应图标文件名去掉.png后缀图标文件要放在usr/share/icons/hicolor/256x256/apps/myapp.png。如果图标尺寸不对或目录层级不对linuxdeployqt 会在生成时警告 icons not found但不会中止。到这一步打包环境、Release 程序和 AppDir 都准备好了下面才真正跟 linuxdeployqt 打交道。4. 开始打包AppDir 结构、xcb 依赖与 AppImage 生成这一章开始踩真正的油门。前面所有准备工作到这里都会反映成终端里的一行行日志。第一次跑命令时不要急着加-appimage先把依赖收集完整再合成镜像。4.1 第一次执行 linuxdeployqt命令与参数说明先不急着生成 AppImage第一遍执行只做依赖收集并把 AppDir 补全cd appdir linuxdeployqt usr/bin/myapp \ -qmake /opt/Qt/5.15.2/gcc_64/bin/qmake \ -verbose2这条命令没有-appimage它会把缺失的 Qt 库、插件和 AppRun 写进 appdir。-qmake参数让工具明确知道用哪套 Qt避免去 PATH 里乱猜。-verbose2会打印详细的复制列表和 ldd 结果是排查一切问题的基础开关。如果程序还依赖第三方非 Qt 库比如libcurl.so.4、libssl.so.3默认情况下 linuxdeployqt 不会把它们收进来需要追加一个参数linuxdeployqt usr/bin/myapp -qmake ... -bundle-non-qt-libs -verbose2-bundle-non-qt-libs会把可执行文件依赖里属于“非系统路径”的 so 一并复制到usr/lib。注意它不处理 glibc但对第三方商业库很有用。另一个常用参数是-no-strip默认工具会用 strip 给可执行文件和 so 去掉符号表以减小体积如果你想保留符号表方便日后分析崩溃就用-no-strip。第一遍执行完检查一下 appdir 里有没有多出usr/plugins/platforms/libqxcb.so、usr/plugins/xcbglintegrations这些目录。如果这些都没出现说明 qmake 路径给错了linuxdeployqt 压根没识别到 Qt。检查方法很简单看终端输出里有没有Creating basic AppDir structure和Copying AppRun。没有的话先确认 qmake 路径再重跑一次。4.2 处理 xcb 平台插件与补充依赖用 ldd 追到 missing 的库大多数情况下第一遍执行会在最后几行打印一长串依赖其中某些 so 会被标记为not found。这时先不要急着加-appimage先定位缺失项。定位入口是 Qt 自己的平台插件ldd /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so | grep not found这条命令会把libqxcb.so所有找不到的系统库列出来。常见的输出是libxcb-xinerama.so.0 not found、libxkbcommon-x11.so.0 not found这类。解决办法是回到第 3 章那一串 apt 包把缺的装上sudo apt install -y libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 \ libxcb-image0 libxcb-randr0 libxcb-render-util0 libxcb-xkb1 \ libxkbcommon-x11-0装完后再跑一次ldd确认没有 not found然后重新执行 linuxdeployqt。这里有个血泪经验即使宿主机装齐了这些库AppImage 在别人的精简机器上仍可能缺其中一两个。稳妥的做法是确认这些 xcb 库确实被复制进了appdir/usr/lib。如果没有可以用-extra-libs参数手动指定linuxdeployqt usr/bin/myapp -qmake ... -extra-libs/usr/lib/x86_64-linux-gnu/libxcb-xinerama.so.0-extra-libs可以重复传多个路径它会忽略白名单把指定 so 拉进来。但能不加就不加加得越多兼容性负担越重优先让宿主环境满足所有依赖再用 linuxdeployqt 自动收集。如果只是想验证程序在“没有 xcb 环境”下能不能启动可以用 Qt 的 offscreen 平台跑一次QT_QPA_PLATFORMoffscreen ./appdir/usr/bin/myapp这只能验证逻辑不能替代 xcb 的真实测试。GUI 程序最终还是要 xcb 跑起来才能确认界面和交互没问题所以这一条只当诊断手段。4.3 生成 AppImage二次执行 一个可复用的打包脚本依赖收集干净后再执行带-appimage的完整命令linuxdeployqt 会基于当前 AppDir 生成最终镜像linuxdeployqt usr/bin/myapp \ -qmake /opt/Qt/5.15.2/gcc_64/bin/qmake \ -appimage -verbose1输出文件一般以 .desktop 里的 Name 字段命名比如MyApp-x86_64.AppImage。如果刚才的 AppDir 里还有问题这一步会在生成前反复警告所以最好像我一样把整个流程写成脚本固定参数避免每次手敲漏了-bundle-non-qt-libs。下面是我常用的package.sh#!/bin/bash set -e APP_NAMEmyapp QT_BIN/opt/Qt/5.15.2/gcc_64/bin export PATH$QT_BIN:$PATH export LD_LIBRARY_PATH/opt/Qt/5.15.2/gcc_64/lib:$LD_LIBRARY_PATH rm -rf appdir mkdir -p appdir/usr/bin appdir/usr/lib mkdir -p appdir/usr/share/applications mkdir -p appdir/usr/share/icons/hicolor/256x256/apps install -m 755 build-release/$APP_NAME appdir/usr/bin/ install -m 644 resources/$APP_NAME.desktop appdir/usr/share/applications/ install -m 644 resources/$APP_NAME.png appdir/usr/share/icons/hicolor/256x256/apps/ linuxdeployqt appdir/usr/bin/$APP_NAME \ -qmake $QT_BIN/qmake \ -bundle-non-qt-libs \ -verbose2 linuxdeployqt appdir/usr/bin/$APP_NAME \ -qmake $QT_BIN/qmake \ -appimage -verbose1set -e让脚本在任意一条命令失败时立即退出避免在残破的 AppDir 上继续生成 AppImage。rm -rf appdir是每次打包的“后悔药”防止上一次残留的 so 干扰本次复制。第一遍命令和第二遍命令分开写可以在第一遍输出里及时发现 not found再让脚本走到第二遍如果第一次执行已经报错set -e会拦住整个脚本不会继续往下打包。这个脚本基本可以复制到任何 Qt 5.15 的 Ubuntu 打包环境里需要改的只有三个地方Qt 路径、项目路径、App 名称。5. 避坑指南linuxdeployqt 打包 Qt 的 5 个常见报错与排查方法打包最花时间的往往不是正常路径而是那些“换台机器就冒出来”的边界问题。这一章的 5 个坑基本覆盖了我见过的 Ubuntu 打包事故现场每条按“现象、原因、解决”的顺序写可以直接当排查手册用。5.1 报错 Could not find qmakePATH 与 -qmake 参数都没对上现象终端执行 linuxdeployqt 后几秒内退出输出ERROR: Could not find qmake。用which qmake一看指向/usr/bin/qmake版本却是系统自带的 Qt 5.12。原因linuxdeployqt 需要 qmake 来确定 Qt 安装路径。默认会在 PATH 里找而 Ubuntu 上用 apt 装的 Qt 会把自己的 qmake 优先放在 PATH。如果你手动编译的 Qt 5.15 没有加入 PATH工具找的就是另一个版本。解决把 Qt 的 bin 目录放在 PATH 最前面并在命令里显式传-qmake参数。注意用qmake -v验证输出最好精确到/opt/Qt/5.15.2/gcc_64/bin/qmake。在脚本里固定这一行不要依赖交互式 shell 的环境变量。还有一个细节sudo下执行 linuxdeployqt 时当前用户的 PATH 会被部分重置所以要么不用 sudo要么在 sudo 里加上env PATH$PATH。5.2 运行时提示 could not load platform plugin xcb不是 Qt 缺文件是系统缺 xcb现象AppImage 拷到另一台机器命令行启动后终端刷一行Failed to load platform plugin xcb就退出。打包机本地跑同一个 AppImage 却一切正常。原因最直接的原因是libqxcb.so被复制进来了但它依赖的libxcb-xinerama.so.0、libxkbcommon-x11.so.0等在目标机器上不存在或者 AppDir 里没有收集进去。另一个常见原因是 qt.conf 缺失导致 Qt 在 AppImage 解压后找不到 plugins 目录。解决先检查打包机的appdir/usr/plugins/platforms/下有没有libqxcb.so。有的话再对appdir/usr/plugins/platforms/libqxcb.so执行ldd把 not found 的库补进 AppDir。同时按 Qt 的 qt.conf 规则在appdir/usr/bin下放一个配置文件[Paths] Prefix .. Plugins plugins这个文件的作用是告诉 Qt可执行文件在usr/binQt 根目录往上一级到usr插件从usr/plugins加载。很多“打包了还是缺 xcb”的案例加了这个文件就正常了。注意目录名要和实际路径一致不要照抄网上五花八门的写法。5.3 QML 程序打包后界面空白或模块找不到需要 -qmldir现象用 QML 写的程序在开发机上正常打包成 AppImage 后能启动但窗口一片空白控制台输出类似module QtQuick.Controls is not installed。原因linuxdeployqt 对 C 链接的库收集比较积极但对 QML 模块的扫描是另一套机制。它不知道你的 .qml 文件里有import QtQuick.Controls 2.15自然也就不会把对应的 QML 目录复制进 AppDir。没有 QML 模块引擎只能白屏。解决执行时加-qmldir参数指定项目的 QML 源文件根目录linuxdeployqt appdir/usr/bin/myapp -qmake ... \ -qmldir../qml -appimage工具会扫描该目录里的 import 语句并把 Qt 对应的 qml 模块复制到appdir/usr/qml。这里有个点需要留意路径是项目源码里 qml 目录的位置不是编译产物的目录。如果你的 qml 文件分散在多个目录可以重复传-qmldir。QML 模块体积大是正常的QtQuick.Controls 整套下来可能多出几十 MB别用“程序没变大”来判断成功要以目标机器上的实际运行结果为准。注意-qmldir只扫描 import 语句不会扫描字符串拼接的动态加载路径。如果你的 QML 里有Qt.createComponent动态加载确保对应的 .qml 文件能被打包进去必要时手动复制到 AppDir 的相应目录。5.4 目标机器报 GLIBC_2.32 not found宿主系统太新linuxdeployqt 不管 glibc现象在 Ubuntu 22.04 上打包完AppImage 在 Ubuntu 18.04 或 CentOS 7 上运行提示/lib/x86_64-linux-gnu/libc.so.6: version GLIBC_2.32 not found。原因linuxdeployqt 不会打包 glibcAppImage 里的程序最终还是要找目标系统的libc.so.6。你的程序在 22.04 上编译时gcc 会引用更高级的 glibc 符号低版本 libc 里根本没有这些符号。解决把打包环境切到更低版本的 Ubuntu 上最直接的就是用 Docker 容器。在容器里安装同样的 Qt 和 linuxdeployqt执行同一套 package.sh产物基线立刻降下来。如果不想用容器至少保证打包机 glibc 不高于目标机的最低版本。还有一种情况代码里调用了新内核的接口即使 glibc 满足也可能遇到系统调用缺失这种问题与打包工具无关要考虑降低代码对系统特性的依赖。注意不要以为在 AppImage 里放一个高版本libc.so.6就能解决那会破坏整个系统的运行机制不是打包工具该干的事。5.5 程序启动还在找 /opt/Qt 绝对路径patchelf 没生效或 RPATH 被覆盖现象打包完把 AppImage 解压或直接运行程序报找不到/opt/Qt/5.15.2/gcc_64/lib/libQt5Widgets.so.5用ldd appdir/usr/bin/myapp看仍然有/opt/Qt/...的记录。原因linuxdeployqt 会用 patchelf 改写 RPATH但如果程序在编译时使用了-Wl,-rpath且链接的是绝对路径某些版本 patchelf 没处理干净或者你后来用install重新覆盖了可执行文件导致 RPATH 被还原。另一个可能linuxdeployqt 复制 so 到usr/lib后so 自身还保留了绝对 RPATH程序加载了它你就会在 ldd 里看到绝对路径。解决用 readelf 检查实际生效的 RUNPATHreadelf -d appdir/usr/bin/myapp | grep -i runpath如果出现/opt/Qt/...手动用 patchelf 修正patchelf --set-rpath $ORIGIN/../lib appdir/usr/bin/myapp然后再跑一次 linuxdeployqt。这里特别提醒$ORIGIN在 shell 里会被展开所以要么用单引号要么转义成\$ORIGIN。对appdir/usr/lib下的每个.so也可以批量执行但一般只要主程序的 RPATH 对了Qt 库自己的相对路径不会错。别在 patchelf 之前运行strip有些符号信息被扒掉后 patchelf 可能找不到 section 头反而改不动。6. 打完成包怎么验ldd 检查、容器测试和版本管理技巧打包完成不代表分发结束。最后这章讲两个我常用的验证和存档技巧能帮你省下不少售后时间。6.1 用 Docker 干净环境验证可移植性打包完成后我会把 AppImage 丢到一个干净的 Ubuntu 容器里跑一遍确认它不是“只在打包机才能启动的花瓶”。容器里通常没有 FUSE所以先解压再执行docker run --rm -v $(pwd)/MyApp-x86_64.AppImage:/tmp/app.AppImage ubuntu:18.04 bash -c \ cd /tmp ./app.AppImage --appimage-extract /dev/null ./squashfs-root/AppRun --version如果程序支持--version或--help这一步能验证动态库加载是否完整。没有图形界面时可以用QT_QPA_PLATFORMoffscreen跑一段自检逻辑。这样验证过的包基本可以放心外发。我的硬性要求是在打包机和目标机器的环境基线差异上至少做一次容器测试基线差一代以上必须换更低版本的容器重新打包。6.2 给打包脚本留一个“后悔药”版本号与归档习惯每次发版我会把 Qt 版本、Ubuntu 基础镜像、linuxdeployqt 版本、源码 commit 写在一个build-info.txt里随 AppImage 一起归档。这样用户两周后报一个诡异的 xcb 问题时我能立刻知道这包是用什么环境打出来的。脚本里固定APP_VERSION变量输出带版本号的文件名也是一种成本很低的防呆措施。早年被用户追着报 GLIBC 错误的经历让我学乖了打包不是把文件跑起来就完事而是要能把“为什么能跑”讲清楚。linuxdeployqt 的边界、宿主系统的影响、QML 和 xcb 的参数都值得在发布前花十分钟验证一遍。希望帮到你。本文还有配套的精品资源点击获取 Ubuntu下linuxdeployqt打包Qt：解决xcb与glibc兼容问题
简介围绕Ubuntu下使用linuxdeployqt打包Qt程序的全流程排障资料适合需要将Qt应用部署到未安装Qt环境的机器上的开发者。内容从配置Qt环境变量、在.bashrc中写入PATH、LD_LIBRARY_PATH、QT_PLUGIN_PATH等变量到编译linuxdeployqt源码并生成可执行程序均有说明同时针对高版本Ubuntu编译前需注释main.cpp中的系统版本检查、打包时出现patchelf未安装和libjasper.so.1缺失等典型错误给出了对应解决办法并延伸出通过ldd输出查找缺失库、再用apt补齐依赖的通用思路。文中以Qt5.9.2路径为示例提醒读者按实际安装环境调整落地性强此外对Qt插件、字体、图标、QML模块等非库依赖也有说明若自动处理仍有遗漏可手动补充缺失文件或配合其他部署方式。资源包共1个文件为PDF文档大小约58KB内容紧凑、便于查阅。已有2723人学习下载适合需要快速掌握Qt打包排错的开发者参考。1. Ubuntu 下用 linuxdeployqt 打包 Qt为什么本地能跑换台机器就崩在 Ubuntu 上把 Qt 程序交给别人最经典的一幕是自己机器上双击运行一切正常拷到同事电脑上要么提示libQt5Core.so.5: cannot open shared object file要么报could not load platform plugin xcb。linuxdeployqt 就是用来解决这类分发问题的它把可执行文件依赖的 Qt 库、插件和第三方 so 收集到一个 AppDir 里再打包成 AppImage。但这个工具在 Ubuntu 下并不是一条命令跑完就万事大吉坑集中在环境选择、xcb 依赖和 glibc 兼容性三处。这篇笔记按我实际打包的经验从原理讲到命令再列出 5 个高频报错帮你少走弯路。2. linuxdeployqt 打包原理与 Ubuntu 环境下的失败根源在动手敲命令以前建议你先花五分钟把 linuxdeployqt 的定位想清楚。它解决的是“Qt 程序跑在别人机器上”的问题而不是“程序能不能编译”的问题。很多人在 Ubuntu 上打包失败是把这一步和开发环境混在一起拿开发机的 Qt 安装路径、系统库路径直接喂给工具结果工具按照另一套假设去收集依赖最后出来的包自然就跑不起来。下面先讲清楚工具的工作方式再讲 Ubuntu 特有的三个坑。2.1 linuxdeployqt 到底在做什么ldd、patchelf、RPATH 与 AppDirlinuxdeployqt 表面上看是一条命令收尾实际内部是按固定流水线工作的。第一步是解析你传入的可执行文件用ldd读出它依赖的所有共享库第二步把 Qt 库和插件复制到 AppDir 的usr/lib、usr/plugins等目录第三步用patchelf修改可执行文件与这些 so 的 RPATH/RUNPATH让它们优先从$ORIGIN/../lib这类相对路径找库而不是继续去/opt/Qt里找最后生成一个名为 AppRun 的启动脚本并把整个 AppDir 用 mksquashfs 压成 AppImage。这四步里任何一步出问题表现都不一样。找不到 qmake 经常死在第一步之前因为工具需要先读 qmake 的安装前缀xcb 插件跑不起来往往死在第二步因为复制过程中漏掉了平台插件的系统依赖程序运行时还在找/opt/Qt的绝对路径则说明第三步 patchelf 没生效或生效之后又被覆盖了。理解这条流水线比背命令有用得多。还要记住一点linuxdeployqt 不是把所有东西都静态塞进包里。glibc、libstdc 这些最底层的运行库它默认不收集仍然依赖目标机器。所以它收集的是“Qt 相关的东西”而把系统的 glibc 当作既成事实。这就是为什么打包环境选得太新会让 AppImage 变成一个只能在“比你更新的系统”上跑的产物方向完全反了。打包完成后你会看到 AppDir 里多出这些目录usr/bin放主程序usr/lib放动态库usr/plugins放 Qt 平台插件和 imageformatsusr/qml放 QML 模块usr/share/applications放 .desktop 文件AppRun是入口脚本。如果你手动改过 AppRun一定要保证它设置了LD_LIBRARY_PATH和QT_QPA_PLATFORM_PLUGIN_PATH很多奇怪的问题其实出在这个文件被覆盖后漏了环境变量。2.2 Ubuntu 下打包翻车的三个根源Qt 路径、xcb 依赖、宿主系统太新第一个坑是 Qt 路径不统一。Ubuntu 上获取 Qt 的渠道很杂官网在线安装器装在/opt/Qtapt 装到/usr/lib/x86_64-linux-gnu/qt5还有人用命令行工具装到自定义目录。linuxdeployqt 需要借助 qmake 来获取 Qt 的库路径、插件路径和 QML 路径。如果你传入的 qmake 与实际编译用的不一致它复制出来的插件版本就可能和程序不匹配。我见过最隐蔽的例子程序是在 Qt 5.15.2 编译的但 linuxdeployqt 找到的是系统 Qt 5.12复制了 5.12 的libQt5Core.so.5程序一启动就报version Qt_5.15 not found。所以打包脚本里第一件事就是要固定 qmake 路径。第二个坑是 xcb 平台插件的系统依赖缺失。Qt 的 Linux 窗口系统插件libqxcb.so不是孤立的它链接了libxcb-icccm.so.4、libxcb-keysyms.so.1、libxcb-image.so.0、libxcb-randr.so.0、libxcb-render-util.so.0、libxcb-xkb.so.1、libxcb-xinerama.so.0以及libxkbcommon-x11.so.0等一串小库。Ubuntu 桌面版通常带全了但从 Docker 镜像、WSL 或精简云主机上打包时这些库很可能没装。linuxdeployqt 复制依赖时以宿主机现有的库为准主机没有它不会去外网取。结果就是 AppDir 里有了libqxcb.so但它在目标机器上缺少依赖运行时只能报could not load platform plugin xcb。第三个根源也是 Ubuntu 用户最容易忽略的是打包机 glibc 太新。linuxdeployqt 的理念是“基于低版本系统打包让产物兼容高版本系统”。低版本系统里链接出来的程序引用的 glibc 符号版本低到高版本机器上照跑反过来在 Ubuntu 22.04glibc 2.35上打包程序里就带着 2.34、2.35 的符号拿到 Ubuntu 18.04glibc 2.27上一跑直接报GLIBC_2.34 not found。很多人在新机器上打包反而翻车原因就在这。这不是 linuxdeployqt 的 bug而是它的设计边界它管 Qt不管 libc。2.3 选对工作环境Ubuntu 版本、Qt 版本与 glibc 兼容性所以我把打包环境当成一个固定工具链来维护而不是随手用当前开发机。最省事的方案是用 Docker 容器跑一个 Ubuntu 18.04在容器里装 Qt、linuxdeployqt 和所有 xcb 依赖库然后每次发布都在这个容器里执行打包脚本。这样 AppImage 的 glibc 基线是 2.27发给 Ubuntu 20.04、22.04、Debian 11/12 甚至 CentOS 8 基本都能跑。如果只在内部小范围分发用 20.04 或 22.04 也可以但你要在发布说明里写清楚“要求 glibc 2.x”别什么都不写。查看本机 glibc 版本很简单ldd --version | head -n1输出里GLIBC 2.31之类就是当前基线。另外Qt 版本不是越新越好linuxdeployqt 对 Qt 5.9 到 5.15 支持最成熟Qt 6 的插件路径和 QML 布局有变化如果你用 Qt 6先确认手里的 linuxdeployqt 版本有没有对应的适配否则可能复制完插件仍加载失败。我的建议能用 Qt 5.15.2 LTS 就先用这个组合这也是目前大量 Linux 桌面项目在用的搭配等打包链路完全摸透再往 Qt 6 迁也不迟。如果不想维护一套带图形界面的容器可以在容器里只做命令行打包。常见做法是把宿主机的 Qt 目录直接挂载进去docker run --rm -it \ -v /opt/Qt:/opt/Qt \ -v $(pwd):/src \ ubuntu:18.04 bash进入容器后先安装依赖再运行打包脚本。挂载进来的 Qt 基本可以跨版本移动但建议在容器里先用ldd /opt/Qt/5.15.2/gcc_64/bin/qmake检查一遍确认它没有依赖宿主机的特殊路径。环境准备好之后剩下的就是重复劳动。3. 搭建打包环境Qt、linuxdeployqt 与 Release 构建三步到位打包环境的搭建本质上是在固定“三样东西”Qt 工具链、linuxdeployqt 版本、系统基础库。三者一旦固定之后每次打包结果才有可比性。不要今天用 Qt 5.15明天换成 5.12也不要今天在 22.04 打包明天换到 20.04否则出了问题很难判断是代码回归还是环境漂移。这一章的三步做完你会得到一个可重复执行的打包基础。3.1 安装依赖与获取 linuxdeployqt先更新 apt 索引再装编译和运行阶段都会用到的包。下面这条命令在 Ubuntu 20.04/22.04 上通用Ubuntu 18.04 里包名也基本一致sudo apt update sudo apt install -y build-essential libgl1-mesa-dev \ libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 \ libxcb-image0 libxcb-randr0 libxcb-render-util0 \ libxcb-xkb1 libxkbcommon-x11-0 \ patchelf file fusebuild-essential提供 gcc/g 和 make编译 Qt 程序绕不开libgl1-mesa-dev是 OpenGL 相关的开发头文件Qt Widgets 里用到 OpenGL 或 QML 的软件渲染时需要。后面一串libxcb-*和libxkbcommon-x11-0是libqxcb.so的运行时依赖先装齐可以让 linuxdeployqt 在复制时直接收集到它们。patchelf是 linuxdeployqt 修改 RPATH 的底层工具file用于识别 AppImage 格式fuse是用来挂载 AppImage 的。Ubuntu 24.04 对 FUSE 的包改成了libfuse2t64如果fuse找不到就装这个名字。linuxdeployqt 本身不是 apt 包需要从它的 GitHub Releases 页面下载 AppImage。选择 x86_64 版本下载后先给执行权限再放到/usr/local/binchmod x linuxdeployqt-*.AppImage sudo mv linuxdeployqt-*.AppImage /usr/local/bin/linuxdeployqt如果你的环境没有 FUSE比如某些容器里直接运行 AppImage 会提示 fuse 权限问题。不用急AppImage 支持解压模式./linuxdeployqt-*.AppImage --appimage-extract sudo mv squashfs-root/usr/bin/linuxdeployqt /usr/local/bin/解压出来的二进制还能顺带把 linuxdeployqt 本身的 Qt 库留在 squashfs-root 里不影响使用。下载工具链这件事建议在打包机里固定一个版本不要每次用最新的因为新版本可能改插件复制行为造成“上周还能打这周突然缺模块”的玄学问题。全部装完后先跑一次linuxdeployqt --version能输出版本说明可执行文件没问题。如果提示缺少 Qt 库说明你下载的这个 AppImage 在解压后依赖了宿主系统的 Qt考虑换一个 AppImage 版本或手动把需要的 Qt 库放到/usr/local/lib下。这种问题在精简环境里不罕见别等打包报错时再回头看工具。3.2 编译一个 Release 版 Qt 程序qmake 命令行与 shadow build打包的第一个前提是手里有一份 Release 构建。如果用 Qt Creator 点过“运行”可执行文件在build-项目名-Desktop_Qt_5_15_2_...-Release/里但 Qt Creator 可能会为了调试给 Makefile 注入额外环境变量所以我更习惯用终端重新构建一遍确保产物干净。先设置 Qt 的 PATH 和库路径再建一个独立目录做 shadow buildexport QT_BIN/opt/Qt/5.15.2/gcc_64/bin export PATH$QT_BIN:$PATH export LD_LIBRARY_PATH/opt/Qt/5.15.2/gcc_64/lib:$LD_LIBRARY_PATH mkdir -p build-release cd build-release qmake ../myapp.pro -spec linux-g CONFIGrelease make -j$(nproc)qmake ../myapp.pro指定项目文件-spec linux-g告诉 qmake 使用 linux-g 这套 mkspec而不是交叉编译配置。CONFIGrelease强制切到 Release 模式如果 .pro 里写死了CONFIG debug这一行可能不起作用需要去 .pro 里改。make -j$(nproc)用本机所有核心并行编译第一次构建会慢一些。编译前先确认 qmake 是不是你期待的那一个qmake -v输出里应当显示/opt/Qt/5.15.2/gcc_64/bin/qmake和对应版本。如果你看到的是/usr/bin/qmake并且版本不对说明 PATH 没有生效检查export那行有没有写错。编译完成后用file确认可执行文件类型file build-release/myapp输出里应该能看到ELF 64-bit LSB executable, dynamically linked。如果出现statically linked反而要检查是不是链接了静态库后面 linuxdeployqt 会少复制很多东西。还要用ldd build-release/myapp | grep Qt看一下它链接的 Qt 库路径确保来自/opt/Qt/5.15.2/gcc_64/lib而不是/usr/lib/x86_64-linux-gnu。路径不对时回到环境变量检查 QT_BIN 是否真的生效。3.3 初始化 AppDir 结构和 .desktop 文件linuxdeployqt 的可执行文件参数可以指向任意路径但生成 AppImage 时要求文件位于 AppDir 的标准布局里。常见做法是提前把目录建好。主程序放usr/bin动态库由 linuxdeployqt 自动复制但目录先建好没坏处rm -rf appdir mkdir -p appdir/usr/bin mkdir -p appdir/usr/lib mkdir -p appdir/usr/share/applications mkdir -p appdir/usr/share/icons/hicolor/256x256/apps install -m 755 build-release/myapp appdir/usr/bin/myapp install -m 644 resources/myapp.desktop appdir/usr/share/applications/ install -m 644 resources/myapp.png appdir/usr/share/icons/hicolor/256x256/apps/用install而不是cp可以顺手把主程序权限设为 755。很多“AppImage 能解压但点开没反应”的案例就是主程序或者 AppRun 少了执行权限。.desktop 文件是 AppImage 的“证件”至少要包含这几项[Desktop Entry] TypeApplication NameMyApp CommentA cross-platform Qt application Execmyapp Iconmyapp CategoriesUtility; X-AppImage-Version1.0.0Exec只写可执行文件名不要写绝对路径或./AppRun 会在运行时把它拼到$APPDIR/usr/bin/下面。Icon对应图标文件名去掉.png后缀图标文件要放在usr/share/icons/hicolor/256x256/apps/myapp.png。如果图标尺寸不对或目录层级不对linuxdeployqt 会在生成时警告 icons not found但不会中止。到这一步打包环境、Release 程序和 AppDir 都准备好了下面才真正跟 linuxdeployqt 打交道。4. 开始打包AppDir 结构、xcb 依赖与 AppImage 生成这一章开始踩真正的油门。前面所有准备工作到这里都会反映成终端里的一行行日志。第一次跑命令时不要急着加-appimage先把依赖收集完整再合成镜像。4.1 第一次执行 linuxdeployqt命令与参数说明先不急着生成 AppImage第一遍执行只做依赖收集并把 AppDir 补全cd appdir linuxdeployqt usr/bin/myapp \ -qmake /opt/Qt/5.15.2/gcc_64/bin/qmake \ -verbose2这条命令没有-appimage它会把缺失的 Qt 库、插件和 AppRun 写进 appdir。-qmake参数让工具明确知道用哪套 Qt避免去 PATH 里乱猜。-verbose2会打印详细的复制列表和 ldd 结果是排查一切问题的基础开关。如果程序还依赖第三方非 Qt 库比如libcurl.so.4、libssl.so.3默认情况下 linuxdeployqt 不会把它们收进来需要追加一个参数linuxdeployqt usr/bin/myapp -qmake ... -bundle-non-qt-libs -verbose2-bundle-non-qt-libs会把可执行文件依赖里属于“非系统路径”的 so 一并复制到usr/lib。注意它不处理 glibc但对第三方商业库很有用。另一个常用参数是-no-strip默认工具会用 strip 给可执行文件和 so 去掉符号表以减小体积如果你想保留符号表方便日后分析崩溃就用-no-strip。第一遍执行完检查一下 appdir 里有没有多出usr/plugins/platforms/libqxcb.so、usr/plugins/xcbglintegrations这些目录。如果这些都没出现说明 qmake 路径给错了linuxdeployqt 压根没识别到 Qt。检查方法很简单看终端输出里有没有Creating basic AppDir structure和Copying AppRun。没有的话先确认 qmake 路径再重跑一次。4.2 处理 xcb 平台插件与补充依赖用 ldd 追到 missing 的库大多数情况下第一遍执行会在最后几行打印一长串依赖其中某些 so 会被标记为not found。这时先不要急着加-appimage先定位缺失项。定位入口是 Qt 自己的平台插件ldd /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so | grep not found这条命令会把libqxcb.so所有找不到的系统库列出来。常见的输出是libxcb-xinerama.so.0 not found、libxkbcommon-x11.so.0 not found这类。解决办法是回到第 3 章那一串 apt 包把缺的装上sudo apt install -y libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 \ libxcb-image0 libxcb-randr0 libxcb-render-util0 libxcb-xkb1 \ libxkbcommon-x11-0装完后再跑一次ldd确认没有 not found然后重新执行 linuxdeployqt。这里有个血泪经验即使宿主机装齐了这些库AppImage 在别人的精简机器上仍可能缺其中一两个。稳妥的做法是确认这些 xcb 库确实被复制进了appdir/usr/lib。如果没有可以用-extra-libs参数手动指定linuxdeployqt usr/bin/myapp -qmake ... -extra-libs/usr/lib/x86_64-linux-gnu/libxcb-xinerama.so.0-extra-libs可以重复传多个路径它会忽略白名单把指定 so 拉进来。但能不加就不加加得越多兼容性负担越重优先让宿主环境满足所有依赖再用 linuxdeployqt 自动收集。如果只是想验证程序在“没有 xcb 环境”下能不能启动可以用 Qt 的 offscreen 平台跑一次QT_QPA_PLATFORMoffscreen ./appdir/usr/bin/myapp这只能验证逻辑不能替代 xcb 的真实测试。GUI 程序最终还是要 xcb 跑起来才能确认界面和交互没问题所以这一条只当诊断手段。4.3 生成 AppImage二次执行 一个可复用的打包脚本依赖收集干净后再执行带-appimage的完整命令linuxdeployqt 会基于当前 AppDir 生成最终镜像linuxdeployqt usr/bin/myapp \ -qmake /opt/Qt/5.15.2/gcc_64/bin/qmake \ -appimage -verbose1输出文件一般以 .desktop 里的 Name 字段命名比如MyApp-x86_64.AppImage。如果刚才的 AppDir 里还有问题这一步会在生成前反复警告所以最好像我一样把整个流程写成脚本固定参数避免每次手敲漏了-bundle-non-qt-libs。下面是我常用的package.sh#!/bin/bash set -e APP_NAMEmyapp QT_BIN/opt/Qt/5.15.2/gcc_64/bin export PATH$QT_BIN:$PATH export LD_LIBRARY_PATH/opt/Qt/5.15.2/gcc_64/lib:$LD_LIBRARY_PATH rm -rf appdir mkdir -p appdir/usr/bin appdir/usr/lib mkdir -p appdir/usr/share/applications mkdir -p appdir/usr/share/icons/hicolor/256x256/apps install -m 755 build-release/$APP_NAME appdir/usr/bin/ install -m 644 resources/$APP_NAME.desktop appdir/usr/share/applications/ install -m 644 resources/$APP_NAME.png appdir/usr/share/icons/hicolor/256x256/apps/ linuxdeployqt appdir/usr/bin/$APP_NAME \ -qmake $QT_BIN/qmake \ -bundle-non-qt-libs \ -verbose2 linuxdeployqt appdir/usr/bin/$APP_NAME \ -qmake $QT_BIN/qmake \ -appimage -verbose1set -e让脚本在任意一条命令失败时立即退出避免在残破的 AppDir 上继续生成 AppImage。rm -rf appdir是每次打包的“后悔药”防止上一次残留的 so 干扰本次复制。第一遍命令和第二遍命令分开写可以在第一遍输出里及时发现 not found再让脚本走到第二遍如果第一次执行已经报错set -e会拦住整个脚本不会继续往下打包。这个脚本基本可以复制到任何 Qt 5.15 的 Ubuntu 打包环境里需要改的只有三个地方Qt 路径、项目路径、App 名称。5. 避坑指南linuxdeployqt 打包 Qt 的 5 个常见报错与排查方法打包最花时间的往往不是正常路径而是那些“换台机器就冒出来”的边界问题。这一章的 5 个坑基本覆盖了我见过的 Ubuntu 打包事故现场每条按“现象、原因、解决”的顺序写可以直接当排查手册用。5.1 报错 Could not find qmakePATH 与 -qmake 参数都没对上现象终端执行 linuxdeployqt 后几秒内退出输出ERROR: Could not find qmake。用which qmake一看指向/usr/bin/qmake版本却是系统自带的 Qt 5.12。原因linuxdeployqt 需要 qmake 来确定 Qt 安装路径。默认会在 PATH 里找而 Ubuntu 上用 apt 装的 Qt 会把自己的 qmake 优先放在 PATH。如果你手动编译的 Qt 5.15 没有加入 PATH工具找的就是另一个版本。解决把 Qt 的 bin 目录放在 PATH 最前面并在命令里显式传-qmake参数。注意用qmake -v验证输出最好精确到/opt/Qt/5.15.2/gcc_64/bin/qmake。在脚本里固定这一行不要依赖交互式 shell 的环境变量。还有一个细节sudo下执行 linuxdeployqt 时当前用户的 PATH 会被部分重置所以要么不用 sudo要么在 sudo 里加上env PATH$PATH。5.2 运行时提示 could not load platform plugin xcb不是 Qt 缺文件是系统缺 xcb现象AppImage 拷到另一台机器命令行启动后终端刷一行Failed to load platform plugin xcb就退出。打包机本地跑同一个 AppImage 却一切正常。原因最直接的原因是libqxcb.so被复制进来了但它依赖的libxcb-xinerama.so.0、libxkbcommon-x11.so.0等在目标机器上不存在或者 AppDir 里没有收集进去。另一个常见原因是 qt.conf 缺失导致 Qt 在 AppImage 解压后找不到 plugins 目录。解决先检查打包机的appdir/usr/plugins/platforms/下有没有libqxcb.so。有的话再对appdir/usr/plugins/platforms/libqxcb.so执行ldd把 not found 的库补进 AppDir。同时按 Qt 的 qt.conf 规则在appdir/usr/bin下放一个配置文件[Paths] Prefix .. Plugins plugins这个文件的作用是告诉 Qt可执行文件在usr/binQt 根目录往上一级到usr插件从usr/plugins加载。很多“打包了还是缺 xcb”的案例加了这个文件就正常了。注意目录名要和实际路径一致不要照抄网上五花八门的写法。5.3 QML 程序打包后界面空白或模块找不到需要 -qmldir现象用 QML 写的程序在开发机上正常打包成 AppImage 后能启动但窗口一片空白控制台输出类似module QtQuick.Controls is not installed。原因linuxdeployqt 对 C 链接的库收集比较积极但对 QML 模块的扫描是另一套机制。它不知道你的 .qml 文件里有import QtQuick.Controls 2.15自然也就不会把对应的 QML 目录复制进 AppDir。没有 QML 模块引擎只能白屏。解决执行时加-qmldir参数指定项目的 QML 源文件根目录linuxdeployqt appdir/usr/bin/myapp -qmake ... \ -qmldir../qml -appimage工具会扫描该目录里的 import 语句并把 Qt 对应的 qml 模块复制到appdir/usr/qml。这里有个点需要留意路径是项目源码里 qml 目录的位置不是编译产物的目录。如果你的 qml 文件分散在多个目录可以重复传-qmldir。QML 模块体积大是正常的QtQuick.Controls 整套下来可能多出几十 MB别用“程序没变大”来判断成功要以目标机器上的实际运行结果为准。注意-qmldir只扫描 import 语句不会扫描字符串拼接的动态加载路径。如果你的 QML 里有Qt.createComponent动态加载确保对应的 .qml 文件能被打包进去必要时手动复制到 AppDir 的相应目录。5.4 目标机器报 GLIBC_2.32 not found宿主系统太新linuxdeployqt 不管 glibc现象在 Ubuntu 22.04 上打包完AppImage 在 Ubuntu 18.04 或 CentOS 7 上运行提示/lib/x86_64-linux-gnu/libc.so.6: version GLIBC_2.32 not found。原因linuxdeployqt 不会打包 glibcAppImage 里的程序最终还是要找目标系统的libc.so.6。你的程序在 22.04 上编译时gcc 会引用更高级的 glibc 符号低版本 libc 里根本没有这些符号。解决把打包环境切到更低版本的 Ubuntu 上最直接的就是用 Docker 容器。在容器里安装同样的 Qt 和 linuxdeployqt执行同一套 package.sh产物基线立刻降下来。如果不想用容器至少保证打包机 glibc 不高于目标机的最低版本。还有一种情况代码里调用了新内核的接口即使 glibc 满足也可能遇到系统调用缺失这种问题与打包工具无关要考虑降低代码对系统特性的依赖。注意不要以为在 AppImage 里放一个高版本libc.so.6就能解决那会破坏整个系统的运行机制不是打包工具该干的事。5.5 程序启动还在找 /opt/Qt 绝对路径patchelf 没生效或 RPATH 被覆盖现象打包完把 AppImage 解压或直接运行程序报找不到/opt/Qt/5.15.2/gcc_64/lib/libQt5Widgets.so.5用ldd appdir/usr/bin/myapp看仍然有/opt/Qt/...的记录。原因linuxdeployqt 会用 patchelf 改写 RPATH但如果程序在编译时使用了-Wl,-rpath且链接的是绝对路径某些版本 patchelf 没处理干净或者你后来用install重新覆盖了可执行文件导致 RPATH 被还原。另一个可能linuxdeployqt 复制 so 到usr/lib后so 自身还保留了绝对 RPATH程序加载了它你就会在 ldd 里看到绝对路径。解决用 readelf 检查实际生效的 RUNPATHreadelf -d appdir/usr/bin/myapp | grep -i runpath如果出现/opt/Qt/...手动用 patchelf 修正patchelf --set-rpath $ORIGIN/../lib appdir/usr/bin/myapp然后再跑一次 linuxdeployqt。这里特别提醒$ORIGIN在 shell 里会被展开所以要么用单引号要么转义成\$ORIGIN。对appdir/usr/lib下的每个.so也可以批量执行但一般只要主程序的 RPATH 对了Qt 库自己的相对路径不会错。别在 patchelf 之前运行strip有些符号信息被扒掉后 patchelf 可能找不到 section 头反而改不动。6. 打完成包怎么验ldd 检查、容器测试和版本管理技巧打包完成不代表分发结束。最后这章讲两个我常用的验证和存档技巧能帮你省下不少售后时间。6.1 用 Docker 干净环境验证可移植性打包完成后我会把 AppImage 丢到一个干净的 Ubuntu 容器里跑一遍确认它不是“只在打包机才能启动的花瓶”。容器里通常没有 FUSE所以先解压再执行docker run --rm -v $(pwd)/MyApp-x86_64.AppImage:/tmp/app.AppImage ubuntu:18.04 bash -c \ cd /tmp ./app.AppImage --appimage-extract /dev/null ./squashfs-root/AppRun --version如果程序支持--version或--help这一步能验证动态库加载是否完整。没有图形界面时可以用QT_QPA_PLATFORMoffscreen跑一段自检逻辑。这样验证过的包基本可以放心外发。我的硬性要求是在打包机和目标机器的环境基线差异上至少做一次容器测试基线差一代以上必须换更低版本的容器重新打包。6.2 给打包脚本留一个“后悔药”版本号与归档习惯每次发版我会把 Qt 版本、Ubuntu 基础镜像、linuxdeployqt 版本、源码 commit 写在一个build-info.txt里随 AppImage 一起归档。这样用户两周后报一个诡异的 xcb 问题时我能立刻知道这包是用什么环境打出来的。脚本里固定APP_VERSION变量输出带版本号的文件名也是一种成本很低的防呆措施。早年被用户追着报 GLIBC 错误的经历让我学乖了打包不是把文件跑起来就完事而是要能把“为什么能跑”讲清楚。linuxdeployqt 的边界、宿主系统的影响、QML 和 xcb 的参数都值得在发布前花十分钟验证一遍。希望帮到你。本文还有配套的精品资源点击获取 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
