Qt for Windows - 部署

本文檔介紹了適用于 Windows 系統(tǒng)的 Qt 應用部署流程。全文將以“Plug & Paint”示例應用為例，演示具體的部署步驟。

Windows 部署工具

Windows 部署工具 windeployqt 旨在自動化創(chuàng)建可部署文件夾的過程，該文件夾包含運行應用所需的 Qt 相關(guān)依賴項（庫、QML 導入文件、插件和翻譯文件）。它可為通用 Windows 平臺（UWP）創(chuàng)建沙箱環(huán)境，或為 Windows 桌面應用創(chuàng)建安裝目錄樹，這些內(nèi)容可輕松打包為安裝程序包。

工具位置與環(huán)境配置

• 工具路徑：該工具位于 QTDIR/bin/windeployqt 目錄下。
• 運行環(huán)境：需在構(gòu)建環(huán)境中運行才能正常工作。若使用 Qt 安裝程序，應通過腳本 QTDIR/bin/qtenv2.bat 配置構(gòu)建環(huán)境。

核心功能與工作原理

1. 依賴掃描：windeployqt 以 .exe 文件或包含 .exe 文件的目錄作為參數(shù)，掃描可執(zhí)行文件的依賴項。
2. QML 依賴處理：若通過 --qmldir 參數(shù)指定目錄，工具會使用 qmlimportscanner 工具掃描該目錄下的 QML 文件，識別 QML 導入依賴，并將所有已識別的依賴項復制到可執(zhí)行文件所在目錄。
3. 路徑修復：若 Qt 編譯時未啟用 configure -relocatable（即關(guān)閉“可重定位”），windeployqt 會將 Qt5Core.dll 中硬編碼的本地路徑替換為相對路徑。
4. 編譯器運行時文件：對于 Windows 桌面應用，默認情況下會將編譯器所需的運行時文件復制到可部署文件夾（除非指定 --no-compiler-runtime 選項）。若使用 Microsoft Visual C++ 編譯發(fā)布版本，這些文件包含 Visual C++ 可再發(fā)行組件包（VCRedist），供應用安裝程序在目標機器上遞歸安裝；其他情況下，則使用編譯器運行時的共享庫。

注意：應用可能依賴額外的第三方庫（如數(shù)據(jù)庫庫），windeployqt 不會處理這類依賴，需手動配置。

基本用法與命令選項

基本用法

1. 將 Qt 安裝目錄的 bin 文件夾（例如 <QT_DIR\bin>）添加到系統(tǒng) PATH 環(huán)境變量。
2. 運行以下命令（根據(jù)應用類型選擇）：
   • 普通應用：windeployqt <應用二進制文件路徑>
   • Qt Quick 應用：windeployqt --qmldir <應用QML文件路徑> <應用二進制文件路徑>

補充說明：若 ICU、ANGLE 等組件不在 bin 目錄中，需將其所在路徑添加到 PATH 環(huán)境變量。

常用命令選項

選項	功能描述
-?, -h, --help	顯示命令行選項幫助
--help-all	顯示包含 Qt 特定選項的完整幫助
-v, --version	顯示工具版本信息
--dir <directory>	使用指定目錄代替二進制文件所在目錄作為部署目標
--libdir <path>	將庫文件復制到指定路徑
--plugindir <path>	將插件復制到指定路徑
--debug	假設處理的是調(diào)試版本二進制文件
--release	假設處理的是發(fā)布版本二進制文件
--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。

靜態(tài)鏈接（Static Linking）

靜態(tài)鏈接會將 Qt 庫與應用打包為單個可執(zhí)行文件，無需在目標機器上額外部署 Qt 依賴庫，但無法部署插件。

1. 靜態(tài)編譯 Qt

需通過 configure -static 配置 Qt 靜態(tài)編譯，命令如下：

cd C:\path\to\Qt  # 進入 Qt 源碼目錄
configure -static <其他所需選項>  # 配置靜態(tài)編譯

注意：若需在同一目錄重新配置并編譯 Qt，需先進入構(gòu)建目錄，運行 nmake distclean（MSVC 編譯器）或 mingw32-make distclean（MinGW 編譯器）清除之前的配置痕跡，再重新執(zhí)行 configure。

