Qt5.12 + MSVC2017 环境搭建：我重装了三次才顺，这 8 个坑你不用再踩

插件化那 20 天写的是程序内部怎么长。这个专栏换个角度——从一堆源码到一个能交给别人用的安装包中间那些把人卡住的事。开篇先解决最前面的一步环境。去年我接手一个老项目硬性要求Qt 5.12.11 MSVC2017。照着网上的教程一步步装结果 Qt Creator 里 Kits 一片红叉编译报各种我搜都搜不到的错。前后把开发环境重装了三次才顺。下面这 8 个坑每一个我都替你撞过了。坑 1Qt 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 2017v141 工具集。别拿 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 value199711Lfor the__cpluspluspreprocessor macro.也就是说哪怕你开了/std:c17不显式打开/Zc:__cplusplus这个宏还是199711L。那个库是照标准宏写的所以它在 MSVC 下永远走旧标准分支。修法在.pro里QMAKE_CXXFLAGS /Zc:__cplusplus这样宏才会报 201703L配合/std:c17。这个开关从 VS2017 15.7 开始有正好在你这个版本里。坑 5Debug 版发给别人一启动就报缺 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。坑 6Release 崩了堆栈里全是问号没法查Release 发出去之后有台机器偶发崩溃。我拿 dump 文件想看堆栈结果函数名全是???行号没有PDB 找不到。因为Release 默认不生成调试信息PDB。出了事你手里什么都没有只能靠猜。修法在.pro里加CONFIG force_debug_info或者在 MSVC 的编译选项里加/Zi并链接/DEBUG。这样 Release 也会带 PDB。PDB 你不一定要跟着安装包发出去但留一份和那次发布 exe 完全对应的 PDB 存档哪天崩溃了才能对照分析。我后来专门建了个目录按版本存 PDB救过好几次火。坑 7windeployqt 跑完到了别的机器还是崩 / 白屏这是最常被人写错的一点。我见过不止一篇文章说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、还有你自己编的.dllwindeployqt 完全不扫。这些得你手动拷进发布目录缺一个就崩一个。另一个我踩过的必须用编你 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 201715.x工作负载使用 C 的桌面开发含 v141 x64/x86 生成工具 Windows 10 SDKQt 5.12.11msvc2017_64套件Qt VS Tools版本与 Qt 5.12 对应那一档别用太新的去开老 .projom并行构建构建统一用qmake -r jom -j 8下一篇写qmake / jom / 影子构建怎么把编译这件事管起来而不是每次都在工程目录里糊一团中间文件。本篇属于「Qt 工程化实战」专栏 DAY 01。技术结论均对照官方文档MSVC/Zc:__cplusplus默认行为见 Microsoft Learnwindeployqt 的运行时与第三方库处理方式见 Qt 5.12 部署文档。