插件化那 20 天写的是"程序内部怎么长"。这个专栏换个角度——从一堆源码到一个能交给别人用的安装包，中间那些把人卡住的事。
开篇先解决最前面的一步：环境。去年我接手一个老项目，硬性要求Qt 5.12.11 + MSVC2017。照着网上的教程一步步装，结果 Qt Creator 里 Kits 一片红叉，编译报各种我搜都搜不到的错。前后把开发环境重装了三次才顺。下面这 8 个坑，每一个我都替你撞过了。
坑 1：Qt Creator 里 MSVC2017 的 Kit 是红的，编译器识别不到
这是我第一个晚上卡住的。Qt 装好了，打开 Creator，左侧"构建套件(Kit)“里那个MSVC 2017 64-bit是黄/红警告，点进去写的是"编译器未设置”。
我当时的第一反应是重装 Qt。没用。
真正的原因是VS2017 没装对组件。装 Visual Studio 时如果只勾了默认项，或者只勾了"通用 Windows 平台开发"，是没有 C++ 编译器的。cl.exe根本不在。Qt Creator 是通过扫 VS 的安装和vcvarsall.bat来找编译器的，找不到就红叉。
修法：打开 VS 安装器（Visual Studio Installer），在"工作负载"里勾上使用 C++ 的桌面开发，右侧确认MSVC v141 - VS 2017 C++ 生成工具（x64/x86）和Windows 10 SDK都选了。装完重启 Qt Creator，它会自动把编译器补上。
顺带一句：Qt 5.12 的官方预编译包就叫msvc2017_64，它对应的是MSVC 2017（v141 工具集）。别拿 MSVC 2019 甚至 2022 去编这个 Qt——工具集 ABI 不一定对得上，链接期或运行期给你脸色看。
坑 2：识别到了 32 位，没有 64 位；或者反过来
环境补了一轮之后，Creator 里出现了MSVC 2017 32-bit，但我要的 64 位还是空的。
原因是 v141 生成工具只装了 x86 那一档。Qt 5.12 的包是 64 位的（msvc2017_64），需要 64 位编译工具。回到 VS 安装器，把MSVC v141 - VS 2017 C++ x64/x86 生成工具那一项勾全（x64 和 x86 都要，工具链自己会用到 x86 的工具），再装一次。
确认办法：打开 “x64 Native Tools Command Prompt for VS 2017”，敲cl，能看到版本和x64字样，就对了。
坑 3：用 nmake 编译，慢，而且个别工程莫名其妙失败
Kit 绿了，开始编。项目是 qmake 工程，我习惯性地qmake && nmake。编是能编，但慢得离谱，而且有一个子工程每次都在链接阶段挂掉，报的路径错误我看了半天没看懂。
后来才知道Qt 官方推荐的是 jom，不是 nmake。jom 是 Qt 自己写的、兼容 nmake 语法的并行构建工具，能开多核。nmake本身不支持-j，而且在某些 qmake 生成的工程上确实会有路径/并行处理的坑。
修法：
qmake -r jom -j 8jom在 Qt 的Tools\QtCreator\bin或者单独下载的 jom 包里就有，加到 PATH 即可。编完之后速度差一个数量级，那个诡异的子工程也过了。
坑 4：__cplusplus永远是 199711L，三方库编译行为不对
这个坑藏得深。我项目里接了一个用#if __cplusplus >= 201703L做特性开关的库，在本机编得好好的，CI 上却表现不一样，部分if constexpr分支没生效。
查了半天才发现：MSVC 默认不更新__cplusplus宏的值。微软文档原话：
By default, Visual Studio always returns the value
199711Lfor the__cpluspluspreprocessor macro.
也就是说，哪怕你开了/std:c++17，不显式打开/Zc:__cplusplus，这个宏还是199711L。那个库是照标准宏写的，所以它在 MSVC 下永远走"旧标准"分支。
修法，在.pro里：
QMAKE_CXXFLAGS += /Zc:__cplusplus这样宏才会报 201703L（配合/std:c++17）。这个开关从 VS2017 15.7 开始有，正好在你这个版本里。
坑 5：Debug 版发给别人，一启动就报缺 MSVCP140D.dll
我有一次图省事，把 Debug 编出来的 exe 直接拷给同事测。他那边双击，弹窗"由于找不到 MSVCP140D.dll，无法继续执行"。
那个D是 Debug 的意思。Debug 构建动态链接的是Debug 版 C 运行库，普通机器上只装了 Release 的运行库（MSVCP140.dll不带 D）。所以 Debug 版本质上离不开你的开发机。
修法就一条：对外交付的必须是 Release 版。Debug 只在自己机器上调。如果你确实想静态链、免运行库，可以/MT，但 Qt 默认是动态链接的，要静态得自己编一份静态 Qt，坑比这个大得多，一般不值得。老实发 Release，让目标机装上对应版本的 VC++ 运行库（Qt 5.12 的 windeployqt 默认会把运行库一起复制，见坑 7）。
坑 6：Release 崩了，堆栈里全是问号，没法查
Release 发出去之后，有台机器偶发崩溃。我拿 dump 文件想看堆栈，结果函数名全是???，行号没有，PDB 找不到。
因为Release 默认不生成调试信息（PDB）。出了事你手里什么都没有，只能靠猜。
修法，在.pro里加：
CONFIG += force_debug_info或者在 MSVC 的编译选项里加/Zi并链接/DEBUG。这样 Release 也会带 PDB。PDB 你不一定要跟着安装包发出去，但留一份和那次发布 exe 完全对应的 PDB 存档，哪天崩溃了才能对照分析。我后来专门建了个目录按版本存 PDB，救过好几次火。
坑 7：windeployqt 跑完，到了别的机器还是崩 / 白屏
这是最常被人写错的一点。我见过不止一篇文章说"windeployqt 不复制 VC++ 运行库，目标机必须装 vcredist"——至少对 Qt 5.12 来说，这是错的。
我查了 Qt 5.12 的官方部署文档，原话有两层：
For Windows desktop applications, the required runtime files for the compiler are also copied to the deployable folder by default (unless the option
--no-compiler-runtimeis specified).
The application may require additional 3rd-party libraries (for example, database libraries), which arenot taken into account by windeployqt.
也就是说：
- VC++ 运行库，windeployqt 默认会复制（不想让它复制就用
--no-compiler-runtime，然后由你的安装包去装 vcredist）。所以"缺 MSVCP140.dll"一般不是 windeployqt 的锅。 - 真正的坑是第三方动态库它一个都不管。你项目里用到的数据库驱动、OpenSSL、还有你自己编的
.dll，windeployqt 完全不扫。这些得你手动拷进发布目录，缺一个就崩一个。 - 另一个我踩过的：必须用编你 exe 的那个 Qt 版本 / 位数去跑 windeployqt。拿 MinGW 的 windeployqt 去扫一个 MSVC64 的 exe，或者拿 32 位的去扫 64 位的，它会复制一堆根本不兼容的 DLL，放到目标机照样白屏。正确做法是直接拿你编译用的那个 Qt 安装目录下的
bin/windeployqt.exe。
平台插件qwindows.dll（在platforms/子目录里）windeployqt 默认会拷，所以"白屏"大概率是上面两条，而不是它漏了 Qt 自己的东西。
坑 8：项目路径带中文或空格，qmake / 脚本解析出错
最后这个坑低级但烦人。我把项目放在D:\工作\我的项目 2021\这种路径下，结果 qmake 生成的 Makefile 里路径被截断，编译命令行里空格把参数切开，一堆文件找不到。
修法很朴素：源码树放在纯英文、无空格的路径下，比如D:\work\myproject。不仅是你自己的代码，第三方库的源码路径也最好别有空格和中文，很多老构建脚本对空格的处理并不严谨。这一条改完，前面好几个"诡异"的失败也顺带消失了——它们根子都在路径。
我最后落地的环境清单
折腾完三次之后，稳定下来的是这一套：
- 系统：Windows 10 / 11 64 位
- Visual Studio 2017（15.x），工作负载"使用 C++ 的桌面开发"，含 v141 x64/x86 生成工具 + Windows 10 SDK
- Qt 5.12.11，
msvc2017_64套件 - Qt VS Tools（版本与 Qt 5.12 对应那一档，别用太新的去开老 .pro）
- jom（并行构建）
- 构建统一用
qmake -r && jom -j 8
下一篇写qmake / jom / 影子构建：怎么把"编译"这件事管起来，而不是每次都在工程目录里糊一团中间文件。
本篇属于「Qt 工程化实战」专栏 DAY 01。技术结论均对照官方文档：MSVC/Zc:__cplusplus默认行为见 Microsoft Learn；windeployqt 的运行时与第三方库处理方式见 Qt 5.12 部署文档。
