1. 为什么Qt程序在Ubuntu上“能跑”不等于“能发”？
刚把Qt写的图像处理小工具在自己机器上调试完，兴冲冲打包成AppImage发给同事，结果对方双击没反应，终端里一跑报错：“libQt5Core.so.5: cannot open shared object file”。这场景我见过太多次了——不是代码写错了，是发布环节漏掉了最基础却最容易被忽视的一环：依赖的完整搬运与路径的绝对可控。
很多人误以为“编译通过=发布完成”，尤其在Ubuntu这种桌面环境成熟的系统上。但Qt程序和Python脚本不同，它不是靠解释器动态加载模块，而是链接大量C++运行时库；Qt本身又分模块（Core、Gui、Widgets、Network……），每个模块还可能依赖系统级库（如libxcb、libxkbcommon）；更麻烦的是，Qt Creator默认用的是系统Qt，而用户机器上的Qt版本、甚至glibc版本都可能不同。你本地ldd ./myapp | grep Qt看到的路径，比如/usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5，在别人机器上根本不存在——那不是路径，那是你本地环境的“快照”，不是可移植的“快照”。
关键词里虽然没填，但这个标题天然锚定三个核心矛盾：跨机器兼容性、Qt模块依赖链的完整性、以及Linux下“无安装包”分发模式的落地成本。它不是教你怎么写Hello World，而是解决“写完之后，怎么让一个没装Qt开发环境、甚至没装Qt运行时的普通Ubuntu用户，点一下就打开你的程序”。这背后涉及动态链接器ldd的原理、patchelf的二进制重写能力、linuxdeployqt的自动化逻辑，以及AppImage这种格式为何成为事实标准——不是因为它技术最先进，而是它用最笨的办法（把所有东西塞进一个文件）绕过了Linux发行版碎片化的宿命。
我试过直接拷贝/usr/lib下的Qt库，结果发现光拷Qt还不够，还得找libxcb-xinerama.so.0、libxkbcommon-x11.so.0这些X11扩展库；也试过用apt install qt5-default让目标机装运行时，结果对方说“公司电脑不能随便装包”。最后才明白：发布不是复制粘贴，是构建一个自包含的、与宿主环境解耦的微型运行时沙盒。这个认知转变，花了我整整两个项目周期。
提示：别信“只要把可执行文件拷过去就行”的说法。Qt程序启动的第一步不是你的
main()，而是Qt自身的初始化，它要加载平台插件（platforms/libqxcb.so）、图像格式插件（imageformats/libqjpeg.so）、样式插件（styles/libqcleanlooksstyle.so）……缺任何一个，程序直接静默退出，连错误日志都不给你留。
2. 从零开始：手动剥离依赖的完整推演过程
自动化工具有时候像黑箱，出问题时你连该骂哪行代码都不知道。所以第一步，我坚持带大家手撸一遍——不是为了生产，而是为了建立肌肉记忆。假设你的可执行文件叫mytool，位于build/release/mytool，我们用最原始的方式把它变成可移植包。
2.1 第一步：揪出所有动态依赖
打开终端，进入build/release目录，执行：
ldd mytool | grep "=>"你会看到类似这样的输出：
libQt5Widgets.so.5 => /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5 (0x00007f8b1a2c3000) libQt5Gui.so.5 => /usr/lib/x86_64-linux-gnu/libQt5Gui.so.5 (0x00007f8b19c5a000) libQt5Core.so.5 => /usr/lib/x86_64-linux-gnu/libQt5Core.so.5 (0x00007f8b196b2000) libstdc++.so.6 => /usr/lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007f8b1932a000) libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007f8b19113000) libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f8b18d22000) libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007f8b18b03000) libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f8b188ff000) librt.so.1 => /lib/x86_64-linux-gnu/librt.so.1 (0x00007f8b186f7000) libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007f8b18359000) /lib64/ld-linux-x86-64.so.2 => /lib64/ld-linux-x86-64.so.2 (0x00007f8b1a8e5000)注意看箭头=>右边的路径——这些就是你的程序在当前机器上找到的库位置。其中/lib64/ld-linux-x86-64.so.2是动态链接器，必须保留；libc.so.6、libm.so.6等glibc基础库，Ubuntu主流版本基本兼容，可以不打包（但高版本glibc向下兼容，低版本不行，这点后面细说）；真正要打包的是Qt系列和libstdc++这类C++运行时。
2.2 第二步：创建可移植目录结构
我们不往系统目录塞东西，而是建一个完全独立的文件夹，模拟一个“便携式根目录”。执行：
mkdir -p mytool.AppDir/usr/bin mkdir -p mytool.AppDir/usr/lib mkdir -p mytool.AppDir/usr/plugins/platforms mkdir -p mytool.AppDir/usr/plugins/imageformats mkdir -p mytool.AppDir/usr/plugins/styles这个结构不是随意定的。AppDir是AppImage规范要求的顶层目录名；usr/bin放主程序；usr/lib放Qt库；usr/plugins/*放Qt插件——因为Qt在启动时会按固定路径查找插件，硬编码在Qt源码里，改不了。你不能把libqxcb.so扔到usr/lib下就完事，它必须在usr/plugins/platforms/里，否则Qt初始化失败。
2.3 第三步：精准拷贝Qt库与插件
Qt库的位置，取决于你用的Qt版本。如果是系统Qt（apt install qt5-default），通常在/usr/lib/x86_64-linux-gnu/；如果是自己编译的Qt或Qt官方在线安装包，则在~/Qt/5.15.2/gcc_64/这类路径。用find命令定位：
# 查找Qt5Widgets库（以它为入口，递归找依赖） find /usr/lib -name "libQt5Widgets.so.5*" 2>/dev/null # 查找平台插件（关键！） find /usr/lib -path "*/plugins/platforms/libqxcb.so" 2>/dev/null # 查找图像格式插件 find /usr/lib -path "*/plugins/imageformats/libqjpeg.so" 2>/dev/null找到后，拷贝：
cp /usr/lib/x86_64-linux-gnu/libQt5Widgets.so.5* mytool.AppDir/usr/lib/ cp /usr/lib/x86_64-linux-gnu/libQt5Gui.so.5* mytool.AppDir/usr/lib/ cp /usr/lib/x86_64-linux-gnu/libQt5Core.so.5* mytool.AppDir/usr/lib/ cp /usr/lib/x86_64-linux-gnu/libstdc++.so.6* mytool.AppDir/usr/lib/ # 拷贝插件（注意路径！） cp /usr/lib/x86_64-linux-gnu/qt5/plugins/platforms/libqxcb.so mytool.AppDir/usr/plugins/platforms/ cp /usr/lib/x86_64-linux-gnu/qt5/plugins/imageformats/libqjpeg.so mytool.AppDir/usr/plugins/imageformats/ cp /usr/lib/x86_64-linux-gnu/qt5/plugins/imageformats/libqsvg.so mytool.AppDir/usr/plugins/imageformats/ cp /usr/lib/x86_64-linux-gnu/qt5/plugins/styles/libqcleanlooksstyle.so mytool.AppDir/usr/plugins/styles/注意：
libqxcb.so依赖libxcb-xinerama.so.0、libxkbcommon-x11.so.0等X11扩展库，这些不在Qt目录下，而在/usr/lib/x86_64-linux-gnu/。用ldd检查它们：ldd mytool.AppDir/usr/plugins/platforms/libqxcb.so | grep "not found"如果有缺失，继续拷贝对应库到
mytool.AppDir/usr/lib/。这是手动打包最耗时的环节——你得像侦探一样，一层层追查依赖。
2.4 第四步：重写可执行文件的库搜索路径
现在mytool还在找/usr/lib/x86_64-linux-gnu/下的库，我们必须告诉它：“别找了，就在我家（mytool.AppDir/usr/lib）里找”。这需要patchelf工具：
sudo apt install patchelf patchelf --set-rpath '$ORIGIN/../usr/lib' mytool.AppDir/usr/bin/mytool$ORIGIN是动态链接器的特殊变量，代表可执行文件自身的目录。$ORIGIN/../usr/lib即mytool.AppDir/usr/bin/../usr/lib=mytool.AppDir/usr/lib。这行命令修改了mytool的DT_RPATH段，让它启动时优先搜索这个相对路径。
验证是否生效：
readelf -d mytool.AppDir/usr/bin/mytool | grep RPATH # 应该输出：0x000000000000001d (RPATH) Library rpath: [$ORIGIN/../usr/lib]2.5 第五步：编写启动脚本与AppRun
AppImage要求根目录下有一个叫AppRun的可执行脚本，它负责设置环境变量并启动主程序。创建mytool.AppDir/AppRun：
#!/bin/bash export APPDIR="$(cd "$(dirname "${0}")"; pwd)" export PATH="${APPDIR}/usr/bin:${PATH}" export LD_LIBRARY_PATH="${APPDIR}/usr/lib:${LD_LIBRARY_PATH}" export QT_PLUGIN_PATH="${APPDIR}/usr/plugins" export QML2_IMPORT_PATH="${APPDIR}/usr/qml" # 启动主程序，用exec确保PID不变，方便信号传递 exec "${APPDIR}/usr/bin/mytool" "$@"赋予执行权限：
chmod +x mytool.AppDir/AppRun同时，把你的可执行文件mytool拷进去：
cp build/release/mytool mytool.AppDir/usr/bin/2.6 第六步：生成AppImage并测试
最后一步，用appimagetool打包：
wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage chmod +x appimagetool-x86_64.AppImage ./appimagetool-x86_64.AppImage mytool.AppDir执行完，会生成mytool-*.AppImage文件。给它加执行权限，双击或命令行运行：
chmod +x mytool-*.AppImage ./mytool-*.AppImage如果一切顺利，你的程序应该正常启动。如果失败，别急着删重来，先看错误：
./mytool-*.AppImage --appimage-extract # 解包到squashfs-root目录 cd squashfs-root ./AppRun # 这样能直接看到终端错误输出这时候常见的错误是Could not load platform plugin "xcb"，说明libqxcb.so或其依赖没拷全；或者是QStandardPaths: XDG_RUNTIME_DIR not set，这是环境变量问题，不影响功能，可忽略。
实操心得：手动打包最大的价值不是最终产物，而是让你彻底理解Qt程序启动的每一步。我曾经在一个客户现场，对方机器上
libxcb-xinerama.so.0版本太老，导致libqxcb.so加载失败。手动打包时，我直接替换了这个库，问题当场解决。而用自动化工具，你可能连报错在哪一层都找不到。
3. linuxdeployqt：自动化打包的边界与陷阱
手动流程走通后，下一步必然是拥抱自动化。linuxdeployqt是目前最成熟、社区支持最好的Qt专用打包工具，但它绝不是“一键傻瓜”，用不好反而比手动更坑。
3.1 安装与基础用法
linuxdeployqt没有.deb包，官方只提供单个二进制文件。下载地址在GitHub Releases页（搜索linuxdeployqt），选最新版linuxdeployqt-continuous-x86_64.AppImage。下载后：
chmod +x linuxdeployqt-continuous-x86_64.AppImage基础命令很简单：
./linuxdeployqt-continuous-x86_64.AppImage \ build/release/mytool.desktop \ -appimage \ -executable build/release/mytool \ -bundle-non-qt-libs注意几个关键参数：
mytool.desktop：这是Linux桌面系统的应用描述文件，没有它，linuxdeployqt不会生成AppImage。内容示例：[Desktop Entry] Name=MyTool Exec=mytool Icon=mytool Type=Application Categories=Utility;-appimage：生成AppImage格式。-executable：指定主程序路径。-bundle-non-qt-libs：把非Qt的第三方库（如OpenCV、FFmpeg）也打包进来。这个选项默认不开启，如果你的程序用了这些库，必须显式加上，否则运行时报cannot open shared object file。
3.2 它到底帮你做了什么？——拆解自动化逻辑
运行linuxdeployqt时，它内部执行了和我们手动流程几乎一致的步骤，只是更快、更全：
- 解析
.desktop文件：提取Exec=和Icon=字段，确定主程序名和图标路径。 - 扫描主程序依赖：调用
ldd，识别所有libQt*.so和libstdc++.so等。 - 定位Qt安装目录：通过
qmake -query QT_INSTALL_LIBS或环境变量QTDIR，找到Qt的lib/和plugins/目录。 - 拷贝Qt库与插件：把
libQt5*.so、libstdc++.so、libgcc_s.so拷到AppDir/usr/lib/；把platforms/、imageformats/、styles/等插件拷到对应AppDir/usr/plugins/子目录。 - 重写RPATH：对主程序和所有拷贝进来的
.so文件，批量执行patchelf --set-rpath，指向$ORIGIN/../usr/lib。 - 生成
AppRun脚本：内置模板，自动设置LD_LIBRARY_PATH、QT_PLUGIN_PATH等。 - 打包成AppImage：调用
appimagetool。
看起来很完美？问题出在第3步和第4步。
3.3 最常见的三个“自动”陷阱
陷阱一：Qt安装路径识别错误
linuxdeployqt依赖qmake来查询Qt路径。如果你的系统里有多个Qt版本（比如系统Qt + Qt官方安装包 + 自编译Qt），qmake命令可能指向错误的版本。执行：
which qmake qmake -v qmake -query QT_INSTALL_LIBS如果QT_INSTALL_LIBS指向/usr/lib/x86_64-linux-gnu/，但你的程序是用~/Qt/5.15.2/gcc_64/编译的，那么linuxdeployqt会去系统目录找库，结果打包进去的全是旧版Qt，运行时崩溃。
解决方案：强制指定Qt路径：
QTDIR=~/Qt/5.15.2/gcc_64 ./linuxdeployqt-... \ build/release/mytool.desktop \ -appimage \ -executable build/release/mytool \ -bundle-non-qt-libs陷阱二：插件拷贝不全，尤其是platforms/libqxcb.so
linuxdeployqt默认只拷platforms/下的libqxcb.so，但它依赖的libxcb-*系列库（libxcb-xinerama.so.0,libxcb-xkb.so.1,libxkbcommon-x11.so.0）可能没被识别为“必须”，导致打包遗漏。现象是AppImage在某些Ubuntu版本（尤其是22.04+）上启动白屏或闪退。
解决方案：手动补全。打包后，进入生成的AppDir，用ldd检查：
ldd AppDir/usr/plugins/platforms/libqxcb.so | grep "not found"如果发现缺失，手动拷贝对应库到AppDir/usr/lib/，再重新打包。
陷阱三：-bundle-non-qt-libs的“非Qt”定义模糊
这个参数只打包ldd输出中“不是Qt库”的.so，但有些库（如libpng16.so.16）既是系统库又是Qt依赖，linuxdeployqt可能认为它是“系统库”而不打包，结果你的程序用QImage::save("xxx.png")时崩溃。
解决方案：宁可多打，不可少打。用--executable参数显式指定所有你用到的第三方库：
./linuxdeployqt ... \ -executable build/release/mytool \ -executable /usr/lib/x86_64-linux-gnu/libpng16.so.16 \ -executable /usr/lib/x86_64-linux-gnu/libjpeg.so.8实操心得：我有个项目用了OpenCV的
cv::imread，linuxdeployqt没打包libopencv_imgcodecs.so.4.5，因为它的名字里没Qt。结果AppImage在客户机器上打开图片直接Segmentation Fault。后来我把整个/usr/lib/x86_64-linux-gnu/libopencv_*.so*都加到-executable列表里，问题解决。记住：自动化工具的“智能”是基于规则的，而你的需求是具体的，规则覆盖不到的地方，就得人工兜底。
4. 高阶实战：解决glibc版本冲突与跨Ubuntu版本兼容
前面所有操作，都默认目标机和你的编译机是同一Ubuntu版本（比如都是20.04）。但现实是，你用22.04打包，客户用18.04运行，或者反过来。这时最大的拦路虎不是Qt，而是glibc。
4.1 glibc兼容性原理：为什么高版本能跑低版本，反之不行？
glibc是Linux的C标准库实现，它提供printf、malloc、open等基础函数。新版本glibc（如2.35 in Ubuntu 22.04）会添加新函数、新符号，但保证旧符号向后兼容。所以：
- 用
glibc 2.35编译的程序，在glibc 2.35或更高版本（如2.39）的机器上能跑； - 但用
glibc 2.35编译的程序，在glibc 2.27（Ubuntu 18.04）上会报错：version GLIBC_2.34 not found。
原因：你的程序在链接时，记录了它需要的glibc符号版本。ldd -v ./mytool会显示每个库依赖的GLIBC_2.x版本号。
4.2 方案一：降级编译环境——最稳妥
终极方案，是在最低目标版本的系统上编译和打包。例如，你要支持Ubuntu 18.04（glibc 2.27）及以上，那就用18.04的Docker镜像：
docker run -it --rm -v $(pwd):/workspace ubuntu:18.04 # 在容器内：apt update && apt install qt5-default build-essential # cd /workspace && mkdir build && cd build && cmake .. && make # 然后用linuxdeployqt打包这样生成的二进制，glibc依赖只会到2.27，在20.04、22.04上都能跑。缺点是开发环境割裂，每次打包都要进容器。
4.3 方案二：静态链接glibc？不，用musl——但Qt不支持
理论上，用musl libc可以生成完全静态的二进制，摆脱glibc依赖。但Qt官方不支持musl，编译会失败。社区有qtbase-musl补丁，但维护不稳定，不推荐生产使用。
4.4 方案三：动态链接器劫持——patchelf的高级用法
这是折中方案：不降级编译环境，但强制让程序链接到更低版本的glibc符号。原理是修改二进制的DT_NEEDED段，替换libc.so.6的版本需求。
步骤（需谨慎，可能破坏程序）：
- 先用
readelf -d mytool | grep NEEDED查看当前依赖的libc版本。 - 下载目标最低版本的
libc.so.6（如Ubuntu 18.04的/lib/x86_64-linux-gnu/libc-2.27.so），放到mytool.AppDir/usr/lib/。 - 用
patchelf修改主程序的NEEDED条目：patchelf --replace-needed libc.so.6 libc-2.27.so mytool.AppDir/usr/bin/mytool - 同时，把
libc-2.27.so重命名为libc.so.6，放在mytool.AppDir/usr/lib/。
注意：这招风险极高。
libc-2.27.so里没有GLIBC_2.34的符号，如果你的程序或Qt库调用了这些新符号，运行时直接undefined symbol。只适用于纯C++逻辑简单、没用新API的程序。我只在紧急救火时用过一次，不建议作为常规方案。
4.5 方案四：AppImage + runtime bundle——官方推荐方案
AppImage官方提供了一个runtime文件，它是一个预编译的、兼容性极广的glibc和基础库集合。linuxdeployqt支持指定runtime：
wget https://github.com/AppImage/AppImageKit/releases/download/continuous/runtime-x86_64 mv runtime-x86_64 mytool.AppDir/AppRun然后打包时加参数：
./linuxdeployqt ... -appimage -executable build/release/mytool -extra-plugins platforms/libqxcb.so -runtime-file mytool.AppDir/AppRun这个runtime文件是用CentOS 6编译的，glibc版本极低（2.12），能在几乎所有现代Linux发行版上运行。但代价是体积增大约20MB，且启动稍慢（因为要解压runtime）。
实操心得：我在交付一个面向高校实验室的工具时，客户机器从Ubuntu 16.04到22.04都有。我最终选择了方案一（Docker 18.04编译）+ 方案四（AppImage runtime）。先用18.04编译保证
glibc底线，再用runtime兜底极端情况。打包脚本里写了清晰注释：“此AppImage最低支持Ubuntu 16.04，经20.04/22.04实测通过”。客户反馈零兼容性问题。
5. 发布前的终极 checklist 与避坑清单
打包不是终点，发布前的验证才是成败关键。以下是我踩过坑、改过bug、被客户电话轰炸后总结的 checklist，每一条都对应一个真实翻车现场。
5.1 功能性验证：不只是“能启动”
| 检查项 | 验证方法 | 常见翻车点 | 我的解决方案 |
|---|---|---|---|
| 平台插件加载 | 运行./mytool.AppImage --platform minimal，看是否能启动最小窗口 | libqxcb.so依赖的libxkbcommon-x11.so.0缺失，导致白屏 | 打包后ldd AppDir/usr/plugins/platforms/libqxcb.so | grep "not found"，补全缺失库 |
| 图像格式支持 | 尝试打开.jpg、.png、.svg文件 | libqjpeg.so、libqsvg.so没打包，或QT_PLUGIN_PATH没设对 | 在AppRun脚本里加echo $QT_PLUGIN_PATH，确认路径正确；用ls AppDir/usr/plugins/imageformats/看文件是否存在 |
| 字体渲染 | 输入中文、日文，看是否方块或乱码 | 缺少fontconfig、freetype库，或Qt没加载字体插件 | linuxdeployqt加-fonts参数；手动打包时拷/usr/lib/x86_64-linux-gnu/libfreetype.so.6和libfontconfig.so.1 |
| 网络请求 | 调用QNetworkAccessManager访问HTTPS网址 | 缺少libssl.so.1.1、libcrypto.so.1.1，或Qt的tls插件没打包 | linuxdeployqt加-always-overwrite和-verbose=2看日志；手动拷/usr/lib/x86_64-linux-gnu/libssl.so.1.1及AppDir/usr/plugins/tls/下对应插件 |
| 系统托盘 | 点击任务栏图标，看是否弹出菜单 | libdbus-1.so.3缺失，或QSystemTrayIcon初始化失败 | ldd mytool | grep dbus，拷libdbus-1.so.3到usr/lib/ |
5.2 环境兼容性验证：不止一台机器
不要只在自己的Ubuntu 22.04上测试！必须覆盖：
- 最低目标版本：如Ubuntu 18.04（glibc 2.27），验证基础功能。
- 最高常见版本：如Ubuntu 24.04（beta），验证新API兼容性。
- 最小化安装：用
ubuntu-server镜像装一个纯命令行系统，sudo apt install xorg openbox，再运行AppImage，验证是否依赖GNOME/KDE特定组件。 - Wayland会话：Ubuntu 22.04默认Wayland，
libqxcb.so可能不工作，需测试-platform wayland参数。
验证脚本示例（保存为test.sh）：
#!/bin/bash # 测试基础启动 if ! timeout 10s ./mytool-*.AppImage --appimage-extract; then echo "ERROR: AppImage extract failed" exit 1 fi # 测试插件路径 if [ ! -f squashfs-root/usr/plugins/platforms/libqxcb.so ]; then echo "ERROR: libqxcb.so not found in plugins" exit 1 fi # 测试glibc版本（需提前知道目标最低版本） if ldd ./mytool-*.AppImage 2>&1 | grep -q "GLIBC_2.34"; then echo "WARNING: glibc 2.34 dependency detected, may not run on Ubuntu 18.04" fi5.3 用户体验优化：让客户第一眼就信任你
技术搞定，用户体验决定口碑。几个细节：
- 图标：
mytool.desktop里的Icon=mytool，要求mytool.AppDir/usr/share/icons/hicolor/256x256/apps/mytool.png存在，且尺寸规范。我用GIMP导出256x256 PNG，比用Inkscape生成的SVG更稳定。 - 桌面菜单：
mytool.desktop的Categories=字段要准确，Utility;Graphics;比Utility;更容易被用户在“图形”分类里找到。 - 更新机制：AppImage本身不支持增量更新。我在程序里加了“检查更新”按钮，后台下载新AppImage，用
cp new.AppImage old.AppImage && chmod +x old.AppImage原子替换，用户重启即生效。 - 错误反馈：当
AppRun启动失败时，不静默退出。我在AppRun末尾加：if [ $? -ne 0 ]; then zenity --error --text="程序启动失败，请检查系统是否安装X11服务。" 2>/dev/null || echo "Error: Failed to start" fi
最后分享一个血泪教训：某次发布前，我忘了在
mytool.desktop里加Terminal=false，结果双击AppImage，先弹出一个黑终端窗口，几秒后才出现GUI主窗口。客户以为程序卡死了，反复双击，开了七八个终端。后来我把Terminal=false加粗写在打包文档首页，并在CI脚本里加了检查：grep -q "Terminal=false" mytool.desktop || exit 1。细节，真的决定成败。
我在实际使用中发现，最省心的发布流程是：Docker 18.04 编译 → linuxdeployqt 打包（加 -fonts -always-overwrite -verbose=2）→ 手动检查 squashfs-root 目录结构 → 运行 test.sh 脚本 → 最后用 appimagetool 生成最终文件。这套组合拳下来，至今没收到过一例“打不开”的客户反馈。
