简介这份PDF文档面向在Ubuntu环境下开发Qt程序、需要将程序打包部署到无Qt环境机器的开发者重点解决使用linuxdeployqt工具打包时遇到的各类问题。内容涵盖Qt环境变量配置、linuxdeployqt源码编译、程序打包流程以及patchelf缺失、libjasper.so.1找不到等典型报错的排查与修复思路适合具备一定Linux与Qt基础的读者参考。资源包内仅含1个PDF文件大小约58KB篇幅精炼便于快速查阅关键配置与命令。目前已有2723人学习下载说明该问题在Qt跨平台部署中较为普遍。读者可从中获得环境变量设置模板、源码编译注意事项、依赖库缺失的定位方法以及借助ldd输出排查库依赖的通用思路帮助减少打包过程中的试错成本。1. 为什么在 Ubuntu 上打包 Qt 程序linuxdeployqt 总在最后一步翻车如果你在 Ubuntu 上写 Qt迟早会撞上同一个场景程序在自己机器上跑得好好的拷到同事或客户的机器上就报error while loading shared libraries: libQt5Core.so.5: cannot open shared object file。这不是代码问题是动态库依赖没跟着走。linuxdeployqt 就是干这件事的——把 Qt 程序依赖的库、插件、QML 模块一股脑塞进 AppDir最后产出一个能双击运行的 AppImage。它解决的是「我编译出来的二进制怎么在没装 Qt 的 Ubuntu 上跑起来」这个最实际的诉求。适合谁适合用 qmake 或 CMake 构建、准备把桌面工具交付出去、又不想让用户手动装一堆依赖的 Qt 开发者。但它的坑也集中Qt 版本混装、qmake 路径不对、插件扫描不全随便一个都能让你卡半天。2. 先把 linuxdeployqt 的依赖解析逻辑摸清楚2.1 它到底做了什么从 ldd 到 AppDir 的搬运过程linuxdeployqt 的核心不是编译是「扫描 拷贝 打补丁」。你给它一个可执行文件它先用ldd递归解析出所有动态库依赖然后按规则筛选出哪些属于 Qt、哪些属于系统基础库glibc、libstdc 这类默认不打包再把 Qt 相关的库复制进 AppDir 的usr/lib目录。接着它会扫描 Qt 插件目录把 platforms、imageformats、sqldrivers 这些按需拷进去最后改写可执行文件的 RPATH让程序运行时优先从 AppDir 内部找库。理解这条链路很关键因为后面所有报错基本都能对应到某一环ldd解析失败 → 库找不到插件没拷 → 运行时报could not find the Qt platform pluginRPATH 没改对 → 还是去系统路径找库。我一般会先手动跑一遍ldd ./myapp | grep Qt看看依赖长什么样心里有底再交给 linuxdeployqt。2.2 环境准备qmake、Qt 版本和 linuxdeployqt 三者的对齐最常见的翻车根源是 Qt 版本混装。你系统里可能同时有 apt 装的 Qt5、官网 installer 装的 Qt5.15、还有 Qt6qmake -v指向的和你编译时用的不是同一个。linuxdeployqt 会调用qmake来定位 Qt 安装路径所以 qmake 必须指向你实际编译用的那套 Qt。# 确认当前 qmake 指向哪套 Qt which qmake qmake -v # 输出示例QMake version 3.1 / Using Qt version 5.15.2 in /opt/Qt/5.15.2/gcc_64/lib # 如果不是你要的那套临时用绝对路径或改 PATH export PATH/opt/Qt/5.15.2/gcc_64/bin:$PATH qmake -v参数说明which qmake看的是 PATH 里第一个 qmakeqmake -v里的Using Qt version ... in ...才是真正决定 linuxdeployqt 行为的路径。如果你用 CMake 构建编译时用的CMAKE_PREFIX_PATH也要和这个 qmake 指向同一套 Qt否则会出现「编译用 5.15、打包用 5.12」的错位运行时报cannot mix incompatible Qt library。下载 linuxdeployqt 本身常见做法是去它的 GitHub Releases 拿编译好的 AppImage 版本赋予执行权限后直接用# 假设下载到当前目录 chmod x linuxdeployqt-continuous-x86_64.AppImage # 验证能跑 ./linuxdeployqt-continuous-x86_64.AppImage --version注意linuxdeployqt 官方推荐用 AppImage 形式分发不要试图从源码编译除非你有特殊需求否则依赖链会让你怀疑人生。2.3 最小可复现打包流程从编译到 AppImage先准备一个干净的构建目录用 release 模式编译避免把 debug 符号和 debug 版 Qt 库带进去。# 1. 编译以 qmake 为例 mkdir build cd build qmake ../myapp.pro CONFIGrelease make -j$(nproc) # 2. 确认产物 ls -lh myapp ldd myapp | grep -i qt | head编译完成后把可执行文件单独拷到一个干净的 AppDir 结构里这是 linuxdeployqt 要求的输入形态# 3. 建立 AppDir 骨架 mkdir -p /tmp/MyApp.AppDir/usr/bin cp myapp /tmp/MyApp.AppDir/usr/bin/ # 4. 准备一个 desktop 文件AppImage 需要 cat /tmp/MyApp.AppDir/myapp.desktop EOF [Desktop Entry] TypeApplication NameMyApp Execmyapp Iconmyapp CategoriesUtility; EOF # 5. 准备图标没有会警告但不致命 cp ../myapp.png /tmp/MyApp.AppDir/myapp.png然后调用 linuxdeployqt关键是-appimage参数让它直接产出 AppImage# 6. 执行打包 ./linuxdeployqt-continuous-x86_64.AppImage \ /tmp/MyApp.AppDir/usr/bin/myapp \ -appimage \ -verbose2 \ -qmake/opt/Qt/5.15.2/gcc_64/bin/qmake参数说明第一个位置参数是 AppDir 内的可执行文件路径不是 AppDir 本身-appimage触发 AppImage 生成-verbose2输出详细日志排错必开-qmake显式指定 qmake避免它自己找错。执行完你会看到MyApp-x86_64.AppImage出现在当前目录chmod x后直接运行测试。2.4 验证打包结果别只看能不能跑打包成功不等于交付成功。我习惯做三层验证第一层在打包机上直接跑 AppImage确认基本功能第二层用ldd检查 AppImage 解压后的库是否都指向内部路径第三层找一个没装 Qt 的干净 Ubuntu 环境虚拟机或容器实测。# 解压 AppImage 看内部结构 ./MyApp-x86_64.AppImage --appimage-extract ls squashfs-root/usr/lib/ | grep -i qt # 检查可执行文件的 RPATH readelf -d squashfs-root/usr/bin/myapp | grep -i rpath如果 RPATH 里出现$ORIGIN/../lib这类相对路径说明改写成功如果还是指向/opt/Qt/...绝对路径那换台机器必挂。这一步是很多人忽略的后悔药等交付后才发现就晚了。3. 插件、QML 和第三方库那些默认扫不到的依赖3.1 Qt 插件扫描机制与 platforms 插件缺失linuxdeployqt 默认会扫描 Qt 安装目录下的plugins文件夹但它的扫描是有条件的——只拷贝它认为「被用到」的插件。问题在于它判断「被用到」靠的是可执行文件的导入符号而 platforms 插件比如libqxcb.so是通过运行时字符串加载的静态分析扫不到。结果就是程序能打包但一运行就报qt.qpa.plugin: Could not find the Qt platform plugin xcb。解决办法是显式告诉它要带哪些插件。常见做法是在 desktop 文件同级放一个qt.conf或者直接用-extra-plugins参数./linuxdeployqt-continuous-x86_64.AppImage \ /tmp/MyApp.AppDir/usr/bin/myapp \ -appimage \ -extra-pluginsplatforms/libqxcb.so,imageformats/libqjpeg.so,iconengines/libqsvgicon.so \ -qmake/opt/Qt/5.15.2/gcc_64/bin/qmake参数说明-extra-plugins接受逗号分隔的相对路径相对于 Qt 的plugins目录。platforms 里的libqxcb.so是 X11 环境必须的如果你还要支持 Wayland得把libqwayland-*.so也带上。imageformats 按你实际用到的图片格式加别一股脑全塞AppImage 体积会失控。3.2 QML 模块的依赖收集qmlimportscanner 的角色纯 Widgets 程序相对简单一旦用了 QML依赖就变成「QML 模块 对应的 C 插件 qmldir 文件」三层结构。linuxdeployqt 内部会调用qmlimportscanner去解析 QML 文件的 import 语句但前提是它能找到你的 QML 源码目录。如果你只把编译后的可执行文件丢进 AppDirQML 源码不在旁边扫描就会漏。我一般会在打包前把 QML 源文件目录也拷进 AppDir 的对应位置或者用-qmldir显式指定./linuxdeployqt-continuous-x86_64.AppImage \ /tmp/MyApp.AppDir/usr/bin/myapp \ -appimage \ -qmldir/path/to/your/qml/sources \ -qmake/opt/Qt/5.15.2/gcc_64/bin/qmake参数说明-qmldir指向包含main.qml等入口文件的目录qmlimportscanner 会从这里递归解析所有 import。如果用了自定义 QML 模块带qmldir文件的确保这些模块目录也在扫描路径下否则运行时会报module MyModule is not installed。3.3 第三方动态库与系统库的取舍边界不是所有.so都该打包。glibc、libstdc、libGL 这些系统基础库打包进去反而容易在新旧系统间产生冲突——你在 Ubuntu 22.04 上打包的 glibc拿到 20.04 上跑可能直接段错误。linuxdeployqt 默认会排除一批系统库但它的排除列表不一定覆盖你项目里引入的所有第三方库。判断标准很简单这个库是不是目标系统默认就有如果是比如libpng、libz可以不打包依赖目标系统如果是你项目特有的比如某个自编译的算法库必须打包。可以用-exclude-libs手动排除也可以用-no-translations等开关精简体积。# 查看 AppDir 里最终带了哪些库人工过一遍 find /tmp/MyApp.AppDir/usr/lib -name *.so* | sort这一步别偷懒我见过有人把libc.so.6都打进去了结果 AppImage 在部分机器上直接起不来。血泪经验系统库能不碰就不碰。4. 避坑与排查linuxdeployqt 最常见的五类翻车4.1 报错 cannot mix incompatible Qt library现象运行打包后的程序终端输出fatal: cannot mix incompatible Qt library (version 0x50601) with this library (version 0x50a00)。原因AppDir 里混进了两个不同版本的 Qt 库。通常是编译时用了一套 Qtlinuxdeployqt 打包时又通过 qmake 找到了另一套把两套库都拷了进去。解决先qmake -v确认版本再用-qmake显式指定和编译时一致的 qmake。打包后find AppDir -name libQt5Core.so*检查是否只有一个版本。如果有多个删掉 AppDir 重新打包别试图手动删库容易漏。4.2 运行时报 could not find the Qt platform plugin xcb现象AppImage 双击没反应命令行运行报qt.qpa.plugin: Could not find the Qt platform plugin xcb in 。原因platforms 插件没被打包进去或者打包了但路径不对程序找不到。解决用-extra-pluginsplatforms/libqxcb.so显式带上。打包后检查AppDir/usr/plugins/platforms/libqxcb.so是否存在。如果存在还报错检查qt.conf里的 Plugins 路径配置确保指向usr/plugins。4.3 AppImage 体积异常膨胀到几百 MB现象一个简单工具打包出来 300MB。原因debug 版 Qt 库、多余的插件、翻译文件、QML 模块全被塞进去了。解决编译时确保CONFIGrelease打包时加-no-translations去掉翻译用-extra-plugins精确控制插件而不是全量扫描。打包后用du -sh AppDir/usr/lib/*看哪个库占大头针对性排除。4.4 在打包机能跑换台机器就报库找不到现象本机测试正常拷到另一台 Ubuntu 上运行报error while loading shared libraries。原因RPATH 没改对程序还在找系统路径或绝对路径的库。解决readelf -d AppDir/usr/bin/myapp | grep RPATH检查正常应该是$ORIGIN/../lib。如果不是说明 linuxdeployqt 的 RPATH 改写没生效常见于可执行文件本身带了-Wl,-rpath硬编码。重新编译时去掉硬编码 rpath或者用patchelf手动改。4.5 qmake 找不到或指向错误路径现象linuxdeployqt 报qmake: could not find a Qt installation或打包出来的库版本不对。原因PATH 里没有 qmake或者有多个 qmake 但指向了系统 apt 装的那套。解决export PATH/opt/Qt/5.15.2/gcc_64/bin:$PATH把正确的 Qt bin 放最前或者每次都用-qmake绝对路径。我习惯在打包脚本里写死-qmake不依赖环境变量省得换终端就翻车。5. 进阶用脚本固化打包流程让每次交付都可复现手动敲命令打包第一次能成第三次就忘了参数。我的做法是写一个build_appimage.sh把编译、清理、打包、验证串起来每次交付走同一个脚本出问题也好回溯。#!/bin/bash set -e # 任何一步失败就停别带着错误往下走 QT_DIR/opt/Qt/5.15.2/gcc_64 APP_NAMEMyApp BUILD_DIR$(pwd)/build APPDIR/tmp/${APP_NAME}.AppDir LDQ$(pwd)/linuxdeployqt-continuous-x86_64.AppImage # 1. 清理旧产物 rm -rf $BUILD_DIR $APPDIR mkdir -p $BUILD_DIR $APPDIR/usr/bin # 2. 编译 cd $BUILD_DIR $QT_DIR/bin/qmake ../${APP_NAME}.pro CONFIGrelease make -j$(nproc) # 3. 组装 AppDir cp $APP_NAME $APPDIR/usr/bin/ cp ../${APP_NAME}.desktop $APPDIR/ cp ../${APP_NAME}.png $APPDIR/ # 4. 打包 $LDQ $APPDIR/usr/bin/$APP_NAME \ -appimage \ -verbose2 \ -qmake$QT_DIR/bin/qmake \ -extra-pluginsplatforms/libqxcb.so,imageformats/libqjpeg.so \ -no-translations # 5. 验证 RPATH echo RPATH check readelf -d $APPDIR/usr/bin/$APP_NAME | grep -i rpath || echo WARN: no RPATH found # 6. 验证 Qt 库版本唯一性 echo Qt lib versions find $APPDIR -name libQt5Core.so* -exec ls -l {} \; echo Done: $(ls ${APP_NAME}-x86_64.AppImage)这个脚本里几个关键点值得说set -e保证编译失败不会继续打包出半成品-no-translations砍掉用不上的翻译文件打包后立刻做 RPATH 和 Qt 库版本检查把问题拦在交付前。参数方面QT_DIR和-qmake必须指向同一套 Qt这是整个流程的锚点改一处就要改另一处。验证方法上除了脚本里的检查我还会在 Docker 里跑一个干净的 Ubuntu 镜像做最终测试docker run --rm -v $(pwd):/app ubuntu:22.04 /app/MyApp-x86_64.AppImage --version如果容器里能正常输出版本号说明依赖打包是完整的。这一步能抓到 90% 的「本机能跑、别人不能跑」问题。从那以后我每次打包 Qt 程序都强制先跑一遍qmake -v和ldd | grep Qt确认版本对齐再动手省下的排错时间比打包本身多得多。希望帮到你。本文还有配套的精品资源点击获取