QT应用程序制作安装包

qq_32663053

1136人浏览 · 2026-03-01 11:16:24

qq_32663053 · 2026-03-01 11:16:24 发布

Qt 应用程序打包部署全攻略：从可执行文件到安装包
摘要：Qt 应用开发完成后，打包部署是最后也是最关键的一步。本文详细介绍 Windows（NSIS/Installer）、Linux（AppImage/Deb）、macOS（DMG）三大平台的打包方法，以及 Qt 特有的依赖处理技巧，助你打造专业的软件安装包。
一、打包前的准备工作
1.1 构建 Release 版本
切勿使用 Debug 版本发布！ Debug 版本依赖调试库，体积大且无法独立运行。
Qt Creator 设置：
plain
复制
左下角构建模式选择：Release
或命令行：qmake CONFIG+=release
1.2 静态链接 vs 动态链接
表格
方式   优点   缺点   适用场景
动态链接（默认）   体积小、可更新 Qt 库   需携带 DLL/SO 文件   大多数桌面应用
静态链接   单文件、无依赖   体积大、LGPL 协议要求   简单工具、嵌入式
静态编译配置（可选）：
bash
复制
# configure 时添加
-static -prefix /path/to/qt-static
二、Windows 平台打包
2.1 使用 windeployqt 工具（官方推荐）
Qt 自带的依赖收集工具，自动复制所需 DLL、插件和翻译文件。
bash
复制
# 进入构建目录
cd release/

# 基础用法
windeployqt YourApp.exe

# 完整用法（包含所有可能依赖）
windeployqt YourApp.exe --release --no-translations --no-compiler-runtime

# 指定输出目录
windeployqt YourApp.exe --dir dist/
windeployqt 复制的内容：
Qt 核心 DLL（Qt5Core.dll, Qt5Gui.dll 等）
平台插件（platforms/qwindows.dll）
样式插件（styles/）
图像格式插件（imageformats/）
翻译文件（可选）
2.2 手动补充依赖
windeployqt 可能遗漏的依赖：
Visual C++ 运行库：msvcp140.dll, vcruntime140.dll
OpenSSL：libcrypto-1_1-x64.dll, libssl-1_1-x64.dll（网络功能）
自定义 DLL：第三方库
使用 Dependency Walker 检查依赖：
bash
复制
# 下载 Dependencies 工具（新版 Dependency Walker）
Dependencies.exe -chain YourApp.exe
2.3 制作安装包（NSIS）
NSIS（Nullsoft Scriptable Install System）是轻量级的 Windows 安装程序制作工具。
安装 NSIS：官网下载 https://nsis.sourceforge.io/
创建安装脚本（installer.nsi）：
nsis
复制
; installer.nsi
!include "MUI2.nsh"

; 基本信息
Name "MyQtApp"
OutFile "MyQtApp-Setup-v1.0.0.exe"
InstallDir "$PROGRAMFILES64\MyQtApp"
RequestExecutionLevel admin

; 界面配置
!insertmacro MUI_PAGE_WELCOME
!insertmacro MUI_PAGE_DIRECTORY
!insertmacro MUI_PAGE_INSTFILES
!insertmacro MUI_PAGE_FINISH

!insertmacro MUI_UNPAGE_WELCOME
!insertmacro MUI_UNPAGE_CONFIRM
!insertmacro MUI_UNPAGE_INSTFILES

!insertmacro MUI_LANGUAGE "SimplifiedChinese"

Section "Install"
SetOutPath "$INSTDIR"

; 复制所有文件（假设已用 windeployqt 收集到 dist 目录）
File /r "dist\*.*"

; 创建快捷方式
CreateDirectory "$SMPROGRAMS\MyQtApp"
CreateShortcut "$SMPROGRAMS\MyQtApp\MyQtApp.lnk" "$INSTDIR\MyQtApp.exe"
CreateShortcut "$DESKTOP\MyQtApp.lnk" "$INSTDIR\MyQtApp.exe"

; 写入卸载程序
WriteUninstaller "$INSTDIR\Uninstall.exe"

; 注册表信息（控制面板显示）
WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MyQtApp" \
"DisplayName" "MyQtApp"
WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MyQtApp" \
"UninstallString" "$INSTDIR\Uninstall.exe"
SectionEnd

