windeployqt.exe的使用与避坑（windows平台）

介绍

windeployqt.exe是Qt自带的工具，用于创建应用程序发布包。
简单来说，这个工具可以自动地将某程序依赖的库、资源拷贝到其所在目录，防止程序在其他电脑上运行报找不到库的错误。
这里贴上官方文档：https://doc.qt.io/qt-5/windows-deployment.html

原理

windeployqt.exe工作原理很简单，它会到当前的环境变量PATH配置的搜索路径中，查找应用程序所需要的库和资源，拷贝到应用程序目录中。

使用

1、先从开始菜单中打开对应版本的Qt命令行终端界面，如下图：

2、命令行中输入

windeployqt.exe 应用程序完整路径

我们知道，Qt项目路径不能包含中文，所以为了保险起见，应用程序路径中不要包含中文。另外，如果应用程序路径中包含空格，需要用双引号将整个路径字符串包裹起来。

回车即可执行发布命令。输出界面如下图所示：

进入到应用程序目录可以看到，目录中增加了很多依赖库和数据文件。如下图所示：

大体上的流程只有这两步。
整个发布过程看似比较简单，但是其中还是存在一些坑的。

坑点一：未使用Qt的命令行终端执行发布命令，导致库版本拷贝错误

下面是直接使用系统cmd命令行发布软件的过程：

直接打开cmd命令行，进入到windeployqt.exe所在目录
输入：windeployqt.exe 应用程序完整路径，回车。

这样发布出来的应用程序可能会崩溃或者出现以下问题：

面对这个错误没有经验的话，很难解决，特别是软件直接崩溃的话，更无从下手。要解决这个问题，估计至少要半天时间。

0xc000007b是一个经典错误，它代表着程序启动时使用了不正确的版本的库，导致无法正常运行。例如，64位的软件使用了32位的库。

所以，发生上面错误的原因是，windeployqt.exe从系统的环境变量路径PATH中找到了其他版本的依赖库，而这个依赖库并不是我们的应用程序真正依赖的那个版本。当你的计算机中安装了很多软件，某些软件会添加系统环境变量，指向自己的bin目录；抑或是安装了几个版本的Qt开发环境时，难免会导致搜索路径中有同名称的、不同版本的库存在，这些情况下，库版本错乱的问题经常发生。

在Qt命令行中输入 echo %PATH%，可以查看当前Qt使用的环境变量：

上图中红色框内是此版本Qt的库文件目录，已添加到当前PATH环境变量的最开头，将会被windeployqt.exe优先搜索到。如此一来，Qt相关的库便不会产生库版本错误的问题。

坑点二：未使用与Qt版本对应的windeployqt.exe

发布软件时，必须确定项目开发所使用的Qt版本，并使用此版本Qt安装目录下的windeployqt.exe完成发布过程。每个Qt版本中的工具只有在此Qt版本下才能确保正常工作，混用会引入未知的风险。

坑点三：发布时，默认文件不会覆盖

在Qt命令行终端中多次执行发布命令时，已发布到应用程序文件夹中的文件默认不会被覆盖。当你第一次发布出问题时，调整好环境后再次发布并不会覆盖已存在的文件。这可能和我们期望的不太一样。可以通过添加强制覆盖参数–force强制覆盖已存在的文件，如下图所示：

建议始终添加–force参数，防止因文件未覆盖而出现问题。

细节问题

Qt命令行启动时有一行提示：

上面打包输出界面的红框中，有这样一行警告：

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

意思是说，因为我们没有运行vcvarsall.bat，所以VS的环境变量没有配置好，所以不会拷贝VS相关的依赖库。

vcvarsall.bat是VS的自带的配置环境变量的批处理文件。以VS2010为例，它位于路径 C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC 下。它属于VS命令行工具的一部分，这里不多说，直接去看VS官网文档即可：通过命令行使用 Microsoft C++ 工具集。

那我们就尝试运行vcvarsall.bat来配置一下VS的环境。整个过程的完整操作过程界面如下：

可以看到，那一行警告不见了。同时，应用程序目录下多了两个库文件，如下图：

这样发布出来的目录就带上了VS的依赖库，拷贝到没有安装VS的电脑上亦可以运行。

命令帮助

除本文提及的基本参数，发布程序还提供了一些额外参数选项，可以通过查看命令帮助了解。

在Qt命令行终端中输入

windeployqt.exe -h

可以查看命令帮助，如下图所示：

限于篇幅，这里不再进一步讲解，大家可以自己动手尝试。

结语

总体来说，虽然发布步骤比较简单，但是有坑有细节，自己尝试操作几次就能熟悉了。里面的坑笔者踩过，会浪费很多时间，希望大家能避免踩坑，提高效率。

本文原创首发于公众号/头条号 Qt未来工程师。