linux下Qt程序部署教程

---

更多精彩内容
👉内容导航 👈
👉Qt开发经验 👈

---

1、概述

linux下打包部署Qt编译的程序主要有3种方法：

• 方法1：安装Qt时编译生成静态库，这样编译生成的程序就不会依赖于Qt库了，如果用到第三方动态库另说；
• 方法2：使用linuxdeployqt打包程序的依赖库；
• 方法3：使用linuxdeploy打包程序。

注意：

• 最好在低版本的LTS（长期支持）系统编译打包程序，这样打包的程序可以支持在低版本和高版本的系统运行，如果在高版本的系统编译打包，在低版本的系统可能不兼容。

测试环境

环境	版本
系统	ubuntu22.04
Qt	Qt5.14.2
linuxdeployqt	2024-9-8版本
appimagetool	3.10.5

2、静态编译安装Qt

如果已经通过Qt官方提供的安装包进行安装了动态版本的可以选择跳过这一节。

官方说明：

从Git构建Qt 5 - Qt Wiki

从Git构建Qt 6 - Qt Wiki

1.1 安装依赖

qt5.14.2

sudo apt-get install build-essential perl python3 git
# Libxcb 的sudo apt-get install '^libxcb.*-dev' libx11-xcb-dev libglu1-mesa-dev libxrender-dev libxi-dev libxkbcommon-dev libxkbcommon-x11-dev
# Qt WebKit（Qt WebKit）
sudo apt-get install flex bison gperf libicu-dev libxslt-dev ruby
# Qt Web引擎
sudo apt-get install libxcursor-dev libxcomposite-dev libxdamage-dev libxrandr-dev libxtst-dev libxss-dev libdbus-1-dev libevent-dev libfontconfig1-dev libcap-dev libpulse-dev libudev-dev libpci-dev libnss3-dev libasound2-dev libegl1-mesa-dev gperf bison nodejs
#Qt多媒体
sudo apt-get install libasound2-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libgstreamer-plugins-good1.0-dev libgstreamer-plugins-bad1.0-dev

Qt6

sudo apt install libxcb-image0-dev libxcb-shm0-dev libxcb-icccm4-dev libxcb-sync-dev libxcb-xfixes0-dev libxcb-shape0-dev libxcb-randr0-dev libxcb-render-util0-dev libxcb-util-dev libxcb-xinerama0-dev libxcb-xkb-dev libxkbcommon-dev libxkbcommon-x11-dev libfontconfig1-dev libfreetype-dev libx11-dev libx11-xcb-dev libxext-dev libxfixes-dev libxi-dev libxrender-dev libxcb1-dev libxcb-cursor-dev libxcb-glx0-dev libxcb-keysyms1-dev git cmake g++ gcc perl python libclang-dev libgl-dev libegl-dev libfontconfig1-dev libinput-dev

1.2 静态编译

Qt5

cd qtbase
mkdir build
cd build
# 编译静态库
../configure -developer-build -opensource -nomake examples -nomake tests --prefix=/opt/qt5.14.2/ -static  -release
make -j8
make install

Qt6

mkdir build 
cd build 
../configure -developer-build -opensource -nomake examples -nomake tests --prefix=/opt/qt6.2.9/ -static -releasecmake --build . --parallel 8
cmake --install .

1.3 报错

• 错误

class numeric_limits<QT_PREPEND_NAMESPACE(qfloat16)> : public numeric_limits<float>
5.14.2/qtbase/include/QtCore/../../src/corelib/global/qfloat16.h:295:7: error: ‘numeric_limits’ is not a class template
295 | class numeric_limits<QT_PREPEND_NAMESPACE(qfloat16)> : public numeric_limits<float>
|       ^~~~~~~~~~~~~~

• 解决办法：打开qtbase/src/corelib/global/qglobal.h，添加#include <limits>；

#ifdef __cplusplus
#  include <type_traits>
#  include <cstddef>
#  include <utility>
#  include <limits>
#endif

