windeployqt 打包出错原因及解决

使用 windeployqt 打包发布 qt 程序时，在某些情况下会遇到程序在本机上可以运行，但是到了其它机器上却显示缺少各种 dll 文件的问题。研究了一下这个问题，详细记录在这里。

背景

windeployqt 说白了只是一个依赖文件的自动复制工具，本质上是先检测目标 exe 文件需要哪些依赖库，再将这些库文件复制到目标路径。

问题

在一些教程中（如这一篇百度搜索结果中的前排教程），推荐将 windeployqt.exe 所在目录（即 qt bin 目录）添加到系统环境变量 PATH 中，然后直接在 cmd 中直接使用 windeployqt PATH\TO\DST\qt_program.exe 来打包的方式。而这样做有时会导致打包的程序在本机可以运行，但是发布到其它机器却出现各种毛病。

原因

造成以上问题的根本原因是 windeployqt 在搜索文件时也是按照“先在运行程序当前所在的目录中搜索，如果找不到再依次到 PATH 收录的目录中寻找”的顺序来进行的。将 windeployqt 添加到 PATH 中直接调用的时候，所谓的“当前目录”并不是 qt 的 bin 根目录，而是 cmd 的当前目录。这个目录下显然不太可能找得到需要的 dll 文件，因此开始搜索 PATH。如果 PATH 中 qt bin 目录之前有其它目录存在同名的 dll 文件，程序就会错误地把这些 dll 复制过来。这些同名 dll 可能关联了本机其它库文件，因此在本机可以正常运行，而发布到其它机器上就会出错。

比如，在我的电脑上安装了 pyqt，而且 PATH 路径还排在了 qt 之前。pyqt 中也有很多 qt 相关的依赖库（Qt5Widgets.dll 等）这样打包得到的依赖库就被 pyqt 污染。

解决

如果简单地将 PATH 中 qt bin 移到最前面，可能又会污染其它程序（pyqt 等）的环境，因此不建议这么做。

这种情况不是每个人都会遇到的，如果不幸中招了，在打包的时候先将当前环境移动至 qt bin 目录，再调用 windeployqt，比如：

或者直接在 qt bin 路径下按住 Shift键，然后右键打开 PowerShell 输入对应命令：