qt部署

Qt for Windows - 部署

本文档介绍了适用于 Windows 系统的 Qt 应用部署流程。全文将以“Plug & Paint”示例应用为例，演示具体的部署步骤。

Windows 部署工具

Windows 部署工具 windeployqt 旨在自动化创建可部署文件夹的过程，该文件夹包含运行应用所需的 Qt 相关依赖项（库、QML 导入文件、插件和翻译文件）。它可为通用 Windows 平台（UWP）创建沙箱环境，或为 Windows 桌面应用创建安装目录树，这些内容可轻松打包为安装程序包。

工具位置与环境配置

工具路径：该工具位于 QTDIR/bin/windeployqt 目录下。
运行环境：需在构建环境中运行才能正常工作。若使用 Qt 安装程序，应通过脚本 QTDIR/bin/qtenv2.bat 配置构建环境。

核心功能与工作原理

依赖扫描：windeployqt 以 .exe 文件或包含 .exe 文件的目录作为参数，扫描可执行文件的依赖项。
QML 依赖处理：若通过 --qmldir 参数指定目录，工具会使用 qmlimportscanner 工具扫描该目录下的 QML 文件，识别 QML 导入依赖，并将所有已识别的依赖项复制到可执行文件所在目录。
路径修复：若 Qt 编译时未启用 configure -relocatable（即关闭“可重定位”），windeployqt 会将 Qt5Core.dll 中硬编码的本地路径替换为相对路径。
编译器运行时文件：对于 Windows 桌面应用，默认情况下会将编译器所需的运行时文件复制到可部署文件夹（除非指定 --no-compiler-runtime 选项）。若使用 Microsoft Visual C++ 编译发布版本，这些文件包含 Visual C++ 可再发行组件包（VCRedist），供应用安装程序在目标机器上递归安装；其他情况下，则使用编译器运行时的共享库。

注意：应用可能依赖额外的第三方库（如数据库库），windeployqt 不会处理这类依赖，需手动配置。

基本用法与命令选项

基本用法

将 Qt 安装目录的 bin 文件夹（例如 <QT_DIR\bin>）添加到系统 PATH 环境变量。
运行以下命令（根据应用类型选择）：
- 普通应用：windeployqt <应用二进制文件路径>
- Qt Quick 应用：windeployqt --qmldir <应用QML文件路径> <应用二进制文件路径>

补充说明：若 ICU、ANGLE 等组件不在 bin 目录中，需将其所在路径添加到 PATH 环境变量。

常用命令选项

选项	功能描述
`-?, -h, --help`	显示命令行选项帮助
`--help-all`	显示包含 Qt 特定选项的完整帮助
`-v, --version`	显示工具版本信息
`--dir <directory>`	使用指定目录代替二进制文件所在目录作为部署目标
`--libdir <path>`	将库文件复制到指定路径
`--plugindir <path>`	将插件复制到指定路径
`--debug`	假设处理的是调试版本二进制文件
`--release`	假设处理的是发布版本二进制文件
`--pdb`	部署 .pdb 文件（仅适用于 MSVC 编译器）
`--force`	强制更新已存在的文件
`--dry-run`	模拟部署模式，不实际复制/更新文件
`--no-patchqt`	不修补 Qt5Core 库
`--no-plugins`	跳过插件部署
`--no-libraries`	跳过库文件部署
`--qmldir <directory>`	从指定目录开始扫描 QML 导入依赖
`--qmlimport <directory>`	将指定路径添加到 QML 模块搜索路径
`--no-quick-import`	跳过 Qt Quick 导入文件的部署
`--no-translations`	跳过翻译文件的部署
`--compiler-runtime`	部署编译器运行时（仅适用于桌面应用）
`--no-compiler-runtime`	不部署编译器运行时（仅适用于桌面应用）
`--list <option>`	仅打印已复制文件的名称，`option` 可选： - `source`：源文件绝对路径 - `target`：目标文件绝对路径 - `relative`：目标文件相对于目标目录的路径 - `mapping`：输出源路径与相对目标路径的映射（适用于 Appx 映射文件）
`--verbose <level>`	详细输出级别（0-2，级别越高信息越详细）

Qt 库的添加与移除

添加库：通过库名称指定（例如 -xml 表示添加 Qt XML 库）。
移除库：在库名称前加 --no-（例如 --no-xml 表示不添加 Qt XML 库）。

支持的库包括：bluetooth、concurrent、core、declarative、designer、designercomponents、enginio、gamepad、gui、qthelp、multimedia、multimediawidgets、multimediaquick、network、nfc、opengl、positioning、printsupport、qml、qmltooling、quick、quickparticles、quickwidgets、script、scripttools、sensors、serialport、sql、svg、test、webkit、webkitwidgets、websockets、widgets、winextras、xml、xmlpatterns、webenginecore、webengine、webenginewidgets、3dcore、3drenderer、3dquick、3dquickrenderer、3dinput、3danimation、3dextras、geoservices、webchannel、texttospeech、serialbus、webview。

