📘 笔记一：在 VS2022 中开发 Qt 程序 -- 为什么需要 windeployqt 以及如何自动化
一、问题现象
在 Visual Studio 2022 中成功生成 Qt 程序（例如 Flex.exe）后：
-
在 VS 中点击"本地 Windows 调试器"运行，程序无法启动或闪退，没有 Qt 界面。
-
在文件资源管理器中直接双击
Flex.exe，提示缺少Qt5Widgets.dll、Qt5Gui.dll等。 -
但打开命令行，进入 exe 所在目录，执行
windeployqt Flex.exe后，再双击Flex.exe就能正常运行并显示 Qt 界面。
为什么？
二、根本原因：缺乏运行时依赖
Qt 程序在运行时不仅需要 exe 本身，还需要：
-
Qt 核心 DLL （如
Qt5Core.dll,Qt5Gui.dll,Qt5Widgets.dll） -
Qt 插件 （如
platforms\qwindows.dll） -
编译器运行时库 （如
vcruntime140.dll，通常系统已有）
Visual Studio 默认只会将项目直接生成的 .exe 放入输出目录（例如 Debug 或 Release），不会自动复制这些 Qt 依赖 。
因此直接运行 exe 会因找不到 DLL 而失败。
windeployqt 是 Qt 官方提供的部署工具，它能自动分析 exe 的依赖，并将所有需要的 DLL、插件、翻译文件等复制到 exe 所在目录，形成一个可独立运行的完整环境。
三、手动部署步骤
每次生成后手动执行以下步骤（确保 Qt 的 bin 目录在系统 PATH 中，或使用完整路径）：
cmd
cd /d "D:\你的项目输出目录\Release"
windeployqt.exe 你的程序名.exe示例（你的项目）：
cmd
cd /d D:\Project_Lh\flex_-master-driver-master\MasterDriver\x64\Release
D:\Qt\Qt5.14.2\5.14.2\msvc2017_64\bin\windeployqt.exe Flex.exe执行后，exe 所在目录会多出 Qt DLL 和 platforms 等文件夹，此时双击 exe 即可正常运行。
四、在 VS2022 中自动化部署（推荐）
避免每次手动执行，可以通过以下两种方式让 VS 在生成后自动运行 windeployqt。
方式一：后期生成事件（最简单）
-
在解决方案资源管理器中，右键点击你的 Qt 项目（如
Flex） → 属性。 -
转到 配置属性 → 生成事件 → 后期生成事件。
-
在 命令行 框中输入：
cmd
"$(QTDIR)\bin\windeployqt.exe" "$(TargetPath)"需要事先在 VS 中定义
QTDIR宏。通常在 Qt VS Tools 安装后会自动定义。若没有，可以写完整路径：
"D:\Qt\Qt5.14.2\5.14.2\msvc2017_64\bin\windeployqt.exe" "$(TargetPath)" -
点击 确定。以后每次生成成功后，都会自动部署依赖。
方式二：配置调试环境变量（仅便于调试）
如果你只想在 VS 中按 F5 调试时能正常启动，而不想复制文件到输出目录，可以设置调试环境的 PATH：
-
项目属性 → 配置属性 → 调试。
-
在 环境 栏中添加：
text
PATH=D:\Qt\Qt5.14.2\5.14.2\msvc2017_64\bin;%PATH% -
这样 VS 启动 exe 时会从这个路径查找 Qt DLL，但 exe 本身仍不能脱离 VS 独立运行。
推荐方式一，因为生成一次后，exe 目录就包含所有依赖，可以直接分发或双击运行。
五、常见问题与解决
| 问题 | 原因 | 解决方法 |
|---|---|---|
'windeployqt' 不是内部或外部命令 |
Qt bin 目录不在系统 PATH 中 | 使用完整路径调用（如 D:\Qt\...\windeployqt.exe） |
部署后依然缺少 qwindows.dll |
未正确复制 plugins 目录 | 手动复制 platforms 文件夹，或使用 windeployqt --plugins 选项 |
| 调试时 Qt 界面不显示（无报错） | 缺少平台插件 | 将 plugins\platforms 文件夹复制到 exe 同级的 platforms 目录；或在调试环境中设置 QT_PLUGIN_PATH 变量 |
| 多个 Qt 版本混用导致崩溃 | 项目中链接的 Qt 版本与 windeployqt 使用的版本不一致 | 确保使用完全相同的 Qt 路径（查看项目属性 → Qt Project Settings） |
六、总结
-
windeployqt是 Qt 程序真正能独立运行的关键一步，它把开发环境的依赖带到发布目录。 -
手动执行该命令是正确但繁琐的做法，通过后期生成事件在 VS 中自动运行，可以一次性解决问题。
-
理解 Qt 的部署机制，能避免大量"本地能跑，换台机器就崩"的尴尬。
将上述"方式一"配置好后，你只需要按 F5 或重新生成，就能得到可直接双击运行的完整程序包。