2. 將應用鏈接到 Qt 靜態(tài)庫

以“Plug & Paint”示例應用為例，步驟如下：

1. 進入應用源碼目錄：

   cd examples\tools\plugandpaint
   

2. 清理舊構(gòu)建文件并生成靜態(tài)鏈接的可執(zhí)行文件：

   nmake clean  # 清理舊構(gòu)建（MSVC）；MinGW 用 mingw32-make clean
   qmake -config release  # 生成發(fā)布版本的 Makefile，指定鏈接靜態(tài)庫
   nmake  # 編譯生成靜態(tài)可執(zhí)行文件（MSVC）；MinGW 用 mingw32-make
   

3. 驗證與注意事項

• 驗證方法：將生成的 plugandpaint.exe 復制到未安裝 Qt 或 Qt 應用的機器上，運行以確認是否正常工作。
• 編譯器依賴：即使是靜態(tài)鏈接，應用若依賴編譯器特定庫（如 Visual C++ 運行時），仍需手動分發(fā)這些庫。可通過 depends 工具（依賴查看器）檢查應用依賴的庫。
• 插件限制：靜態(tài)鏈接方式無法部署插件，因此應用功能會因缺少插件而受限。若應用依賴插件，建議使用動態(tài)鏈接（共享庫）方式。

共享庫（Shared Libraries）

共享庫方式是 Qt 部署的默認方式，需將應用可執(zhí)行文件與 Qt 共享庫、插件等一同部署，支持插件功能，但需確保依賴文件路徑正確。

1. 編譯 Qt 共享庫（默認配置）

Qt 安裝時默認以共享庫模式構(gòu)建，假設 Qt 安裝在 C:\path\to\Qt 目錄。

2. 將應用鏈接到 Qt 共享庫

仍以“Plug & Paint”示例應用為例：

步驟 1：編譯應用核心可執(zhí)行文件

cd examples\tools\plugandpaint  # 進入應用目錄
nmake clean  # 清理舊構(gòu)建（MSVC）；MinGW 用 mingw32-make clean
qmake -config release  # 生成發(fā)布版本 Makefile（動態(tài)鏈接）
nmake  # 編譯生成動態(tài)鏈接的可執(zhí)行文件

步驟 2：編譯應用插件

cd ..\plugandpaint/plugins  # 進入插件目錄
nmake clean  # 清理舊插件構(gòu)建
qmake -config release  # 生成插件 Makefile
nmake  # 編譯插件，生成 pnp_basictools.dll 和 pnp_extrafilters.dll

成功編譯后，會得到：

• 應用可執(zhí)行文件：plugandpaint.exe
• 插件文件：pnp_basictools.dll（基礎工具插件）、pnp_extrafilters.dll（額外濾鏡插件）

3. 創(chuàng)建應用部署包

需將應用可執(zhí)行文件、Qt 依賴庫、插件、編譯器運行時等按特定目錄結(jié)構(gòu)組織，確保應用能找到所有依賴。

核心文件與目錄結(jié)構(gòu)

應用部署包需包含以下文件（以“Plug & Paint”為例），目錄結(jié)構(gòu)參考如下：

release/
├─ plugandpaint.exe  # 應用可執(zhí)行文件
├─ 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/     # 圖像格式插件目錄（可選，按需添加）
└─ ...               # 其他按需添加的插件目錄

需額外添加的文件

根據(jù)應用配置和依賴，可能需要添加以下文件：

依賴類型	所需文件	說明
編譯器運行時（Visual Studio）	vccorlib140.dll、vcruntime140.dll（C 運行時）、msvcp140.dll（C++ 運行時）	適用于 Visual Studio 14.0 (2015)、15.0 (2017)、16.0 (2019)，需與編譯時使用的編譯器版本一致
動態(tài) OpenGL（ANGLE）	libEGL.dll、libGLESv2.dll（ANGLE 庫）、d3dcompiler_XX.dll（HLSL 編譯器，XX 為版本號）、opengl32sw.dll（OpenGL 軟件渲染庫）	若應用使用動態(tài) 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()：在現(xiàn)有搜索路徑前添加自定義路徑，應用會優(yōu)先搜索該路徑。
• QCoreApplication::setLibraryPaths()：直接設置所有搜索路徑及順序，覆蓋默認路徑。