1.4 添加环境变量

export PATH=/opt/qt5/bin:$PATH                            # 可执行程序环境变量
export LD_LIBRARY_PATH=/opt/qt5/lib:$LD_LIBRARY_PATH      # 链接库环境变量

1.5 下载安装QtCreator

1. 下载最新版本的Qt Creator安装包，也可以下载源码编译；

   

2. 下载后使用sudo chmod 777 ./qt-creator*.run设置文件权限，然后使用sudo ./qt-creator-opensource-linux-x86_64-14.0.2.run命令运行安装。

3. 安装完成后配置编译器；

4. 点击【工具】->【外部】->【配置】，打开【首选项】；

   

5. 点击【Kit】->【Qt版本】->【添加】，找到自己编译安装的Qt安装路径下编译器中的QMake；

   • /opt/qt5/bin/qmake；

   

6. 然后选择【构建套件Kit】，点击【添加】；

   • 编译器选择gcc/g++，调试器选择GDB，Qt版本选择刚才添加的qmake名称；

   

7. 配置完成后创建一个工程，选择QMake，刚才添加的编译器就可以编译代码了。

3、配置linuxdeployqt环境

1.1 在线安装依赖

sudo apt install patchelf libfuse2

• patchelf用于修改现有的ELF可执行文件和库（修改可执行程序去寻找动态库的路径，默认是从环境变量找）;

• libfuse2 Linux FUSE（用户空间中的文件系统）接口的参考实现。（可以不安装，如果linuxdeployqt运行提示缺失再安装）

1.2 使用linuxdeployqt提供的程序

• 下载linuxdeployqt可执行程序linuxdeployqt-continuous-x86_64.AppImage
• 使用sudo chmod 777 linuxdeployqt-continuous-x86_64.AppImage设置文件权限；
• 然后使用linuxdeployqt-continuous-x86_64.AppImage -version 命令检查程序是否可以运行，在高版本的ubuntu或者不支持的系统需要自己编译源码；
• 注意：
  • linux只提供了x86-64架构的可执行程序。
  • 如果显示找不到Qt库则需要将Qt库的lib路径添加环境变量。

1.3 编译安装linuxdeployqt

• 下载linuxdeployqt源码；
• 解压后使用qt creator打开linuxdeployqt.pro文件；

• 注意： 如果ubuntu版本大于20.04则需要打开main.cpp文件，将if (strverscmp (glcv, "2.32") >= 0)判断功能注释掉；

• 注意： linuxdeployqt中调用appimagetool打包程序需要联网，appimagetool打包程序时会依赖于type2-runtime程序，如果没有安装runtime则使用linuxdeployqt每次运行都会从github下载runtime，速度慢，并且需要联网，如果没有联网或者无法访问github则打包第三步会失败，后续给出解决办法。

• 直接开始编译，然后在编译生成的build文件夹中的bin文件夹内找到linuxdeployqt；

• 使用命令sudo cp linuxdeployqt /usr/local/bin/将linuxdeployqt添加到环境变量可以找到的路径下；
• 使用linuxdeployqt -version命令验证是否安装成功；

• 如果找不到显示错误如下：
  • 使用命令gedit ~/.bashrc打开文件..bashrc文件；
  • 添加Qt环境变量；export LD_LIBRARY_PATH=/opt/Qt5.14.2/5.14.2/gcc_64/lib:$LD_LIBRARY_PATH；
  • 然后保存关闭文件，使用source .bashrc使配置生效。

linuxdeployqt: error while loading shared libraries: libQt5Core.so.5: cannot open shared object file: No such file or directory

4、使用linuxdeployqt打包依赖

linuxdeployqt工作流程：

1. 将依赖库文件打包到当前路径下；
2. 使用patchelf修改可执行程序查找动态库的路径；
3. 使用appimagetool将打包好的可执行程序和依赖库制作为AppImage程序。

