很多朋友问我在 Qt 里配置 MSVC2017 编译器的事说自己电脑上装的是 MinGW 版 Qt平时写写界面、串口、网络通讯都挺顺一旦要用 QtWebEngine、要用只有 MSVC 预编译的第三方库或者给客户交付时对方指定要 msvc2017_64 的构建就卡住了。去翻网上的教程几乎千篇一律让你“装一个 Visual Studio”然后一路下一步。可整套 VS 十几个 GB装完动辄半小时起步就为了拿一个 C 编译器怎么想都觉得亏。其实微软官方早就把 C 生成工具单独拆了出来名字叫 Build Tools里面就是编译器、Windows SDK 和调试工具没有臃肿的 IDE 界面Qt Creator 完全能靠它完成从编译、链接到调试的全流程。我重新把这条路完整走了一遍用的还是 2022 年当时能拿到的版本组合中间遇到的坑、跳过的坎都记在了这篇里算是一份保姆级备忘。1. 为什么非要 MSVCMinGW 用得好好的为什么要折腾1.1 MinGW 和 MSVC 是两套完全不同的生态很多人第一次接触 Qt 时官方安装包会默认引导装 MinGW 版本因为开箱即用、不需要额外装编译器新手期几乎感受不到“编译器”这个东西的存在。直到某一天你发现某个第三方库只有.lib .dll形式的 MSVC 版本没有.a .dll的 MinGW 版本或者你辛辛苦苦下载了 OpenCV 的 Windows 预编译包链接时报出一堆unresolved external symbol又或者你打开 Qt 安装器发现Qt WebEngine组件在 MinGW 系列下面根本没有对应项你才意识到事情没那么简单。根子在于 MinGW 和 MSVC 走的是两套完全不同的 ABI 体系。MinGW 是 GCC 在 Windows 下的移植自带 C 运行库用的是 POSIX 线程模型MSVC 是微软自家编译器依赖 vcruntime140、ucrtbase 这一套 Windows 系统级的 C/C 运行时。两者编译出来的二进制文件符号修饰规则、异常处理方式、结构体内存布局都不一致所以不能混着链接。Qt 官方为这两个阵营分别发布预编译二进制包因为底层编译器不同库本身也需要分别构建。很多时候“为什么非要 MSVC”并不是因为你个人喜好而是你被外部环境推着走的。比如 Qt 官方从 Qt 5.5 开始Chromium 内核的 QtWebEngine 模块就只提供 MSVC 构建版本让 MinGW 用户只能用回老的 WebKit又比如大部分工业相机 SDK、加密库、收费控件预编译包只发 MSVC 版。这一条就足够说服很多人老老实实把 MSVC 给配上。1.2 什么时候你完全不需要 MSVC讲到这里我反而要先泼一盆冷水如果你的项目是纯 QWidget 界面加上串口、Modbus、网络 TCP/UDP、SQLite 这类常规功能我建议继续用 MinGW没必要为了“追赶潮流”去装 MSVC。MinGW 版 Qt 的体积更小交叉编译到 Linux 也方便很多嵌入式上位机项目团队用的就是这套。真正需要加装 MSVC 的场景我总结下来基本是这几类项目里要引入 QtWebEngine / QtWebView 这类 Chromium 系模块需要调用第三方预编译 SDK且只提供 MSVC.lib版本比如 OpenCV、PCL、海康/大华相机 SDK客户或团队统一要求 MSVC 构建比如发版需要带微软符号的 dump 给调试你想用 CDB / WinDbg 来排查一些难以定位的内存问题你要用到某些只有 MSVC 才能正确编译的代码比如依赖 MSVC 特定扩展、需要在/Zc系列编译选项下才正常如果你的需求不在这些范围里那读完这篇之后知道“有这条路”就行不用急着折腾。但如果已经踩到上面的坑下面这套不装完整 VS 的方案就能帮你省至少 10 GB 磁盘空间和大量等待时间。2. 前置准备只装“生成工具”不装完整 IDE2.1 生成工具和完整 VS 到底差在哪这里要先分清两个东西“Visual Studio”和“Visual Studio Build Tools”。完整的 VS 是一个 IDE里面有代码编辑器、项目管理器、调试界面、各种插件系统当然也包含了 C 编译器。Build Tools 则是把 VS 里的 C 编译工具链单独抽出来做成的一个独立安装器没有图形 IDE装上之后你找不到多出来的“Visual Studio”启动图标但cl.exe、link.exe、nmake.exe、Windows SDK 头文件与库文件、CDB 调试器这些核心部件全都在。网上有些人分不清编译器和 IDE 的区别以为“装了 VS 才有 cl.exe”这其实是被完整版 VS 的一体化体验给惯出来的。实际上编译器就是几个 exeIDE 是壳子Build Tools 已经把壳子去掉了完全够一个 Qt 开发者使用。对比一下两者的安装差异会更直观对比项完整 Visual Studio CommunityVisual Studio Build Tools安装包体积数 GB 起步安装占用约 15-20 GB约 4-6 GB是否包含 IDE有无是否包含 C 编译器 cl.exe有有是否包含 Windows SDK可勾选可勾选是否包含 CDB 调试器需单独勾选需单独勾选是否适合 Qt Creator 配合使用可以完全没问题所以正确结论是面向 Qt 开发Build Tools 是性价比最高的选择。2.2 Qt 安装包准备以 5.14.2 离线包为例这一步的目标是确保你手头有一个 MSVC 版 Qt。Qt 官方安装包分为在线安装器和离线安装包2022 年时 5.14.2 离线包依然是最常见的选择因为它同时包含了 MSVC2017 32/64 位、MinGW 7.3.0 32 位等套件。如果你还没有 Qt可以先把离线包下载好在安装时勾选“MSVC 2017 64-bit”组件。注意这里说的组件是 Qt 库的预编译二进制不依赖你电脑上是否装了 MSVC 编译器所以这一步可以先做配不配得上编译器另说。我自己在实操时用的就是 Qt 5.14.2 msvc2017_64 这一套组合这也是当年很多工控、医疗、电力行业项目的常见搭配。如果你用的是 Qt 5.15 系列同样支持 MSVC2017但到了 Qt 6 时代官方默认不再提供 msvc2017 构建最低就是 MSVC2019 了所以老项目继续用 Qt 5.14/5.15 也是一个现实选择。2.3 只安装生成工具的具体步骤打开微软官方下载页面在“较旧的下载”区域找到“Visual Studio 2017 生成工具”的引导程序文件名是vs_buildtools.exe。这里有个细节2022 年时官网页面已经改版过很多次入口藏得比较深如果找不到 2017 版可以选择“Visual Studio 2017”下载页面下方的“生成工具”得到的就是同一个引导程序。拿到vs_buildtools.exe后强烈建议用命令行安装而不是直接双击走图形界面。图形界面很容易漏选组件而命令行方式可以把组件清单一次指定清楚步骤如下vs_buildtools.exe --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --add Microsoft.VisualStudio.Component.Windows10SDK.17763 --add Microsoft.VisualStudio.Component.Windows10SDK.18362 --passive --wait解释一下这几个参数的含义Microsoft.VisualStudio.Workload.VCTools是“使用 C 的桌面开发”工作负载安装它就会带上 MSVC 编译器、C 标准库、CMake 工具等。--includeRecommended会把工作负载里推荐的组件也一起装上避免后续因为缺某个小组件导致各种奇怪问题。Microsoft.VisualStudio.Component.Windows10SDK.17763和.18362分别是 Windows 10 SDK 的具体版本。Qt 5.14 官方构建基于较旧的 SDK 头文件装一个 17763 版本做兼容非常稳。如果界面安装你会看到一个组件树重点是把“Windows 10 SDK”和“Debugging Tools for Windows”都勾上。后者往往默认不选但它是 CDB 调试器的来源缺失的话后面 Qt Creator 里调试器一栏就会是空的。安装过程大约 10-20 分钟等它跑完。完成后在开始菜单里应该能看到“Developer Command Prompt for VS 2017”这个快捷方式打开后执行cl如果能打印出版本信息说明编译器工具链已经就位。提示如果你电脑里已经装了 VS 2019 或 VS 2022 的 Community 版本还有一个取巧办法——打开 Visual Studio Installer在“单个组件”里勾选“MSVC v141 - VS 2017 C x64/x86 生成工具”也能拿到 MSVC2017 工具链。但如果你没有装任何完整 VS直接走 Build Tools 最干净还能少装一堆用不到的东西。3. Qt Creator 里配置 MSVC2017编译器、调试器、Qt 版本一个都不能少3.1 自动检测常常比你想象的聪明如果你是在安装完 Build Tools 之后再第一次打开 Qt Creator通常 Qt Creator 会自动检测到 MSVC 编译器。打开“工具 → 选项 → Kits → 编译器”选项卡展开“Microsoft Visual C”分类应该能看到“MSVC 2017 64-bit (x86_64)”之类的条目这就是自动检测到的编译器。Qt Creator 的自动检测机制会去读注册表和 vcvarsall.bat 的位置比手动配置可靠得多。但很多时候用户是“先装了 Qt 和 Qt Creator后面才去装 Build Tools”或者“同时装了多个版本的 VS 工具集”自动检测有可能认不到或者认到了但指向的是 MSVC2019/2022。这时候就需要手动添加了。3.2 手动添加编译器路径务必精确到 cl.exe先说明我踩过的最大一个坑手动添加 MSVC 编译器时很多人不知道“编译器路径”到底该填什么级别。Qt Creator 里的“编译器路径”不是让你填 VS 的安装目录也不是让你填bin文件夹而是精确到cl.exe这个文件本身。拿我的环境举例在用 Build Tools 装完后cl.exe的完整路径是C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC\Tools\MSVC\14.16.27023\bin\Hostx64\x64\cl.exe注意几个细分点2017\BuildTools表示这是通过 Build Tools 安装的不是 Community/Professional 版。14.16.27023是 MSVC 2017 15.9 具体的小版本号具体数字可能因更新状态有所不同你在文件夹里点开Tools\MSVC后看到哪个14.x.x.xxxxx就用哪个。Hostx64\x64表示主机是 64 位目标也是 64 位。如果你的 Qt 装的是 32 位 msvc2017这里要选Hostx64\x86下的 cl.exe。在 Qt Creator 里操作时打开“工具 → 选项 → Kits → 编译器”点击右侧“添加 → Microsoft Visual C → C (适用于 x86 和 x64)”在弹出的界面里命名一个名字比如MSVC2017-64编译器路径就填上面那个 cl.exe 的完整路径。ABI 一栏让它自动生成通常会自动识别成x86-windows-msvc2017-pe-64bit如果不是改成这个格式。手动添加完成后Qt Creator 会尝试用这个编译器编译一个小的测试程序如果成功编译器条目前面的状态信号灯就会变成绿色。如果出现红色感叹号大概率是路径填错了或者 ABI 没选对。3.3 调试器配置CDB 是很多人容易漏的一环编译器和 Qt 版本都配好了结果打开 Qt Creator 发现 Kits 里调试器还是空的界面上那块区域是一个黄色感叹号。这是因为 MSVC 调试器默认用的是 Windows SDK 里的 CDBConsole Debugger而不是 MinGW 时代的 GDB。CDB 的典型路径是C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe如果你在安装 Build Tools 时忘了勾选“Debugging Tools for Windows”Debuggers这个文件夹根本不会出现。解决办法有两个一是重新运行vs_buildtools.exe在“单个组件”里找到“Debugging Tools for Windows”勾上修复安装二是直接下载 Windows SDK 独立安装包安装时只勾选“Debugging Tools for Windows”这一个功能。个人更推荐第二种因为不用再把所有组件扫一遍省时间。在 Qt Creator 里打开“工具 → 选项 → Kits → 调试器”点击“添加 → GDB/CDB 调试器”名字随便填路径指向cdb.exe。Qt Creator 会自动识别出其类型是“Windows Console Debugger”。3.4 Qt 版本页签一定要选 msvc2017_64 下的 qmake这一步看起来简单实际出错的频率极高。打开“工具 → 选项 → Kits → Qt 版本”这里 Qt Creator 默认会列出所有检测到的 qmake.exe。注意看路径别一顺手选成 MinGW 的 qmake。比如我装在 D 盘D:\Qt\Qt5.14.2\5.14.2\msvc2017_64\bin\qmake.exe和D:\Qt\Qt5.14.2\5.14.2\mingw73_64\bin\qmake.exe这两个 qmake 编译出来的代码是完全不同 ABI 的产物。如果你用 MinGW 的 qmake 去配合 MSVC 编译器构建时 Qt Creator 会报错说你选择的编译器和 Qt 版本不匹配典型提示是“The compiler xxx cannot produce code for the Qt version yyy”。所以这里必须明确选择 msvc2017_64 对应的 qmake。3.5 构建套件Kit三件套组合才是最终生效的配置编译器、调试器、Qt 版本这三个页签都配好了并不代表 Qt Creator 就已经能编译了最后一步是把它们组合成一个构建套件Kit。打开“工具 → 选项 → Kits → 构建套件”点“添加”命名一个名字比如MSVC2017-64然后在下拉列表里编译器C 和 C 都选MSVC2017-64调试器选刚才添加的 CDBQt 版本选Qt 5.14.2 (5.14.2) (msvc2017_64)CMake 工具如果你用 CMake 构建可让它自动选择或指向 Qt 自带的 CMake配完之后 Qt Creator 会对这个 Kit 做一次自动检测状态列显示为绿色勾或黄色感叹号。绿色基本就说明三件套匹配成功。3.6 用新建的 Kit 跑通第一个测试项目强烈建议在正式项目里直接使用前先新建一个“Qt Widgets Application”测试项目验证整个链路。新建项目向导最后一步会列出所有可用的构建套件确保勾选MSVC2017-64然后点击“构建”。如果一切顺利几秒钟后底部“编译输出”窗口会出现编译成功的日志并且项目目录里生成release\test.exe或debug\test.exe。这个测试项目的意义很大它验证了 cl.exe、CDB、qmake、Windows SDK 这一整条链路是通的之后你再把自己真正的项目切到 MSVC Kit 下大概率不会有大问题。如果连这么简单的 widget 程序都编不过也别急着排查大项目说明基础环节还有问题往下看我踩过的坑。4. 踩坑实录从“编译器未包含 main 类型”到黄色感叹号4.1 “编译器未包含 main 类型”多半是 Qt Creator 认错了编译器你可能在搜索框里见过“编译器未包含 main 类型”这个报错我第一次遇到时也是一头雾水。排查了一圈下来发现这个报错最常出现在手动添加编译器时路径填的不是cl.exe而是rc.exe、lib.exe或者干脆填到了bin目录。Qt Creator 拿这个不是 C 编译器的文件去尝试解析代码、判断代码里的 main 函数时自然一头雾水最后给出“编译器未包含 main 类型”这种绕口提示。遇到这个报错正确处理方式分四步回到“编译器”页签把所有状态不好的编译器条目删掉。重新添加编译器路径直接指向cl.exe本体不要指到目录更不要指到rc.exe。检查 ABI 是否与你的 Qt 位数一致。Qt 装的 msvc2017_64ABI 就选 64 位如果选了 32 位 ABI 配 64 位 qmake会报另一些莫名其妙的 ABI 相关错误。删除有问题的 Kit重建一个新的重新组合三件套。这里也提醒一句“编译器未包含 main 类型”还有一个变体是在构建项目时 Qt Creator 弹出“编译器无法为 Qt 版本生成代码”这种基本上就是 Kit 里把编译器的 ABI 位数和 Qt 版本搞反了处理思路是一样的。4.2 黄色感叹号和“找不到 cl.exe”配色完成后 Kit 列表里显示黄色感叹号把鼠标悬上去提示信息多半是“无法找到命令”。我遇到过好几次原因都出在 Build Tools 安装不完整上。一个比较隐蔽的情况是命令行安装时只写了--add Microsoft.VisualStudio.Workload.VCTools没有带--includeRecommended结果 SDK 和调试工具组件没装上。结果就是 cl.exe 虽然存在但 Windows SDK 的头文件或库文件缺失Qt Creator 在调用cl让编译器编译一个测试文件时找不到windows.h或kernel32.lib于是只能给个笼统的感叹号提示。解决办法是重新运行vs_buildtools.exe进入“修改”界面把“单个组件”里你能看到的 Windows 10 SDK、MSVC v141 工具集、Debugging Tools for Windows 都确认勾选再点修改。装完后重启 Qt Creator让自动检测重新扫描一遍。4.3 报错有“rc.exe”的身影SDK 路径问题这是 MSVC 构建中非常经典的一个坑。Qt 的 qmake 在链接资源文件时要调用rc.exeWindows Resource Compiler但这个工具位于 Windows SDK 目录下的bin\x64\rc.exe而不在 MSVC 的bin里。如果你的 SDK 安装不正常或者 Qt Creator 调用链传参时没有正确传递 SDK 的 bin 目录到 PATH 环境变量就会出现LNK1104: 无法打开文件 kernel32.lib或 “rc.exe not found” 之类的错误。处理方案是不要试图手动把 rc.exe 单独拷到某个目录而是修复 SDK 安装。重装 SDK 后重新构建测试项目Qt 的 qmake 脚本会负责调用 vcvarsall.bat 把正确的 PATH 设置好rc.exe 自然就能被找到。4.4 “unknown module in qt: serialport” 和编译器无关在搜索记录里还有一类高频问题Project ERROR: Unknown module(s) in QT: serialport。很多人把它当成编译器问题去折腾其实这是 Qt 组件缺失。Qt 的 Maintenancetool维护工具打开后勾选 “Qt Serial Port”把对应模块补装进来即可。这个问题和 MSVC、MinGW 都没有直接关系唯一的区别是MSVC 版 Qt 安装时组件列表里会多出一排 msvc2017_64 的模块项目别只勾了最基础的 base 然后骂编译器不给力。顺带说一个相关现象如果你的 Kit 里 Qt 版本错选了 MinGW 的 qmake而编译器是 MSVC你可能会在编译时遇到一些“不明所以”的错误比如cannot find -lQt5Core或者一堆头文件找不到。这其实不是模块缺失是 qmake 和编译器 ABI 不匹配。先回到 Kits 确认 Qt 版本是不是 msvc2017_64再考虑补模块。4.5 2022 年版本差异新版 VS 和旧工具集的兼容问题这篇教程的时间背景是 2022 年当时 Qt Creator 主流版本已经到 7.x/8.x对 MSVC2017 的自动检测依然支持良好。但如果你电脑上装的是 VS2022又想用 MSVC2017 的工具集通过 Visual Studio Installer 寻找“v141 工具集”时要注意组件列表里可能显示为“MSVC v141 - VS2017 C x64/x86 生成工具”。勾选这个组件VS2022 就能附带编译出 MSVC2017 ABI 的 cl.exe不需要额外装旧版完整 VS。不过这里有一个容易混淆的点用了 v141 工具集生成的二进制 ABI 是 MSVC2017 的可以匹配 msvc2017_64 的 Qt 库但如果你用了 VS2022 默认的 v143 工具集生成的就是 MSVC2022 ABI和 msvc2017_64 的 Qt 库不兼容链接时会报出一堆无法找到符号的错误。这也是很多“明明装了新版 VS 却还是配不了 Qt 5.14 MSVC 套件”的原因。5. 从这套配置里得到的核心经验整套流程走完我自己最大的感受是Qt 的编译器配置并没有想象中复杂难点基本集中在“ABI 是否匹配”和“组件是否装全”这两件事上。你只要记住一条主线MSVC 编译器必须搭配 MSVC ABI 的 Qt 库也就是带 msvc2017_64 字样的 qmake调试器要用 CDB 而不继续用 GDB编译器和调试器的来源都靠 Build Tools不需要为了 Qt 去装一个完整版 Visual Studio。在实际操作里我还遇到过一个小问题顺便分享如果你装的是 32 位 msvc2017 的 Qt那 cl.exe 要选Hostx64\x86这个目录下的版本。很多人看到 64 位宿主机下意识选 Hostx64 那个目录如果目标是 32 位会选到 Hostx64\x64 下的 cl.exe结果 x64 编译器尝试生成 32 位目标ABI 对不上Qt Creator 会提示架构不兼容。这时候别怪编译器坏了先看目标位数是不是一致。另外提醒一点Build Tools 安装完以后你可能发现开始菜单里没有独立的“编译器终端”图标。这是正常的Qt Creator 在构建时会自己加载 vcvarsall.bat 来初始化环境变量不需要你手动配置 PATH。所以千万不要为了“让 cl 命令能在 CMD 里用”去手动把 MSVC 的 bin 目录加进系统 PATH那样反而容易造成多个版本的工具链互相干扰最后搞得谁都用不了。如果你手头项目暂时没有用到 MSVC 的硬需求我也建议抽时间把这两三个小时投入在这个环境配置上因为 Qt 的整个生态里跨平台构建、三方库引入、崩溃 dump 分析迟早会把你推回到 MSVC 这条路上。提前把环境备好等真要用的时候直接切 Kit 构建比临阵磨枪从容得多。