Section "Uninstall"
Delete "$INSTDIR\Uninstall.exe"
RMDir /r "$INSTDIR"
Delete "$DESKTOP\MyQtApp.lnk"
RMDir /r "$SMPROGRAMS\MyQtApp"
DeleteRegKey HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\MyQtApp"
SectionEnd
编译安装包：
bash
复制
makensis.exe installer.nsi
2.4 进阶：使用 Qt Installer Framework
Qt 官方提供的安装包制作工具，支持在线更新、组件选择。
安装：通过 Qt MaintenanceTool 安装 Qt Installer Framework
创建配置：
plain
复制
installer/
├── config/
│ ├── config.xml # 安装包配置
│ └── logo.png
└── packages/
└── com.yourcompany.app/
├── meta/
│ ├── package.xml
│ └── installscript.qs
└── data/
└── your_app_files/
config.xml：
xml
复制
<?xml version="1.0" encoding="UTF-8"?>
<Installer>
<Name>MyQtApp</Name>
<Version>1.0.0</Version>
<Title>MyQtApp 安装程序</Title>
<Publisher>Your Company</Publisher>
<StartMenuDir>MyQtApp</StartMenuDir>
<TargetDir>@HomeDir@/MyQtApp</TargetDir>
</Installer>
打包命令：
bash
复制
binarycreator.exe --offline-only -c config/config.xml -p packages MyQtApp-Installer.exe
三、Linux 平台打包
3.1 通用方案：AppImage（推荐）
AppImage 是 Linux 上的"绿色软件"，一个文件包含所有依赖，无需安装即可运行。
使用 linuxdeployqt 工具：
bash
复制
# 1. 下载 linuxdeployqt
wget https://github.com/probonopd/linuxdeployqt/releases/download/continuous/linuxdeployqt-continuous-x86_64.AppImage
chmod +x linuxdeployqt-continuous-x86_64.AppImage

# 2. 准备目录结构
mkdir -p MyApp.AppDir/usr/bin
mkdir -p MyApp.AppDir/usr/lib
mkdir -p MyApp.AppDir/usr/share/applications
mkdir -p MyApp.AppDir/usr/share/icons/hicolor/256x256/apps

# 3. 复制可执行文件
cp YourApp MyApp.AppDir/usr/bin/
cp your_icon.png MyApp.AppDir/usr/share/icons/hicolor/256x256/apps/MyApp.png

# 4. 创建桌面文件
cat > MyApp.AppDir/usr/share/applications/MyApp.desktop << EOF
[Desktop Entry]
Type=Application
Name=MyQtApp
Exec=YourApp
Icon=MyApp
Categories=Development;
Comment=My Qt Application
EOF

# 5. 运行 linuxdeployqt
./linuxdeployqt-continuous-x86_64.AppImage MyApp.AppDir/usr/share/applications/MyApp.desktop -appimage

# 生成 MyQtApp-x86_64.AppImage
3.2 Debian/Ubuntu：DEB 包
bash
复制
# 创建目录结构
mkdir -p myapp-deb/DEBIAN
mkdir -p myapp-deb/usr/bin
mkdir -p myapp-deb/usr/share/applications

# 控制文件
cat > myapp-deb/DEBIAN/control << EOF
Package: myqtapp
Version: 1.0.0
Section: utils
Priority: optional
Architecture: amd64
Depends: libqt5gui5, libqt5core5a, libqt5widgets5
Maintainer: Your Name <your@email.com>
Description: My Qt Application
A simple Qt application.
EOF

# 复制文件
cp YourApp myapp-deb/usr/bin/
cp MyApp.desktop myapp-deb/usr/share/applications/

# 构建
dpkg-deb --build myapp-deb myqtapp_1.0.0_amd64.deb
3.3 RedHat/CentOS：RPM 包
使用 rpmbuild 工具，创建 SPEC 文件后构建。
四、macOS 平台打包
4.1 使用 macdeployqt
Qt 官方提供的 macOS 依赖收集工具。
bash
复制
# 基础用法
macdeployqt YourApp.app

# 生成 DMG 镜像
macdeployqt YourApp.app -dmg

# 包含所有插件
macdeployqt YourApp.app -dmg -verbose=2
4.2 手动完善 App Bundle
App Bundle 结构：
plain
复制
YourApp.app/
└── Contents/
├── Info.plist # 应用配置
├── MacOS/
│ └── YourApp # 可执行文件
├── Resources/
│ ├── YourApp.icns # 图标
│ └── qt.conf # Qt 配置
├── Frameworks/ # Qt 框架（macdeployqt 自动复制）
└── PlugIns/ # 插件
Info.plist 示例：
xml
复制
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleExecutable</key>
<string>YourApp</string>
<key>CFBundleIdentifier</key>
<string>com.yourcompany.YourApp</string>
<key>CFBundleName</key>
<string>YourApp</string>
<key>CFBundleVersion</key>
<string>1.0.0</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleIconFile</key>
<string>YourApp.icns</string>
</dict>
</plist>
4.3 创建 DMG 安装包
bash
复制
# 1. 创建临时目录
mkdir -p dmg_temp

# 2. 复制 App
cp -r YourApp.app dmg_temp/

# 3. 创建符号链接到 Applications
ln -s /Applications dmg_temp/Applications

# 4. 创建 DMG（使用 create-dmg 工具）
create-dmg \
--volname "YourApp Installer" \
--window-pos 200 120 \
--window-size 800 400 \
--icon-size 100 \
--app-drop-link 600 185 \
"YourApp-1.0.0.dmg" \
"dmg_temp/"
五、跨平台自动化方案
5.1 使用 QMake/CMake 自动打包
CMake 示例（CPack）：
cmake
复制
# CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(MyQtApp VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt5 COMPONENTS Widgets REQUIRED)