这三个步骤可以一步全部执行，也可以单独执行；

• 如果使用-appimage全部执行可能会报错，导致步骤中断；

• 如果执行第一步失败，则打包的依赖库不全，无法使用；

• 如果第一步执行完成，第二步失败，则依赖库打包完成，但是拷贝到其它电脑上后还是无法找到动态库，因为这时可执行程序是从系统环境变量去找动态库，可以单独使用patchelf命令修改查找路径；

• 如果前两步执行完成，就可以将整个文件夹复制到其它电脑上使用了；

• 第三步是将整个文件夹制作为一个单独可以运行的AppImage程序。

1.1 linuxdeployqt使用选项

选项	说明
-always-overwrite	复制文件，即使目标文件存在。
-appimage	创建一个AppImage（默认包含-bundle-non-qt-lib）
-bundle-non-qt-libs	打包非Qt库
-exclude-libs=$⟨$ list$⟩$	应排除的库列表，以逗号分隔。
-ignore-glob=	在搜索库时忽略相对于appdir的glob模式。
-executable=	让给定的可执行文件也使用部署的库
-executable-dir=	让文件夹中的所有可执行文件（递归）也使用部署的库
-extra-plugins=	需要部署的额外插件列表，以逗号分隔。
-no-copy-copyright-files	不部署版权文件。
-no-plugins	跳过插件部署。
-no-strip	不要在二进制文件上运行‘strip’。
-no-translations	跳过翻译的部署。
-qmake=	要使用的qmake可执行文件。
-qmldir=	扫描指定路径中的QML导入。
-qmlimport=	添加给定的路径到QML模块搜索位置。
-show-exclude-libs	打印排除库列表。
-verbose=<0-3>	0 =无输出，1 =错误/警告（默认），2 =正常，3 =调试。
-updateinformation=	嵌入更新信息string；如果安装了zsyncmake，生成zsync文件
-version	打印版本语句并退出。

示例：

linuxdeployqt 可执行程序 -appimage

• 注意：可执行程序所在的根文件夹不应该时bin，否则打包的文件会跑到文件夹外。

1.2 patchelf修改动态库搜索路径

如果打包第二步执行失败，则可以手动使用patchelf修改动态库搜索路径。

• patchelf基本用法:

  • $ORIGIN是一个特殊的占位符，它表示当前可执行文件所在的目录
  • RPATH 是一个嵌入到 ELF 文件中的路径列表，用于告诉动态链接器在运行时去哪里查找共享库。

patchelf --set-rpath '$ORIGIN/lib/' ./RadarServer     # 设置程序动态库链接路径
patchelf --print-rpath ./RadarServer   # 打印链接路径

1.3 验证

打包完成后需要验证依赖库是否打包完整，可执行程序是否能从当前路径下找到动态库。

• 使用下列命令临时清除动态库环境变量：

export LD_LIBRARY_PATH=""

• 然后再使用ldd命令查看链接动态库是否指向相对路径

ldd ./可执行程序

• 再运行可执行程序看是否能成功运行。

1.4 修改linuxdeployqt源码

注意： 如果离线想通过linuxdeployqt直接生成appimage包，就需要修改源码，否则可用跳过。

• 由于linuxdeployqt调用appimagetool命令没有指定运行时，所以名称使用-appimage打包时都会从github下载runtime，离线环境或者网络差的环境无法使用；
• 需要离线使用linuxdeployqt指定运行时就需要修改linuxdeployqt源码。

1. 下载安装runtime，放到/usr/local/bin路径下；
2. 打开linuxdeployqt源码，找到shared.cpp文件，搜索appimagetool；
3. 在下图中位置添加指定运行时runtime的路径；
4. 然后编译生成linuxdeployqt就可以使用了。

5、使用appimagetool打包生成AppImage程序

