Qt Creator自动部署：用windeployqt告别DLL缺失烦恼

做 Qt 桌面开发，最怕的一件事不是需求变来变去，而是代码在你自己机器上跑得好好的，打包发给别人，人家双击就弹“缺少 Qt5Core.dll”，或者干脆闪退没反应。这些年我见过太多同行在自己机器上跑得飞起，一打包就翻车的案例，绝大多数问题都出在部署环节。Qt 应用不像一个简单 exe 那样拷走就能跑，它背后是一整套运行库、平台插件、图片格式插件、翻译文件、QML 组件，手动一个个找出来再拷过去，效率极低还容易漏。Qt 官方其实提供了一个相当好用的工具 windeployqt，它能自动站在你的 exe 上分析依赖，把需要的 Qt 组件全部收集到输出目录。不过这工具默认是一行命令手动敲，手动敲就容易忘，忘了就翻车。这篇文章就是教你把 windeployqt 配置进 Qt Creator 的构建流程，实现“构建完自动部署”，从此告别部署焦虑。内容覆盖原理、配置步骤、脚本方案和常见坑位，适合所有正在用 Qt Creator 做 Windows 桌面 Qt 开发的朋友直接参考。

1. 先搞清楚 windeployqt 在帮你干什么

1.1 它到底收集哪些文件

用一个生活类比：你开了一家餐馆，一张菜单背后是后厨几十种调料和食材。Qt 程序就像这份菜单，exe 只是一个“菜品展示单”，真正跑起来要依赖 Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll 这些“后厨食材”，还要有 platforms 目录里的 qwindows.dll 这个“厨师”，以及 imageformats 里面的各种“参考帮手”。windeployqt 做的事情，就是对着你的 exe 做一次“后厨清点”，把所有它认识的关联文件全部搬到指定目录。

它收集的东西包括：

• Qt 核心运行库，比如 Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll，如果你的程序用了网络、SQL、多媒体等模块，也会把对应的模块 dll 一并拷出。
• 平台插件，主要是 platforms/qwindows.dll，这个文件缺失会导致程序在 Windows 上“闪退”或者提示无法启动。
• 样式插件，比如 styles 目录下的各类风格 dll。
• 图片格式插件，比如 imageformats 目录里的 qjpeg.dll、qgif.dll、qico.dll、qsvg.dll，它们是 Qt 运行时能加载多种图片格式的关键。
• 翻译文件，如果不加 --no-translations 参数，它会打包一堆 .qm 文件。
• 编译器运行时，比如 MinGW 的 libgcc_s_seh-1.dll、libstdc++-6.dll、libwinpthread-1.dll，或者 MSVC 对应的运行时组件。
• QML 相关依赖，配合 --qmldir 参数，它能把 QtQuick 的模块、插件、QML 导入文件一并收集。

所以 windeployqt 本质上是一个“依赖收集器”，它不像简单的复制工具那样只知道把文件复制过去，而是会读取 exe 的 PE 头，一层层分析链接依赖，再按依赖关系拉取对应的 Qt 模块。这也是为什么它比你手动拷贝“聪明”得多。

1.2 每次都手动执行，到底有多痛苦

windeployqt 好用是好用，但如果每次都手动打开命令行执行，你会面临一连串问题：

• 每次都要翻 Qt 安装路径，脑记 C:\Qt\5.15.2\mingw81_64\bin\windeployqt.exe 这种长串地址。
• 参数记不全，今天用 --release，明天忘了加 --no-opengl-sw，部署出来的产物忽大忽小，缺这个缺那个。
• 构建完顺手就关了 Qt Creator，压根没想起来部署这一步。
• 团队里每个人手动执行的命令还不一样，有人加了 --compiler-runtime，有人没加，最后出的安装包在别人机器上表现不一致。
• 多个项目、多个 Qt 版本之间来回切换时，特别容易用错版本的工具，部署结果千奇百怪。

这些痛点不是理论上的，我在实际项目里全都踩过一遍。后来我开始琢磨：既然 Qt Creator 本身就支持自定义构建步骤，为什么不直接把部署动作绑进构建流程呢？这也是“自动部署”这个需求的来源。

1.3 自动部署到底要解决什么问题

自动部署的目标很明确：每次构建成功之后，构建目录或指定的发布目录里已经躺着一个可以直接打包分发、拷到别的电脑就能运行的完整产物。从“写代码-点击构建-收工”变成“写代码-点击构建-得到可发布包”，中间所有需要手工干预的部署环节全部消灭。

它还能统一团队环境。把部署逻辑沉淀成脚本或构建配置之后，不同同事拉下同一份代码，构建出来的可部署目录结构完全一致。这对于后面接 CI/CD 自动化流水线也是打基础。这套配置适用面很广：Qt Widgets 应用、QML/Quick 应用、桌面工具，只要最终目标是 Windows 桌面分发，都可以用同一套思路做。

2. 配置前的准备：先把工具和参数理顺

2.1 一个关键问题：你的 windeployqt 到底在哪

不同 Qt 版本、不同编译器渠道，windeployqt 的路径会有差异，不过规律是固定的：它永远在 Qt 安装目录下对应 Kit 的 bin 文件夹里。比如：

• Qt 5.15.2 + MinGW 64-bit：C:\Qt\5.15.2\mingw81_64\bin\windeployqt.exe
• Qt 6.5.3 + MinGW 64-bit：C:\Qt\6.5.3\mingw81_64\bin\windeployqt.exe