Qt QML 打包终极指南：从“无法运行”到完美部署（附避坑全流程）

此问题是将 QML项目打包成可执行文件的时候出现的，现在已解决，下面复盘一下问题。

1.代码目录

2.main.cpp 代码

#include <QGuiApplication>
#include <QQmlApplicationEngine>

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

    QQmlApplicationEngine engine;
    QObject::connect(
        &engine,
        &QQmlApplicationEngine::objectCreationFailed,
        &app,
        []() { QCoreApplication::exit(-1); },
        Qt::QueuedConnection);
    engine.loadFromModule("HelloTestApp", "Main");

    return app.exec();
}

3.Main.qml 代码

import QtQuick

Window {
    width: 640
    height: 480
    visible: true
    title: qsTr("Hello World")
}

4.在Qt Creator 16.0.1 (Community)运行 hello 程序

效果图如下所示：

5.点击项目，查看构建的目录

通过查看，知道构建目录为：D:\C++-Projects\HelloTestApp\build\Desktop_Qt_6_9_0_MinGW_64_bit-Release

6.进入构建目录，复制exe程序

7.在某个盘新建一个文件夹，将复制的exe程序粘贴到新建的文件夹

现在，我们点击这个exe程序，还不能运行，缺少一些qt组件，报错截图如下所示：

所以，我们需要使用 qt 自带的工具进行打包。

8.使用qt工具进行打包

win+x，打开快捷菜单，如下图所示：

点击搜索，输入 qt，截图如下所示：

这里简单说一下，MinGW 和 MSVC的区别：

MinGW（Minimalist GNU for Windows）和 MSVC（Microsoft Visual C++）是 Windows 平台上两种主流的 C/C++ 编译器工具链，具体区别如下：

特性	MINGW	MSVC
编译器	GCC（开源）	微软私有编译器
运行时库	libstdc++（GNU 标准库）	MSVCRT（微软运行时）
部署依赖	自带运行时 DLL（绿色分发）	需用户安装 VC++ Redist 运行库
跨平台	✅ 代码兼容 Linux/macOS	❌ 仅限 Windows
性能优化	中等（通用优化）	⭐ 针对 Windows 深度优化（更快）
开发工具	Qt Creator / VSCode	⭐ Visual Studio（调试强大）
Qt 官方建议	✅ 支持（开源友好）	⭐ 首选（性能最佳）

💡 怎么选？

选 MinGW 如果：

需要免安装直接运行（复制 DLL 即可）

开发跨平台应用（一套代码编译多系统）

项目必须 100% 开源（避免许可证问题）

选 MSVC 如果：

追求最高性能（尤其大型项目）

需用 Visual Studio 高级调试工具

依赖仅支持 MSVC 的第三方库（如某些 SDK）

特别注意：

具体要使用哪种编译器工具链，取决于QT项目用的是 MinGW，还是 MSVC。像我这个项目，在Qt Creator 16.0.1 (Community)上编译用的是 MinGW，所以，我使用的也是MinGW来进行打包。

一般的打包命令，windeployqt 项目目录\xxx.exe,

我这里的打包命令：windeployqt D:\HelloTestApp\appHelloTestApp.exe

效果图如下所示：

ok,打包完成！！

9.找到问题的根源，问题解决

因为我们的项目是QML项目，也就是Qt Quick 程序（含 .qml文件），需要 QML 引擎和 Qt Quick 模块才能运行。

重新使用下面的命令进行打包：

windeployqt D:\HelloTestApp\appHelloTestApp.exe --qmldir D:\C++-Projects\HelloTestApp

windeployqt                     # Qt 官方部署工具
D:\HelloTestApp\appHelloTestApp.exe  # 目标可执行文件路径
--qmldir                        # 关键参数：指定 QML 文件目录
D:\C++-Projects\HelloTestApp    # QML 文件所在的项目源码目录（Main.qml所在的目录）