AppImage是一种将应用程序及其所有依赖项打包成一个单一可执行文件的格式。这种格式使得分发和运行应用程序变得非常简单，因为用户无需担心安装过程中可能出现的各种问题，如权限不足、缺少依赖库等。以下是关于AppImage程序的一些详细说明：

特点

1. 独立性：AppImage包含应用程序的所有依赖项，因此可以在任何支持的Linux发行版上运行，而不需要额外的安装步骤。
2. 便携性：AppImage是一个单一的可执行文件，可以方便地复制、移动和分享。
3. 安全性：由于AppImage是自包含的，它不会对系统进行任何更改，因此减少了潜在的安全风险。
4. 更新简便：用户可以简单地下载新版本的AppImage并替换旧版本，而无需卸载或重新安装。

工作原理

1. 打包：开发者使用工具（如appimagetool）将应用程序及其所有依赖项打包成一个AppImage文件。
2. 运行：用户下载AppImage文件后，只需赋予其执行权限（例如通过命令chmod +x your-app.AppImage），然后直接运行即可。
3. 集成桌面环境：AppImage通常会自动集成到用户的桌面环境中，使其在应用菜单中可见。

https://doc.appimage.cn/docs/home/

https://appimage.org/

https://specifications.freedesktop.org/menu-spec/latest/category-registry.html

1.1 安装appimagetool

• 下载runtime可执行程序；runtime-x86_64
• 下载appimagetool可执行程序appimagetool-x86_64.AppImage；
• https://appimage.github.io/appimagetool/
• 使用下面命令安装

sudo chmod 777 runtime-x86_64 appimagetool-x86_64.AppImage   # 设置权限
sudo cp runtime /usr/local/bin/runtime
sudo cp appimagetool-x86_64.AppImage /usr/local/bin/appimagetool

1.2 appimagetool选项

appimagetool [选项… ] 可执行程序文件夹 [生成文件名]

[]中是可选

例如：

appimagetool ./untitled4.App --runtime-file /usr/local/bin/runtime-x86_64

将untitled4.App文件夹打包

指定运行时文件路径--runtime-file /usr/local/bin/runtime-x86_64。

选项	说明
-h	帮助
-l, --list	列出SOURCE AppImage中的文件
-u, --updateinformation	嵌入更新信息字符串；如果安装了zsyncmake，生成zsync文件
-g, --guess	基于常用CI系统（GitHub actions, GitLab CI）设置的环境变量猜测更新信息
–version	显示版本号
-v, --verbose	输出详细信息
-s, --sign	用gpg[2]签名
–comp	压缩
-n, --no-appstream	不检查AppStream元数据
–exclude-file	除了.appimageignore之外，还使用指定文件作为mksquash的排除文件。
–runtime-file	指定runtime文件路径
–sign-key	用于gpg[2]签名的密钥ID
–sign-args	使用gpg[2]签名时使用的额外参数

1.3 打包AppImage工程

创建AppImage

文件夹结构规范

• 不按照文件夹规范也可以，最简单的是创建一个文件夹，文件夹中包含可执行程序、可执行程序.desktop、可执行程序.png三个文件；
• 然后使用linuxdeployqt打包依赖库，如果没有desktop和图标，则在使用linuxdeployqt打包时会生成默认的文件，但是需要修改文件内容；
• 使用appimagetool打包成appimage程序；

desktop规范

.desktop基本文件格式

可用的键值对

[Desktop Entry]
Name=应用程序的具体名称
Exec=可执行程序路径
Icon=图片名称（不包含后缀）
Type=Application # 类型， Application （类型1）； Link （类型2） Directory （3型）
Categories=Utilities # 注册类别，必须项

注册类别主要分类