静态链接（Static Linking）

静态链接会将 Qt 库与应用打包为单个可执行文件，无需在目标机器上额外部署 Qt 依赖库，但无法部署插件。

1. 静态编译 Qt

需通过 configure -static 配置 Qt 静态编译，命令如下：

cd C:\path\to\Qt  # 进入 Qt 源码目录
configure -static <其他所需选项>  # 配置静态编译

注意：若需在同一目录重新配置并编译 Qt，需先进入构建目录，运行 nmake distclean（MSVC 编译器）或 mingw32-make distclean（MinGW 编译器）清除之前的配置痕迹，再重新执行 configure。

2. 将应用链接到 Qt 静态库

以“Plug & Paint”示例应用为例，步骤如下：

进入应用源码目录：
```
cd examples\tools\plugandpaint
```

清理旧构建文件并生成静态链接的可执行文件：

nmake clean  # 清理旧构建（MSVC）；MinGW 用 mingw32-make clean
qmake -config release  # 生成发布版本的 Makefile，指定链接静态库
nmake  # 编译生成静态可执行文件（MSVC）；MinGW 用 mingw32-make

3. 验证与注意事项

验证方法：将生成的 plugandpaint.exe 复制到未安装 Qt 或 Qt 应用的机器上，运行以确认是否正常工作。
编译器依赖：即使是静态链接，应用若依赖编译器特定库（如 Visual C++ 运行时），仍需手动分发这些库。可通过 depends 工具（依赖查看器）检查应用依赖的库。
插件限制：静态链接方式无法部署插件，因此应用功能会因缺少插件而受限。若应用依赖插件，建议使用动态链接（共享库）方式。

共享库（Shared Libraries）

共享库方式是 Qt 部署的默认方式，需将应用可执行文件与 Qt 共享库、插件等一同部署，支持插件功能，但需确保依赖文件路径正确。

1. 编译 Qt 共享库（默认配置）

Qt 安装时默认以共享库模式构建，假设 Qt 安装在 C:\path\to\Qt 目录。

2. 将应用链接到 Qt 共享库

仍以“Plug & Paint”示例应用为例：

步骤 1：编译应用核心可执行文件

cd examples\tools\plugandpaint  # 进入应用目录
nmake clean  # 清理旧构建（MSVC）；MinGW 用 mingw32-make clean
qmake -config release  # 生成发布版本 Makefile（动态链接）
nmake  # 编译生成动态链接的可执行文件

步骤 2：编译应用插件

cd ..\plugandpaint/plugins  # 进入插件目录
nmake clean  # 清理旧插件构建
qmake -config release  # 生成插件 Makefile
nmake  # 编译插件，生成 pnp_basictools.dll 和 pnp_extrafilters.dll

成功编译后，会得到：

应用可执行文件：plugandpaint.exe
插件文件：pnp_basictools.dll（基础工具插件）、pnp_extrafilters.dll（额外滤镜插件）

3. 创建应用部署包

需将应用可执行文件、Qt 依赖库、插件、编译器运行时等按特定目录结构组织，确保应用能找到所有依赖。

核心文件与目录结构

应用部署包需包含以下文件（以“Plug & Paint”为例），目录结构参考如下：

release/
├─ plugandpaint.exe  # 应用可执行文件
├─ Qt5Core.dll       # Qt Core 模块库
├─ Qt5Gui.dll        # Qt GUI 模块库
├─ Qt5Widgets.dll    # Qt Widgets 模块库
├─ platforms/        # 平台插件目录（必选）
│  └─ qwindows.dll   # Windows 平台插件（Qt GUI 应用必需）
├─ styles/           # 样式插件目录（可选，按需添加）
│  └─ qwindowsvistastyle.dll  # Windows Vista 样式插件
├─ plugins/          # 应用自定义插件目录（按需添加）
│  ├─ pnp_basictools.dll      # 基础工具插件
│  └─ pnp_extrafilters.dll    # 额外滤镜插件
├─ iconengines/      # 图标引擎插件目录（可选，按需添加）
├─ imageformats/     # 图像格式插件目录（可选，按需添加）
└─ ...               # 其他按需添加的插件目录

需额外添加的文件

根据应用配置和依赖，可能需要添加以下文件：

依赖类型	所需文件	说明
编译器运行时（Visual Studio）	`vccorlib140.dll`、`vcruntime140.dll`（C 运行时）、`msvcp140.dll`（C++ 运行时）	适用于 Visual Studio 14.0 (2015)、15.0 (2017)、16.0 (2019)，需与编译时使用的编译器版本一致
动态 OpenGL（ANGLE）	`libEGL.dll`、`libGLESv2.dll`（ANGLE 库）、`d3dcompiler_XX.dll`（HLSL 编译器，XX 为版本号）、`opengl32sw.dll`（OpenGL 软件渲染库）	若应用使用动态 OpenGL，需从 Qt 的 `lib` 目录复制
ICU 库	`icudtXX.dll`、`icuinXX.dll`、`icuucXX.dll`	若 Qt 编译时配置了 ICU 支持，需添加这些文件

