介绍

初学Qt时，发现程序可以编译成功但直接在文件夹中运行失败。这种情况几乎可以断定是 运行时环境 的问题，具体来说就是程序在运行时找不到必要的 Qt 动态链接库（DLL）。

问题原因分析

1. 编译成功：CMake 通过你指定的 Qt6_DIR 或类似的配置找到了 Qt 的库文件和头文件，因此能够正确编译和链接。
2. 运行失败：当运行生成的可执行文件（.exe）时，操作系统需要加载该exe所依赖的Qt DLL（如 Qt6Core.dll, Qt6Gui.dll, Qt6Widgets.dll 等）。系统会在 PATH 环境变量列出的目录中搜索这些DLL。
3. 环境变量未设置：因为你没有将Qt的二进制目录（包含这些DLL的目录）添加到系统的 PATH 变量中，所以系统找不到它们，导致弹出“找不到xxx.dll”的错误。

---

解决方案（从最佳实践到临时方法）

这里给你提供几种解决方案，推荐使用第一种或第二种。

方法一：使用 windeployqt 工具（最推荐、最规范）

这是 Qt 官方提供的部署工具，它会自动将程序运行所需的所有 Qt 依赖库、插件、翻译文件等复制到你的程序所在目录。这样你的程序就成为一个“便携”的版本，不再依赖系统 PATH。

操作步骤：

1. 编译你的项目（使用 CMake 和 Visual Studio 或 MinGW）。
2. 找到你的可执行文件（.exe），例如 build/Debug/MyApp.exe。
3. 打开 Qt 的命令行工具（最重要的一步！）：
   • 在开始菜单中找到类似 Qt 6.5.2 (MSVC 2019 64-bit) 这样的快捷方式并打开它。这会配置好当前命令行的环境，使其包含 windeployqt 工具和 Qt 的 PATH。
   • 如果找不到，你需要手动找到 windeployqt.exe 的路径，它通常在 Qt安装路径/版本/编译器/bin/ 下，例如 C:\Qt\6.5.2\msvc2019_64\bin。
4. 在打开的命令行中，导航到你的 exe 文件所在目录：

   cd C:\path\to\your\build\Debug
   

5. 运行 windeployqt 命令：

   windeployqt MyApp.exe
   

   • 如果是 Release 模式，可能需要加 --release 参数：windeployqt --release MyApp.exe
   • 如果程序还使用了其他模块（如 Qt Quick），可能需要额外参数，例如 --qmldir C:\path\to\your\qml\files 来部署 QML 相关文件。

执行完毕后，你会看到该目录下多了很多 Qt 的 DLL 和子文件夹（如 platforms, styles等）。现在再次双击运行你的 MyApp.exe，它应该就能正常启动了。

优点：一键部署，非常可靠，适合最终分发程序。
缺点：每次编译后如果需要测试，都要重新运行一次（可以写个CMake脚本或批处理文件来自动化这个过程）。

---

方法二：临时修改系统 PATH（适合开发调试）

在开发阶段，你可以临时为当前的命令行会话或IDE设置PATH，而不是永久修改系统环境变量。

对于命令行（CMD/PowerShell）：

1. 打开普通的命令行（CMD或PowerShell）。
2. 使用命令临时添加Qt的bin目录到PATH（请替换为你自己的路径）：
   • 对于 MSVC 编译器：

     set PATH=C:\Qt\6.5.2\msvc2019_64\bin;%PATH%
     

   • 对于 MinGW 编译器：

     set PATH=C:\Qt\6.5.2\mingw_64\bin;%PATH%
     

3. 然后在这个同一个命令行窗口中，导航到你的exe目录并运行它：

   cd build\Debug
   MyApp.exe
   

   这样程序就能找到DLL了。

对于IDE（如Visual Studio, CLion）：

你可以在IDE的运行/调试配置中直接设置环境变量。

1. 在 Visual Studio 中：项目属性 -> 调试 -> 环境，输入：

   PATH=C:\Qt\6.5.2\msvc2019_64\bin;%PATH%
   

2. 在 CLion 中：Edit Configurations -> 在 Environment 字段中添加：

   PATH=C:\Qt\6.5.2\msvc2019_64\bin;%PATH%
   

优点：适合快速调试，不影响整个系统。
缺点：每次新开一个命令行或IDE会话都需要重新设置。

---

方法三：将Qt目录永久添加到系统PATH（简单但不够灵活）

这是最直接的方法，但通常不推荐，尤其是如果你在系统上安装了多个Qt版本或多个编译器时，容易造成冲突。

1. 在Windows搜索框输入“环境变量”并打开“编辑系统环境变量”。
2. 点击“环境变量…”按钮。
3. 在“系统变量”部分，找到并选中 Path 变量，点击“编辑”。
4. 点击“新建”，然后将你的Qt二进制路径添加进去，例如：
   C:\Qt\6.5.2\msvc2019_64\bin
5. 点击“确定”保存所有更改。
6. 重要：你需要重启任何已经打开的命令行窗口或IDE，新的PATH设置才会生效。

之后，在任何地方运行你的Qt程序，系统都能找到DLL了。

优点：一劳永逸。
缺点：可能与其他软件或Qt版本冲突；污染了全局环境。