add_executable(${PROJECT_NAME} main.cpp)

target_link_libraries(${PROJECT_NAME} Qt5::Widgets)

# 安装规则
install(TARGETS ${PROJECT_NAME} RUNTIME DESTINATION bin)

# CPack 配置
set(CPACK_PACKAGE_NAME ${PROJECT_NAME})
set(CPACK_PACKAGE_VERSION ${PROJECT_VERSION})
set(CPACK_PACKAGE_VENDOR "YourCompany")
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "My Qt Application")

if(WIN32)
set(CPACK_GENERATOR "NSIS")
set(CPACK_NSIS_DISPLAY_NAME ${PROJECT_NAME})
elseif(APPLE)
set(CPACK_GENERATOR "DragNDrop")
elseif(UNIX)
set(CPACK_GENERATOR "DEB;RPM")
endif()

include(CPack)
构建安装包：
bash
复制
cmake -B build -S .
cmake --build build --config Release
cpack -C Release --config build/CPackConfig.cmake
5.2 CI/CD 自动化（GitHub Actions）
yaml
复制
# .github/workflows/build.yml
name: Build Installers

on: [push, pull_request]

jobs:
build-windows:
runs-on: windows-latest
steps:
- uses: actions/checkout@v3

- name: Setup Qt
uses: jurplel/install-qt-action@v3
with:
version: '5.15.2'

- name: Build
run: |
qmake CONFIG+=release
nmake

- name: Deploy
run: |
windeployqt release\YourApp.exe
# 使用 NSIS 或 Qt Installer Framework 制作安装包

- name: Upload
uses: actions/upload-artifact@v3
with:
name: windows-installer
path: YourApp-Setup.exe

build-linux:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

- name: Setup Qt
uses: jurplel/install-qt-action@v3

- name: Build AppImage
run: |
# 编译...
# 使用 linuxdeployqt 制作 AppImage

- name: Upload
uses: actions/upload-artifact@v3
with:
name: linux-appimage
path: YourApp-x86_64.AppImage

build-macos:
runs-on: macos-latest
steps:
- uses: actions/checkout@v3

- name: Setup Qt
uses: jurplel/install-qt-action@v3

- name: Build
run: |
qmake CONFIG+=release
make
macdeployqt YourApp.app -dmg

- name: Upload
uses: actions/upload-artifact@v3
with:
name: macos-dmg
path: YourApp.dmg
六、常见问题与解决方案
6.1 运行提示缺少 Qt 库？
原因： windeployqt/macdeployqt 未正确运行，或插件目录缺失。
解决：
bash
复制
# Windows：检查 platforms 目录是否存在 qwindows.dll
# Linux：设置 LD_LIBRARY_PATH 或使用 rpath
patchelf --set-rpath '$ORIGIN/lib' YourApp

# macOS：检查 Frameworks 目录
otool -L YourApp.app/Contents/MacOS/YourApp
6.2 图标/图片无法显示？
原因：图像格式插件未打包。
解决：
bash
复制
# 确保 imageformats 目录包含 qjpeg.dll, qpng.dll 等
windeployqt YourApp.exe --dir dist
# 手动复制：Qt/plugins/imageformats/* -> dist/imageformats/
6.3 中文显示乱码？
原因：缺少翻译文件或字体。
解决：
cpp
复制
// main.cpp 中添加
#include <QTranslator>

int main(int argc, char *argv[]) {
QApplication app(argc, argv);

// 加载 Qt 自带中文翻译
QTranslator translator;
translator.load(":/translations/qt_zh_CN.qm");
app.installTranslator(&translator);

// 或使用系统字体
app.setFont(QFont("Microsoft YaHei", 9));
}
6.4 数据库驱动加载失败？
原因： SQL 驱动插件未打包。
解决：
bash
复制
# 复制 sqldrivers 目录
# Windows: Qt/plugins/sqldrivers/qsqlite.dll, qsqlmysql.dll
# Linux: Qt/plugins/sqldrivers/libqsqlite.so
七、最佳实践总结
表格
平台   推荐方案   输出格式
Windows   windeployqt + NSIS/Qt Installer Framework   .exe 安装包
Linux   linuxdeployqt (AppImage)   .AppImage
macOS   macdeployqt + create-dmg   .dmg 镜像
打包检查清单：
[ ] Release 模式构建
[ ] 所有依赖 DLL/SO/Dylib 已包含
[ ] 插件目录（platforms, imageformats, sqldrivers）完整
[ ] 翻译文件（如需要）已添加
[ ] 图标/资源文件正确嵌入
[ ] 在干净环境（无 Qt 环境）测试通过
[ ] 安装/卸载流程测试正常
参考资料：
Qt 官方部署文档：https://doc.qt.io/qt-6/deployment.html
Qt Installer Framework 手册：https://doc.qt.io/qtinstallerframework/
NSIS 文档：https://nsis.sourceforge.io/Docs/