插件路径配置（可选）

默认情况下，应用会在自身目录下的 plugins 子目录中搜索插件。若需自定义插件路径，可通过代码添加：

#include <QCoreApplication>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    // 添加自定义插件搜索路径
    QCoreApplication::addLibraryPath("C:/some/other/path/plugins");
    // ... 其他代码 ...
    return a.exec();
}

QCoreApplication::addLibraryPath()：在现有搜索路径前添加自定义路径，应用会优先搜索该路径。
QCoreApplication::setLibraryPaths()：直接设置所有搜索路径及顺序，覆盖默认路径。

验证部署包

将部署包解压到未安装 Qt 和编译器的机器上，运行 plugandpaint.exe，确认应用可正常启动且插件功能可用。

清单文件（Manifest Files）

使用 Visual Studio 编译应用时，需额外处理清单文件，该文件记录了应用对“并行程序集”（如编译器运行时库）的依赖信息。

1. 清单文件的复制与嵌入

应用清单：需将链接生成的应用清单文件（与 .exe 同名，扩展名为 .manifest）复制到可执行文件所在目录。
DLL 清单：无需复制共享库（DLL）的清单文件；若 DLL 的依赖与应用不同，需将其清单文件嵌入 DLL 二进制文件中。

2. 清单嵌入配置（Qt 4.1.3 及以上）

Qt 提供以下 CONFIG 选项控制清单嵌入，默认均为启用状态：

embed_manifest_dll：嵌入 DLL 清单。
embed_manifest_exe：嵌入应用（EXE）清单。

若需禁用应用清单嵌入，在项目的 .pro 文件中添加：

CONFIG -= embed_manifest_exe

3. 编译器运行时的正确部署

推荐通过以下方式在目标机器上安装编译器运行时：

从 Visual Studio 安装目录（<Visual Studio install path>/VC/redist/<language-code>）获取对应版本的可再发行组件包：
- 64 位：vcredist_x64.exe
- 32 位：vcredist_x86.exe
将该组件包与应用安装程序一同分发，并确保用户安装应用时自动执行该组件包。

关键注意事项：发布的应用必须使用与编译时完全相同的编译器版本和 C 运行时版本，避免因运行时版本不匹配导致部署错误。

应用依赖项（Application Dependencies）

1. 额外库的检查与分发

应用可能依赖 Qt 之外的库（如 ANGLE、ICU、OpenSSL 等），需通过工具检查并手动分发：

检查工具：使用 Dependency Walker（依赖查看器），命令为 depends <应用可执行文件路径>，该工具会列出应用依赖的所有库（包括系统库和非系统库）。
示例（Plug & Paint 发布版本）：
- Qt 库：QT5CORE.DLL、QT5GUI.DLL、QT5WIDGETS.DLL
- Visual C++ 运行时：VCCORLIB140.DLL、VCRUNTIME140.DLL、MSVCP140.DLL
- MinGW 运行时（若使用 MinGW 编译）：LIBWINPTHREAD-1.DLL、LIBGCC_S_DW2-1.DLL、LIBSTDC++-6.DLL

2. Qt 插件的部署要求

所有 Qt GUI 应用都依赖实现 Qt 平台抽象层（QPA）的插件，Windows 平台对应的插件为 qwindows.dll，其他插件按需部署。

插件路径规则

插件类型	必需性	目标目录	示例
平台插件（QPA）	必选	`platforms/`	`platforms/qwindows.dll`
打印支持插件	可选（若应用需打印功能）	`printsupport/`	`printsupport/qwindowsprintersupport.dll`
图像格式插件	可选（若应用需处理特定图像格式）	`imageformats/`	`imageformats/qjpeg.dll`、`imageformats/png.dll`
SQL 驱动插件	可选（若应用需 SQL 功能）	`sqldrivers/`	`sqldrivers/qsqlmysql.dll`
应用自定义插件	可选（若应用使用自定义插件）	`plugins/`	`plugins/pnp_basictools.dll`

非可重定位构建（Non-Relocatable Builds）的插件路径配置

Qt 5.14 及以上版本中，若未通过 configure -relocatable 关闭“可重定位”，Qt 库默认支持重定位，插件搜索路径相对于 QtCore 库的位置，无需额外配置；若为非可重定位构建（即编译 Qt 时关闭了可重定位），需通过以下方式确保应用能找到插件：

使用 qt.conf 文件：推荐用于多个可执行文件共享同一组插件的场景，通过 qt.conf 配置插件搜索路径。
代码设置路径：推荐用于单个可执行文件的场景，

posted @ 2025-08-25 21:00 小小怪历险记阅读(102) 评论(0) 收藏举报

刷新页面返回顶部

柴新宇的博客