驗證部署包

將部署包解壓到未安裝 Qt 和編譯器的機器上，運行 plugandpaint.exe，確認應用可正常啟動且插件功能可用。

清單文件（Manifest Files）

使用 Visual Studio 編譯應用時，需額外處理清單文件，該文件記錄了應用對“并行程序集”（如編譯器運行時庫）的依賴信息。

1. 清單文件的復制與嵌入

• 應用清單：需將鏈接生成的應用清單文件（與 .exe 同名，擴展名為 .manifest）復制到可執(zhí)行文件所在目錄。
• DLL 清單：無需復制共享庫（DLL）的清單文件；若 DLL 的依賴與應用不同，需將其清單文件嵌入 DLL 二進制文件中。

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

Qt 提供以下 CONFIG 選項控制清單嵌入，默認均為啟用狀態(tài)：

• embed_manifest_dll：嵌入 DLL 清單。
• embed_manifest_exe：嵌入應用（EXE）清單。

若需禁用應用清單嵌入，在項目的 .pro 文件中添加：

CONFIG -= embed_manifest_exe

3. 編譯器運行時的正確部署

推薦通過以下方式在目標機器上安裝編譯器運行時：

1. 從 Visual Studio 安裝目錄（<Visual Studio install path>/VC/redist/<language-code>）獲取對應版本的可再發(fā)行組件包：
   • 64 位：vcredist_x64.exe
   • 32 位：vcredist_x86.exe
2. 將該組件包與應用安裝程序一同分發(fā)，并確保用戶安裝應用時自動執(zhí)行該組件包。

關(guān)鍵注意事項：發(fā)布的應用必須使用與編譯時完全相同的編譯器版本和 C 運行時版本，避免因運行時版本不匹配導致部署錯誤。

應用依賴項（Application Dependencies）

1. 額外庫的檢查與分發(fā)

應用可能依賴 Qt 之外的庫（如 ANGLE、ICU、OpenSSL 等），需通過工具檢查并手動分發(fā)：

• 檢查工具：使用 Dependency Walker（依賴查看器），命令為 depends <應用可執(zhí)行文件路徑>，該工具會列出應用依賴的所有庫（包括系統(tǒng)庫和非系統(tǒng)庫）。
• 示例（Plug & Paint 發(fā)布版本）：
  • 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 應用都依賴實現(xiàn) Qt 平臺抽象層（QPA）的插件，Windows 平臺對應的插件為 qwindows.dll，其他插件按需部署。

插件路徑規(guī)則

插件類型	必需性	目標目錄	示例
平臺插件（QPA）	必選	platforms/	platforms/qwindows.dll
打印支持插件	可選（若應用需打印功能）	printsupport/	printsupport/qwindowsprintersupport.dll
圖像格式插件	可選（若應用需處理特定圖像格式）	imageformats/	imageformats/qjpeg.dll、imageformats/png.dll
SQL 驅(qū)動插件	可選（若應用需 SQL 功能）	sqldrivers/	sqldrivers/qsqlmysql.dll
應用自定義插件	可選（若應用使用自定義插件）	plugins/	plugins/pnp_basictools.dll

非可重定位構(gòu)建（Non-Relocatable Builds）的插件路徑配置

Qt 5.14 及以上版本中，若未通過 configure -relocatable 關(guān)閉“可重定位”，Qt 庫默認支持重定位，插件搜索路徑相對于 QtCore 庫的位置，無需額外配置；若為非可重定位構(gòu)建（即編譯 Qt 時關(guān)閉了可重定位），需通過以下方式確保應用能找到插件：

1. 使用 qt.conf 文件：推薦用于多個可執(zhí)行文件共享同一組插件的場景，通過 qt.conf 配置插件搜索路徑。
2. 代碼設置路徑：推薦用于單個可執(zhí)行文件的場景，