1.

为什么选择AppImage：一个开发者的打包故事

如果你在Linux上开发过Qt程序，肯定经历过发布时的“依赖地狱”。

我记得几年前，我写了一个小工具，在自己电脑上跑得好好的，发给朋友用，他那边直接报错，说缺这个库、少那个插件。

折腾了半天，最后我几乎是把整个Qt安装。

这对于我们开发者来说，简直是分发利器，尤其是对于那些不想折腾复杂安装过程的普通用户。

在Linux世界里，分发软件的方式有很多，比如各个发行版自己的包管理器（deb、rpm），或者Flatpak、Snap这类沙盒化的格式。

但AppImage有它独特的魅力：极致的简单。

它不依赖包管理系统，不需要运行时环境，就是一个文件。

用户拿到手，chmod

+x一下，双击运行，完事。

这种体验，对于从Windows或macOS转过来的用户来说，非常友好。

而linuxdeployqt，就是专门为Qt程序打造的制作AppImage的神器。

它背后的原理，其实就是分析你的可执行文件，找出它运行时需要的所有Qt库、插件、翻译文件、图标字体等等，然后把它们统统复制到一个特定的“压”成一个独立的可执行文件。

所以，今天这篇指南，我就来手把手带你走一遍在Ubuntu下，用linuxdeployqt把Qt程序变成AppImage的完整流程。

我会把我踩过的坑、总结的技巧都分享出来，目标是让你看完就能动手，一次打包成功。

无论你是刚接触Linux桌面开发的新手，还是被传统打包方式折磨过的老鸟，这篇文章都能给你一个清晰、可靠的实践路径。

2.

打包前的准备工作：打好地基

在开始挥舞linuxdeployqt这个“打包魔法棒”之前，我们得先把准备工作做扎实。

这就像盖房子，地基不稳，后面怎么装修都白搭。

准备工作主要分三块：系统环境、Qt环境和工具安装。

2.1

系统与Qt环境确认

首先，确保你有一个干净的、用于打包的Qt开发环境。

我强烈建议，打包用的Qt版本最好和开发时用的版本完全一致，这样可以避免很多因版本差异导致的诡异问题。

怎么确认呢？打开终端，输入qmake

-v。

你会看到类似下面的输出：

QMake
version
/opt/Qt/5.15.2/gcc_64/lib

这里关键看两处：一是Qt版本号（例如5.15.2），二是Qt的安装路径（例如/opt/Qt/5.15.2/gcc_64）。

请记下这个路径，后面配置环境变量会用到。

如果你的系统里有多个Qt版本，这个命令显示的可能不是你想要的。

你可以通过设置PATH环境变量来指定，比如export

PATH=/opt/Qt/5.15.2/gcc_64/bin:$PATH，然后再运行qmake

-v确认。

接下来，把你的Qt程序编译成Release版本。

在Qt

Creator里，把构建套件切换到Release，然后点构建。

这里有个小建议：勾选“Shadow

build”（影子构建）。

这样会把构建产生的文件（比如.o,

.moc）放到一个独立的，非常清爽。

构建完成后，找到生成的可执行文件。

它通常位于类似build-项目名-Desktop_Qt_5_15_2_GCC_64bit-Release这样的，执行以下命令：

#
赋予执行权限
改个简短的名字（可选，但方便）
linuxdeployqt
/usr/local/bin/

完成后，在终端输入linuxdeployqt

--version，如果能看到版本信息输出，比如linuxdeployqt

(commit

xxxxxx)，那就说明安装成功了。

这里有个坑我踩过：有些比较新的Ubuntu系统（比如20.04、22.04）自带的glibc版本比较高，而linuxdeployqt为了确保生成的AppImage能在更多老系统上运行，会对宿主机的glibc版本做检查。

如果报错说“The

host

new”，你可以选择从源码编译一个去除了版本检查的linuxdeployqt，或者在一个老一点的系统（比如Ubuntu

18.04）上进行打包。

对于大多数情况，直接下载的版本都是可用的。

2.3

配置必要的环境变量

为了让linuxdeployqt在扫描依赖时能找到正确的Qt库和插件，我们需要确保一些关键的环境变量设置正确。

最稳妥的方法，是在打包前，在当前终端会话中临时设置它们。

