介紹

初學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版本沖突；污染了全局環境。