Qt Quick 桌面應用程式部署完整指南：從開發到跨平台發布

Qt Quick 桌面應用程式部署完整指南

Qt 5 時代全面推廣 Qt Quick (QML) 技術，但桌面應用部署仍讓許多開發者踩坑。本文以實戰經驗為基礎，詳解 windeployqt 工具使用、依賴項自動收集、跨平台發布關鍵點，並針對 Windows XP 相容性、模組依賴缺失等常見問題提供解決方案。

專案建立與基礎配置

1. Qt Creator 中建立 Qt Quick Application 專案 (如 TestQtQuickApp)
2. 預設配置即可，確保專案在開發環境正常執行
3. 啟用 Release 模式 建置

核心部署步驟：windeployqt 自動化收集依賴

在 Qt Creator 專案模式下：

1. 點選左側 專案 圖示 → 建置步驟
2. 在 部署 區域勾選 windeployqt 選項
3. 點擊右下角小三角展開，確保勾選 QML 支援 相關選項
4. 建置專案，輸出目錄將自動包含 Qt 核心庫、QML 引擎、插件等依賴

實戰踩坑與解決方案

問題 1：Windows XP 上啟動報錯 msvcrt.dll 缺少 vsprintf_s

現象：目標機器為 Windows XP，雙擊執行檔彈出動態連結庫錯誤對話框，但點擊確定後程式仍能啟動。

原因：VS 2015+ 執行期庫預設使用 vsprintf_s 等安全函式，XP 系統 msvcrt.dll 版本過舊不支援。

解決方案：

• 專案 .pro 檔加入：QMAKE_CXXFLAGS += /D_USING_V110_SDK71_ (使用 VS2012 工具集)
• 或安裝 Visual C++ Redistributable for Visual Studio 2015-2022 並確保目標機已更新 KB2533623 補丁
• 長期建議：放棄 XP 支援，專注 Win7+ 現代系統

問題 2：部署後介面空白、QML 模組載入失敗

現象：windeployqt 處理後，目標機雙擊執行檔視窗打開但無內容、或報錯 module not found。

根因：windeployqt 僅掃描靜態引用，動態載入的 QML 模組 (如 QtQuick.LocalStorage 依賴 Qt5Sql.dll) 會被遺漏。

解決方案：在 main.cpp 显式引入所需模組，強制連結器保留相關符號：

// main.cpp
#include 
#include 
#include         // 強制連結 Qt5Sql.dll
#include     // 強制連結 Qt5Network.dll
// ... 其他動態使用的模組

int main(int argc, char *argv[]) {
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    return app.exec();
}

.pro 檔同步添加：

QT += quick sql network   // 確保編譯時連結對應庫

跨平台部署對照表

實戰驗證：Qt 5.5 Planets 範例在 Windows XP 上運行

經上述配置後，官方 planets 範例 (含 OpenGL 場景、粒子系統、QML 動畫) 成功在 2006 年購置的 Windows XP 機器上流暢運行，證明方案可行性。

# 部署腳本範例 (Windows 批次檔)
windeployqt --qmldir ..\qml --release TestQtQuickApp.exe
copy Qt5Sql.dll release\
copy Qt5Network.dll release\
# 打包發布

最佳實踐總結

1. 開發階段：main.cpp 顯式 #include 所有動態使用的 Qt 模組
2. 建置階段：啟用 windeployqt 自動收集，手動補充遺漏 DLL
3. 測試階段：在乾淨虛擬機 (無 Qt SDK、無 VS Runtime) 完整測試
4. 發布階段：製作安裝包、數位簽名、自動更新機制

Qt Quick 部署核心在於 依賴完整性 與 目標環境相容性。掌握 windeployqt 機制、理解 QML 動態載入特性，配合持續整合自動化測試，即可實現專業級桌面應用交付。