根本原因是linuxdeployqt无法自动定位非标准路径的Qt安装目录，因其依赖qmake -query输出的QT_INSTALL_LIBS等变量，而该变量在多版本Qt共存、PATH混乱或自定义安装路径时易失效；解决需显式指定-qmake-path参数并确保AppDir结构规范。
linuxdeployqt 为什么找不到你的 Qt 库
根本原因通常是 linuxdeployqt 没法自动定位你实际使用的 Qt 安装路径，尤其当你用的是非系统包管理器安装的 Qt（比如 Qt Online Installer、源码编译或自定义前缀路径）。它默认只查 /usr/lib/x86_64-linux-gnu/qt5 或 /usr/local/Qt-5.15.2 这类常见位置，而你的 qmake 输出的 QT_INSTALL_LIBS 路径可能完全不在它的扫描列表里。
解决办法是显式告诉它 Qt 根目录：
- 先运行
qmake -query QT_INSTALL_PREFIX拿到你的 Qt 安装根路径（比如/opt/Qt/5.15.2/gcc_64） - 打包时加参数：
./linuxdeployqt AppName.AppDir/usr/share/applications/AppName.desktop -appimage -executable ./AppName.AppDir/usr/bin/yourapp -qmake-path /opt/Qt/5.15.2/gcc_64/bin/qmake - 注意：必须用
-qmake-path，不能只靠PATH环境变量；linuxdeployqt不读QTDIR或QMAKE
AppDir 结构不对会导致插件和资源丢失
linuxdeployqt 严格依赖标准的 AppDir 布局，不是随便把可执行文件扔进去就行。它只从固定子目录加载东西：插件走 usr/plugins/，翻译文件走 usr/translations/，图标走 usr/share/icons/，否则打包后运行时会报 Plugin not found 或 QIcon::fromTheme: no icon theme installed。
构建 AppDir 的推荐做法：
立即学习“C++免费学习笔记（深入）”；
Linux 安全审计工具，检查 SSH 配置、开放/监听端口、防火墙规则（ufw/iptables/nftables）、失败登录尝试、sudoers 权限...
- 用
linuxdeployqt自带的-bundle-non-qt-libs选项前，先确保你的可执行文件已用patchelf --set-rpath '$ORIGIN/../lib' yourapp设置好 rpath - 手动创建结构：
AppName.AppDir/usr/bin/放主程序，AppName.AppDir/usr/lib/放你自己的动态库（如果有），AppName.AppDir/usr/plugins/放platforms/libqxcb.so等 Qt 插件（可从你的 Qt 安装目录复制） - 桌面文件必须放在
AppName.AppDir/usr/share/applications/下，且Exec=字段要写成Exec=yourapp（不带路径），图标字段用Icon=yourapp，然后确保AppName.AppDir/usr/share/icons/hicolor/48x48/apps/yourapp.png存在
打包后运行报错 “Could not find Qt platform plugin xcb”
这是最常遇到的问题，本质是 libqxcb.so 没被正确复制进 AppDir，或者它依赖的系统库（如 libxcb-xinerama.so.0）缺失。不要指望 linuxdeployqt 自动扫出所有 xcb 相关插件——它只复制 platforms/ 下的 libqxcb.so，但不会递归处理它的 DT_NEEDED。
实操补救步骤：
- 先确认插件是否在
AppName.AppDir/usr/plugins/platforms/libqxcb.so，没有就手动复制：cp $QTDIR/plugins/platforms/libqxcb.so AppName.AppDir/usr/plugins/platforms/ - 用
ldd AppName.AppDir/usr/plugins/platforms/libqxcb.so | grep "not found"查缺哪些系统库 - 把缺失的库（如
libxcb-xinerama.so.0）从系统里复制进AppName.AppDir/usr/lib/，再用patchelf --set-rpath '$ORIGIN/../lib' AppName.AppDir/usr/plugins/platforms/libqxcb.so修正依赖路径 - 如果系统没装
libxcb-xinerama0，别急着apt install，而是直接下载对应 deb 包解压提取.so文件，避免污染目标环境
AppImage 启动黑屏或崩溃，但控制台无输出
这类问题往往源于 X11 环境变量未透传或 Qt 平台参数失效。AppImage 内部运行时默认不继承宿主的 DISPLAY 和 XAUTHORITY，而且 Qt 5.14+ 对 xcb 的 GL 上下文检查更严。
临时调试方法：
- 运行前加环境变量：
DISPLAY=:0 XAUTHORITY=$HOME/.Xauthority ./YourApp-x86_64.AppImage - 强制指定平台和渲染后端：
QT_QPA_PLATFORM=xcb QT_QPA_PLATFORMTHEME=kvantum ./YourApp-x86_64.AppImage（如果你用了 Kvantum 主题） - 如果仍黑屏，尝试禁用 OpenGL：
QT_QPA_PLATFORM=offscreen ./YourApp-x86_64.AppImage，看是否至少能输出日志 - 真正发布前，应该在干净的 Ubuntu/Fedora Live USB 环境中测试，而不是只在开发机上跑通就认为 OK
复杂点在于：同一个 AppImage 在不同发行版上行为可能完全不同，因为底层 libxcb 版本、Mesa 驱动、Wayland 适配程度都不同。不要跳过跨发行版验证这步，哪怕只是最小化测启动和主窗口显示。