主要类别	描述	Notes
AudioVideo	用于呈现、创建或处理多媒体（音频/视频）的应用程序
Audio	音频应用程序	Desktop entry must include AudioVideo as well
Video	视频应用	Desktop entry must include AudioVideo as well
Development	开发应用程序
Education	教学软件
Game	游戏
Graphics	用于查看、创建或处理图形的应用程序
Network	网络应用程序，如web浏览器
Office	办公室类型的应用程序
Science	科学软件
Settings	设置应用程序	条目可以出现在单独的菜单中，也可以作为“控制中心”的一部分。
System	系统应用程序，“系统工具”，例如日志查看器或网络监视器
Utility	小型公用事业应用，“辅助程序”

示例：

6、错误记录

• 执行linuxdeployqt时报错，需要安装sudo apt install libfuse2
• https://github.com/AppImage/AppImageKit/wiki/FUSE

dlopen(): error loading libfuse.so.2AppImages require FUSE to run. 
You might still be able to extract the contents of this AppImage 
if you run it with the --appimage-extract option. 
See https://github.com/AppImage/AppImageKit/wiki/FUSE 
for more information

• 系统版本过新，需要自己编译linuxdeployqt；

linuxdeployqt  (commit b00a83d), build 70 built on 2024-09-08 11:56:56 UTC
ERROR: The host system is too new.
Please run on a system with a glibc version no newer than what comes with the oldest
currently supported mainstream distribution (Ubuntu Focal Fossa), which is glibc 2.31.
This is so that the resulting bundle will work on most still-supported Linux distributions.
For more information, please see
https://github.com/probonopd/linuxdeployqt/issues/340

• linuxdeployqt找不到Qt动态库的环境变量
  • 在.bashrc中添加export LD_LIBRARY_PATH=/opt/Qt5.14.2/5.14.2/gcc_64/lib:$LD_LIBRARY_PATH

./linuxdeployqt: error while loading shared libraries: libQt5Core.so.5: cannot open shared object file: No such file or directory

• linuxdeployqt从环境变量中找不到qt的qmake
  • 在.bashrc中添加export PATH=/opt/Qt5.14.2/5.14.2/gcc_64/bin:$PATH

ERROR: Desktop file missing, creating a default one (you will probably want to edit it)
ERROR: Icon file missing, creating a default one (you will probably want to edit it)
qmakePath 3= ""
ERROR: qmake not found on the $PATH

• 需要安装sudo apt install patchelf

relativeBinPath: "untitled"
Keeping existing AppRun
qmakePath 3= ""
ERROR: Could not start patchelf.
ERROR: Make sure it is installed on your $PATH.
ERROR: Error reading rpath with patchelf "libQt5Widgets.so" : ""
ERROR: Error reading rpath with patchelf "libQt5Widgets.so" : ""

• linuxdeployqt找不到appimagetool，打包的依赖库已经可以使用了，如果需要打包成appimage程序，就可以下载安装appimagetool和runtime；

relativeBinPath: "untitled"
Keeping existing AppRun
qmakePath 3= ""
sh: 1: appimagetool: not found

• linuxdeployqt默认生成的default.desktop文件内缺少必须项Categories；

WARNING: "/home/mhf/Code/test/qt.conf" already exists, will not overwrite.
fusermount3 version: 3.10.5
appimagetool, continuous build (git version feac857), build 185 built on 2024-11-24 19:31:44 UTC
WARNING: zsyncmake command is missing, please install it if you want to use binary delta updates
Desktop file: /home/mhf/Code/test/default.desktop
Categories entry not found in desktop file
.desktop file is missing a Categories= key

• default.desktop中Categories设置的值错误，必须是给出的固定值；

/home/mhf/Code/test/default.desktop: error: value "Utilities" for key "Categories" in group "Desktop Entry" contains an unregistered value "Utilities";  values extending the format should start with "X-"

• linuxdeployqt中调用appimagetool需要依赖于runtime，每次都需要从github联网下载；解决办法：
  1. 下载runtime放到/usr/local/bin路径下，使用appimagetool去打包；
  2. 修改linuxdeployqt，增加指向runtime的路径。