你可以把下面这几行命令保存成一个脚本，比如setup_env.sh，每次打包前source一下。

#!/bin/bash
QT_DIR=/opt/Qt/5.15.2/gcc_64
export
LD_LIBRARY_PATH=$QT_DIR/lib:$LD_LIBRARY_PATH
export
QT_PLUGIN_PATH=$QT_DIR/plugins:$QT_PLUGIN_PATH
export
QML2_IMPORT_PATH=$QT_DIR/qml:$QML2_IMPORT_PATH

LD_LIBRARY_PATH告诉系统去哪里找动态库，QT_PLUGIN_PATH告诉Qt去哪里找平台插件（比如platforms/libqxcb.so，没有这个你的图形界面程序可能起不来），QML2_IMPORT_PATH则是给QML程序用的。

设置好后，你可以用echo

$LD_LIBRARY_PATH来检查是否生效。

3.

核心打包流程：从程序到AppImage

环境准备好了，程序也编译好了，现在进入最激动人心的环节：打包。

这个过程其实不复杂，但每一步的细节决定了最终产出的AppImage是否完美。

3.1

创建打包，（AppDir）结构也清晰。

#
创建一个
/path/to/your/build-release/your_app
.

现在，你的MyApp的路径最好不要包含中文或特殊字符，避免一些不必要的编码问题。

3.2

执行linuxdeployqt命令

在MyApp下的lib、plugins、translations等子（现在它已经是一个标准的AppDir了）打包成Your_App-x86_64.AppImage这样的文件。

第一次运行可能会比较慢，因为它需要下载一些必要的工具（比如appimagetool）。

过程中会输出很多信息，别被吓到，只要最后没有红色的ERROR导致中断，一般就成功了。

你可能会看到很多WARNING，比如某些库没找到，这通常是因为那些库是系统基础库，linuxdeployqt认为目标系统会自带，所以不打包进去，这是正常的。

3.3

完善桌面集成（.desktop文件）

打包完成后，你会发现下。

然后这里就填your_app。

修改后的.desktop文件示例：

[Desktop
Entry]
Categories=Utility;

改好后，强烈建议把这个文件重命名，比如改成my_calculator.desktop，这样更规范。

然后，你需要重新运行一次linuxdeployqt，但这次以.desktop文件作为输入，并加上-qmake参数来确保使用正确的Qt实例（如果你有多个Qt安装的话）：

linuxdeployqt
-qmake=/opt/Qt/5.15.2/gcc_64/bin/qmake
-appimage

这次运行会更快，它会根据.desktop文件里的信息，更新AppDir里的元数据，并重新生成AppImage。

现在，你的AppImage在用户双击时，就会在系统菜单里显示正确的名字和图标了。

4.

进阶技巧与疑难杂症排查

基本的打包流程走通了，但要想做出一个真正健壮、能在各种环境下运行的AppImage，我们还得掌握一些进阶技巧，并知道如何解决常见问题。

4.1

处理非Qt库和特殊资源

你的程序可能依赖一些非Qt的第三方库，比如OpenCV、FFmpeg或者某些自定义的.so文件。

默认情况下，linuxdeployqt可能不会自动打包它们。

这时候就需要用到-bundle-non-qt-libs这个参数。

linuxdeployqt
your_app.desktop
-appimage

这个参数会指示工具尝试找出并打包所有非Qt的核心库。

但注意，它仍然会排除一些非常基础的系统库（比如libc,libpthread）。

如果还有漏网之鱼，你就需要手动处理了。

手动处理的方法是把缺失的库文件复制到AppDir下的lib文件夹里，并确保其符号链接正确。

你可以通过在一个干净的测试系统（比如虚拟机）里运行打包好的AppImage，用ldd命令检查缺失的库来定位问题。

另外，如果你的程序使用了图片、音频、配置文件等资源文件，它们默认也不会被打包进去。

你需要手动将这些资源文件复制到AppDir里一个合适的位置，比如创建一个resources文件夹放进去。

然后在你的代码中，访问这些资源的路径也要相应调整，可以使用相对路径（比如./resources/icon.png）或者通过QCoreApplication::applicationDirPath()来构造绝对路径。

4.2

