windeployqt.exe的使用與避坑(windows平臺)

左耳听风發表於2024-08-14

1. 介紹

windeployqt.exe是Qt自帶的工具,用於建立應用程式釋出包。 簡單來說,這個工具可以自動地將某程式依賴的庫、資源複製到其所在目錄,防止程式在其他電腦上執行報找不到庫的錯誤。 這裡貼上官方文件:https://doc.qt.io/qt-5/windows-deployment.html

本文適用於Windows + Visual Studio + Qt平臺。

2. 原理

windeployqt.exe工作原理很簡單,它會到當前的環境變數PATH配置的搜尋路徑中,查詢應用程式所需要的庫和資源,複製到應用程式目錄中。

3. 使用

1、先從開始選單中開啟對應版本的Qt命令列終端介面,如下圖:

2、命令列中輸入

windeployqt.exe 應用程式完整路徑

我們知道,Qt專案路徑不能包含中文,所以為了保險起見,應用程式路徑中不要包含中文。另外,如果應用程式路徑中包含空格,需要用雙引號將整個路徑字串包裹起來。

回車即可執行釋出命令。輸出介面如下圖所示:

進入到應用程式目錄可以看到,目錄中增加了很多依賴庫和資料檔案。如下圖所示:

大體上的流程只有這兩步。 整個釋出過程看似比較簡單,但是其中還是存在一些坑的。

3.1 坑點一:未使用Qt的命令列終端執行釋出命令,導致庫版本複製錯誤

下面是直接使用系統cmd命令列釋出軟體的過程:

直接開啟cmd命令列,進入到windeployqt.exe所在目錄 輸入:windeployqt.exe 應用程式完整路徑,回車。

這樣釋出出來的應用程式可能會崩潰或者出現以下問題

面對這個錯誤沒有經驗的話,很難解決,特別是軟體直接崩潰的話,更無從下手。要解決這個問題,估計至少要半天時間。

0xc000007b是一個經典錯誤,它代表著程式啟動時使用了不正確的版本的庫,導致無法正常執行。例如,64位的軟體使用了32位的庫。

所以,發生上面錯誤的原因是,windeployqt.exe從系統的環境變數路徑PATH中找到了其他版本的依賴庫,而這個依賴庫並不是我們的應用程式真正依賴的那個版本。當你的計算機中安裝了很多軟體,某些軟體會新增系統環境變數,指向自己的bin目錄;抑或是安裝了幾個版本的Qt開發環境時,難免會導致搜尋路徑中有同名稱的、不同版本的庫存在,這些情況下,庫版本錯亂的問題經常發生。

在Qt命令列中輸入 echo %PATH%,可以檢視當前Qt使用的環境變數:

上圖中紅色框內是此版本Qt的庫檔案目錄,已新增到當前PATH環境變數的最開頭,將會被windeployqt.exe優先搜尋到。如此一來,Qt相關的庫便不會產生庫版本錯誤的問題。

3.2 坑點二:未使用與Qt版本對應的windeployqt.exe

釋出軟體時,必須確定專案開發所使用的Qt版本,並使用此版本Qt安裝目錄下的windeployqt.exe完成釋出過程。每個Qt版本中的工具只有在此Qt版本下才能確保正常工作,混用會引入未知的風險。

3.3 坑點三:釋出時,預設檔案不會覆蓋

在Qt命令列終端中多次執行釋出命令時,已釋出到應用程式資料夾中的檔案預設不會被覆蓋。當你第一次釋出出問題時,調整好環境後再次釋出並不會覆蓋已存在的檔案。這可能和我們期望的不太一樣。可以透過新增強制覆蓋引數--force強制覆蓋已存在的檔案,如下圖所示:

建議始終新增--force引數,防止因檔案未覆蓋而出現問題。

3.4 執行庫問題

Qt命令列啟動時有一行提示:

上面打包輸出介面的紅框中,有這樣一行警告:

Warning: Cannot find Visual Studio installation directory, VCINSTALLDIR is not set.

意思是說,因為我們沒有執行vcvarsall.bat,所以VS的環境變數沒有配置好,所以不會複製VS相關的依賴庫。

vcvarsall.bat是VS的自帶的配置環境變數的批處理檔案。

在VS2015及更早VS版本下:

以VS2010為例,它位於路徑 C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC 下。它屬於VS命令列工具的一部分,這裡不多說,直接去看VS官網文件即可:透過命令列使用 Microsoft C++ 工具集

那我們就嘗試執行vcvarsall.bat來配置一下VS的環境。整個過程的完整操作過程介面如下:

可以看到,那一行警告不見了。同時,應用程式目錄下多了兩個庫檔案,如下圖:

【*************************************************************】

"D:\software\vs2022\IDE\VC\Auxiliary\Build\vcvars64.bat"

【*************************************************************】

這樣釋出出來的目錄就帶上了VS的依賴庫,複製到沒有安裝VS的電腦上亦可以執行。

VS2017及以後VS版本:

vcvarsall.bat的位置有所變動,一般在

C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build。

更高版本的VS在版本對應的目錄下即可找到。

通用方法

打包軟體時,附上對應版本的vcredist.exe微軟執行庫給使用者,使用者在使用軟體前,先安裝對應版本的微軟執行庫,程式依賴的執行庫就可以安裝到系統中,程式即可順利執行。

因為Qt Creator開發環境也是用Qt+VS開發的,所以Qt Creator安裝目錄下是帶有vcredist.exe微軟執行庫的,我們直接拿過來用即可。

4. 命令幫助

除本文提及的基本引數,釋出程式還提供了一些額外引數選項,可以透過檢視命令幫助瞭解。

在Qt命令列終端中輸入

windeployqt.exe -h

可以檢視命令幫助。

5. 結語

總體來說,雖然釋出步驟比較簡單,但是有坑有細節,自己嘗試操作幾次就能熟悉了。裡面的坑筆者踩過,會浪費很多時間,希望大家能避免踩坑,提高效率。

相關文章