Using app name extracted from desktop file: Application
/home/mhf/Code/test should be packaged as Application-x86_64.AppImage
Deleting pre-existing .DirIcon
Creating .DirIcon symlink based on information from desktop file
Generating squashfs...
Downloading runtime file from https://github.com/AppImage/type2-runtime/releases/download/continuous/runtime-x86_64
libcurl's default CA certificate bundle file /etc/ssl/certs/ca-certificates.crt was found on this system
libcurl's default CA certificate bundle directory /etc/ssl/certs was found on this system
* Host github.com:443 was resolved.
* IPv6: (none)
* IPv4: 20.205.243.166
*   Trying 20.205.243.166:443...
* Connected to github.com (20.205.243.166) port 443
* ALPN: curl offers h2,http/1.1
*  CAfile: /etc/ssl/certs/ca-certificates.crt
*  CApath: /etc/ssl/certs
* SSL connection using TLSv1.3 / TLS_AES_128_GCM_SHA256 / X25519 / id-ecPublicKey
* ALPN: server accepted h2
* Server certificate:
*  subject: CN=github.com
*  start date: Mar  7 00:00:00 2024 GMT
*  expire date: Mar  7 23:59:59 2025 GMT
*  subjectAltName: host "github.com" matched cert's "github.com"
*  issuer: C=GB; ST=Greater Manchester; L=Salford; O=Sectigo Limited; CN=Sectigo ECC Domain Validation Secure Server CA
*  SSL certificate verify ok.
*   Certificate level 0: Public key type EC/prime256v1 (256/128 Bits/secBits), signed using ecdsa-with-SHA256
*   Certificate level 1: Public key type EC/prime256v1 (256/128 Bits/secBits), signed using ecdsa-with-SHA384
*   Certificate level 2: Public key type EC/secp384r1 (384/192 Bits/secBits), signed using ecdsa-with-SHA384
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://github.com/AppImage/type2-runtime/releases/download/continuous/runtime-x86_64
* [HTTP/2] [1] [:method: GET]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: github.com]
* [HTTP/2] [1] [:path: /AppImage/type2-runtime/releases/download/continuous/runtime-x86_64]
* [HTTP/2] [1] [accept: */*]
> GET /AppImage/type2-runtime/releases/download/continuous/runtime-x86_64 HTTP/2
Host: github.com
Accept: */*

• 需要安装sudo apt install zsync

WARNING: "/home/mhf/Code/RadarServer.AppDir/qt.conf" already exists, will not overwrite.
fusermount3 version: 3.10.5
appimagetool, continuous build (git version feac857), build 185 built on 2024-11-24 19:31:44 UTC
WARNING: zsyncmake command is missing, please install it if you want to use binary delta updates
fatal: 不是 git 仓库（或者任何父目录）：.git
Failed to run 'git rev-parse --short HEAD: Child process exited with code 128 (code 128)
Desktop file: /home/mhf/Code/RadarServer.AppDir/default.desktop
/home/mhf/Code/RadarServer.AppDir/default.desktop: error: value "Network" for boolean key "Terminal" in group "Desktop Entry" contains invalid characters, boolean values must be "false" or "true"
ERROR: Desktop file contains errors. Please fix them. Please seehttps://standards.freedesktop.org/desktop-entry-spec/1.0/n       for more information.

7、参考

1.1 Qt

• 从Git构建Qt 5 - Qt Wiki
• 从Git构建Qt 6 - Qt Wiki
• Qt Creator安装包

1.2 linuxdeployqt

• patchelf

• libfuse2

• linuxdeployqt

• linuxdeploy

• Linuxdeploy用户指南

1.3 appimage

• runtime下载
• appimagetool下载
• AppImage
• appimage英文文档
• appimage中文文档
• AppImage-CN
• appimagetool下载地址
• appimagetool源码及下载地址
• desktop规范
• desktop可用键值对

8、视频

linux下QT程序打包

linux下使用linuxdeployqt工具打包Qt程序

---

---