解决常见的打包错误

打包过程中，你可能会遇到一些错误。

这里我列举几个我常遇到的及其解决方法：

1. “Could

   not

   found”这是最常见的问题，根本原因是linuxdeployqt找不到正确的qmake。

   解决方法就是明确指定qmake的路径，使用-qmake参数：

   linuxdeployqt
   your_app
   -qmake=/opt/Qt/5.15.2/gcc_64/bin/qmake
   -appimage

   确保这个路径就是你开发时使用的Qt版本的qmake。

2. “This

   application

   plugin”程序启动时提示找不到平台插件。

   这通常是因为platforms插件，里面是否有libqxcb.so（对于X11）等文件。

   其次，确保环境变量QT_QPA_PLATFORM_PLUGIN_PATH在AppImage内部被正确设置。

   linuxdeployqt通常会处理好，但如果出现问题，你可以尝试在打包命令后加上-verbose=3参数查看详细日志，检查插件复制过程。

3. 生成的AppImage文件巨大这可能是因为打包了不必要的调试符号、翻译文件或者冗余的Qt模块。

   你可以尝试以下参数来精简：

   linuxdeployqt
   your_app.desktop
   -appimage

   -no-translations跳过翻译文件，-no-strip保留调试符号（发布时可以去掉这个参数让工具自动strip）。

   另外，在Qt项目文件（.pro）中，确保你没有链接不必要的Qt模块（比如QT

   +=

   multimedia如果你的程序不用多媒体功能）。

4. 在较新系统上打包，想在旧系统上运行失败（glibc版本问题）这是Linux二进制兼容的老大难问题。

   AppImage的理念是“一次打包，到处运行”，但glibc的向前兼容性很差。

   一个在Ubuntu

   22.04（glibc

   2.35）上编译的程序，很可能无法在Ubuntu

   18.04（glibc

   2.27）上运行。

   最可靠的解决方案是：在一个较老版本的系统（比如Ubuntu

   18.04）上进行打包。

   你可以使用Docker容器来创建一个干净的、老版本的系统环境进行打包，这是目前最专业和通用的做法。

4.3

使用额外参数优化打包

linuxdeployqt提供了不少参数来微调打包行为，了解它们能让你更好地控制结果：

• -verbose=<0-3>:

  设置输出信息的详细程度。

  调试时用-verbose=3可以看到所有决策过程。

• -always-overwrite:

  即使目标文件已存在也强制覆盖。

  在多次打包调试时有用。

• -executable=<path>:

  除了主程序，额外指定其他需要部署库的可执行文件（比如你程序附带的某个工具）。

• -qmldir=<path>:

  如果你的程序使用了QML，用这个参数指定QML文件所在（比如~/.config/yourapp），而不是尝试写入AppImage只读挂载点。

5.2

分发渠道与版本管理

测试通过后，就可以分发了。

AppImage文件本身就是一个独立的分发单元。

你可以把它放在自己的项目网站、GitHub

Releases页面，或者像AppImageHub这样的集中），很容易地将其转化为deb或rpm包。

这需要用到fpm或dpkg-deb这样的工具。

例如，使用dpkg-deb打包deb的基本思路是：将AppDir整理成符合Linux文件系统层次结构标准（FHS）的样子，比如把可执行文件放到/usr/bin/，库文件放到/usr/lib/yourapp/，然后编写一个DEBIAN/control控制文件，最后用dpkg-deb

-b打包。

虽然这超出了本文的核心范围，但知道有这条路可以走是很有用的。

网上有很多关于如何将目录打包成deb的教程，你的起点已经比他们高了，因为你已经有了一个包含所有依赖的完整AppDir。

最后，我想说，使用linuxdeployqt打包Qt程序为AppImage，是一个平衡了便利性与兼容性的优秀方案。

它不能解决Linux桌面生态的所有问题，但确实为开发者提供了一个非常实用的发布工具。

我自己的几个小项目用上它之后，用户反馈安装体验好了很多。

过程中难免会遇到坑，多看看工具的详细输出日志，善用搜索引擎和项目的GitHub

Issues页面，大部分问题都能找到答案。

希望这份详细的指南能帮你顺利跨过打包的门槛，让你更专注于创造优秀的应用本身。