用Qt做Windows桌面开发的朋友应该都碰到过这种场面官网下载Qt时默认给你的是MinGW版编译器日常写个小工具、跑个Demo都挺顺手。结果有一天你要用某个第三方库或者接手一个同事留下的老项目对方甩过来一句话“这个库是MSVC编译的你这边工具链得切成MSVC2017。”这时候人就有点懵。装完整版Visual Studio好几个GB起步光是为了一个编译器就拖一个IDE下来怎么看都亏。这篇教程解决的正是这个问题不安装完整版VS通过微软官方的Build Tools单独装MSVC2017编译工具链然后把这个编译器加到Qt Creator里正常创建MSVC2017的构建套件Kit编译运行都没问题。整个过程我已经完整走过一遍按步骤来基本不会再被“编译器未包含main类型”之类的报错卡住。1. 先把思路理清楚为什么要MSVC2017凭什么能不装完整VS1.1 什么时候你会碰到“必须上MSVC”的硬需求很多人一开始接触Qt时装的是官方在线安装包里的MinGW版本。MinGW在Windows上用起来确实省心因为Qt Creator自带编译器装完就能跑。但等你的项目变得复杂之后MSVC就绕不开了。比如第三方C库只提供了MSVC编译好的静态库或动态库.lib/.dll这类库跟MinGW的二进制格式不兼容硬链接会直接报一堆unresolved symbol。公司内部的旧项目、或客户给的源码Makefile和构建逻辑都是按MSVC工具链写的。需要调试Windows底层API、调用DirectX或Windows SDK里一些特性MSVC环境最顺。要发布给其他Windows用户使用MSVC编译出的程序在兼容性上通常更稳特别是涉及系统底层库和UCRT运行环境时。在Qt的MSVC版本阵营里MSVC2017对应的是微软Visual Studio 2017版本的C编译器工具集v141。很多老项目、老库甚至部分嵌入式SDK都默认按这个工具集来编译所以“添加MSVC2017编译器”这个需求才一直有人搜。1.2 “不装完整VS”到底是怎么做到不装完整VS的这是这篇教程的核心微软其实提供了一个独立的安装载体叫Visual Studio Build Tools生成工具。它跟完整版Visual Studio IDE是分离的只包含命令行编译器、Windows SDK、各种构建组件没有Visual Studio那种图形界面开发环境。打个比方完整版VS相当于一间精装修的工作室编辑器、调试器、插件、代码高亮全给你配齐。而Build Tools就像是把这间工作室里的“工具房”单独拆出来只给你锤子、电钻和一堆螺丝刀。你做Qt开发反正已经有了Qt Creator当IDE缺的就是这间工具房里的MSVC工具集。所以这条路是行得通的而且是很正规的微软官方方案。下面我按实际操作的顺序把每一步细节和容易踩的坑都写出来。2. 开始前的版本匹配与系统准备2.1 Qt版本和MSVC2017怎么配对先说明一个容易混淆的地方Qt官方在提供预编译安装包时通常会标注编译器类型比如msvc2017_64、mingw73_32、msvc2019_64。如果你的Qt是msvc2017_64那对应的就是MSVC2017工具链如果是msvc2019_64那就需要MSVC2019或更高版本的工具集。在操作之前先去看一眼你Qt安装目录下的文件夹名。一般在安装路径里比如D:\Qt\Qt5.14.2\5.14.2\下能看到msvc2017_64之类的目录。如果你手上的Qt安装包是MinGW版本那这篇教程不适用你需要先去下载对应版本的MSVC版Qt。很多人踩过这个坑装了一个MinGW版Qt然后又去折腾MSVC编译器结果Qt Creator里怎么配都不对因为编译器类型和Qt库本身就不匹配。就好比你拿着美国插头的电器硬往中国插座里怼物理上就不兼容。2.2 老规矩把系统环境先理顺安装前还有几个前置条件虽然不复杂但漏掉一个后面就得回来补确保系统是64位的Windows大多数场景都是这个32位系统的话要另行选择对应32位工具链。安装前清一下Qt Creator的缓存和临时配置防止旧的编译器检测结果干扰新添加的MSVC2017。建议暂时关闭实时保护的杀毒软件或把安装目录加入白名单Build Tools安装过程中会生成很多临时文件个别安全软件会误删关键组件导致后面编译器不可用。记录一下系统当前有没有安装过其他版本的Visual Studio或Build Tools这个东西跟多个VS版本其实可以共存但为了避免新装的2017工具链被混淆最好心里有数。我把版本对应关系整理成一张表方便对照Qt版本后缀对应编译器工具集版本号本教程是否适用msvc2017_64MSVC2017 64位v141适用msvc2017_32MSVC2017 32位v141适用选择x86架构即可msvc2019_64MSVC2019 64位v142不适用需装2019工具集msvc2015_64MSVC2015 64位v140不适用需装2015工具集mingw73_32MinGW无不适用需换MSVC版Qt如果你的Qt安装包本身就是msvc2017_64那么恭喜你只需要把工具链配置对就可以直接编译。如果你发现自己的Qt是msvc2019_64也可以参考本文思路改成安装MSVC2019的Build Tools原理完全一样。3. 保姆级实操从零装好MSVC2017工具链3.1 下载并安装Visual Studio Build Tools我先说结论虽然MSVC2017对应的工具集版本很老但微软官方并没有把这条路堵死。最省事的方式是下载Visual Studio 2017版本的Build Tools安装器用这个安装器单独安装C工具链。实际操作步骤打开微软官网的Visual Studio旧版本下载页面找到“2017”标签下的“Build Tools”下载项。这里注意不要下成完整版Visual Studio社区版那个会附带一大堆IDE组件认准名字里带Build Tools的离线安装包确保是vs_BuildTools.exe。下载完成后右键选择“以管理员身份运行”。这一步很关键因为安装过程要写入系统环境变量和注册表信息非管理员权限容易半路失败。安装界面启动后注意看“工作负载”选项卡勾选“使用C的桌面开发”。右侧的“安装详细信息”面板里展开“MSVC v141工具集”节点确认以下子组件都被勾上通常默认真没问题“编译器MSVC v141”、“Windows 10 SDK”、“Windows SDK和VS的调试工具”。右下角设置好安装路径尽量选一个纯英文路径比如D:\VS2017BuildTools避免中文字符带来的工具链识别问题。点击“安装”然后等着。这个过程大概需要下载1GB到几GB不等取决于你选择的组件取决于网速快的话十几分钟慢的话可能得等一会儿。这里有一个很容易误会的地方我问过很多朋友他们以为勾选的“使用C的桌面开发”里包含了Visual Studio IDE其实不会。Build Tools安装器本来就是独立产品装完以后你只能从命令行调用MSVC不会多出一个Visual Studio图标这正好符合“不装完整VS”的需求。如果你手头下载不到2017版安装器还有一个替代方案用Visual Studio 2022或2019的Build Tools安装器在“单个组件”标签里勾选“MSVC v141工具集”。微软在新版Build Tools里依然保留了老工具集的可选组件安装完后同样能得到MSVC2017编译器。这个方案我实测过编译器识别和Qt Creator的Kit匹配都没问题。3.2 验证工具链是否装成功安装完成后先别急着打开Qt Creator先在命令行里验证一下编译器是否真的能用这样遇到问题可以少走一半弯路。找到编译器核心程序cl.exe的目录。以VS2017 Build Tools为例默认路径类似C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC\Tools\MSVC\14.16.27023\bin\Hostx64\x64\cl.exe注意这个路径里的版本号14.16.27023可能因你安装的具体补丁日期不同而变化找目录时按实际版本号匹配就好。然后打开一个管理员权限的命令提示符窗口执行以下操作来加载MSVC编译环境call C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC\Auxiliary\Build\vcvars64.bat执行完这条命令后输入以下命令查看版本cl如果看到一堆以“用于 x64 的 Microsoft (R) C/C 优化编译器”开头的版本信息说明工具链没问题。如果提示“不是内部或外部命令”说明环境变量没加载对或者cl.exe路径不对。这一步强烈建议不要跳过因为很多人在Qt Creator里配置了半天都是红叉最后发现其实是工具链自己就没装好压根不是配置的问题。4. 在Qt Creator里添加MSVC2017编译器并配置Kit4.1 添加编译器路径填对就是成功的一半现在打开Qt Creator按照下面步骤走菜单栏选择“工具” - “选项”。左侧找到“Kits”选项卡顶部切到“编译器”子页。点击右下角的“添加”按钮在下拉列表里选择“MSVC” - “C” - “Microsoft Visual C Compiler 14.16 (x64)”具体名称取决于Qt Creator识别到的工具集版本。在弹出的编译器配置页面中重点填写以下内容名称随意建议写“MSVC2017 64bit”方便自己认。编译器路径必须指向刚才那个cl.exe文件的完整路径。千万不能填成vcvarsall.bat或者Visual Studio安装目录的根路径Qt Creator要的是真正的编译器可执行文件。根据你的需要选择ABI。如果你要编译msvc2017_64版Qt项目ABI就选“x86_64-windows-msvc2017-pe-64bit”如果你是32位环境则选对应的“x86-windows-msvc2017-pe-32bit”。这一步经常有人漏选或者选错结果Kit一直检测不到编译器后面就报“编译器未包含main类型”。填完后点击“应用”。这里要特别提醒一个很多新手没搞懂的点编译器路径其实有两处概念。一处的根目录对应cl.exe另一处的“工具链”或“环境脚本”可能指向vcvarsall.bat。Qt Creator的编译器页签填写cl.exe路径Kit页签里如果需要设置“环境”或者“代码分析工具”再把vcvarsall.bat的路径作为环境脚本填上。两者别搞混。如果你在“编译器”页签里添加下拉列表时看不到MSVC选项最常见的原因是Qt Creator版本太老或者电脑上还没有被系统识别到的MSVC安装信息。这种情况先把Qt Creator更新到较新版本再检查Build Tools是否装好了注册表信息。极端情况下可以尝试重启电脑让环境变量刷新然后再打开Qt Creator添加。4.2 创建构建套件Kit编译器添加好后我们还要弄一个“Kit”让Qt Creator知道“用什么编译器 用什么Qt版本”组合来构建项目。操作流程还是在“Kits”选项页面切到“构建套件Kit”子页。点击“添加”按钮新建一个构建套件。配置区里有几个重点项名称写成“MSVC2017 x64”。编译器一栏C和C都选择刚才添加的“MSVC2017 64bit”。Qt版本一栏选择你安装的msvc2017_64对应的qmake。如果列表里没有点击旁边的“管理”手动添加D:\Qt\Qt5.14.2\5.14.2\msvc2017_64\bin\qmake.exe。CMake工具一栏如果项目需要CMake就选择你常用的CMake版本如果你用的是qmake工程这个不是必填。调试器一栏推荐选择“自动检测”到的CDB调试器这个通常会在安装Windows SDK时一并装好。如果这里显示“无”也不影响编译运行只是断点调试用不了需要单独安装Debugging Tools。点击“应用”后注意观察构建套件卡片上有没有红叉或黄色警示。如果一切正常这张卡会显示绿色“OK”状态如果红色说明有项目没配好需要继续修正。很多人在这一步栽跟头明明编译器添加对了但Kit一直红原因是“Qt版本”没选对或者“CMake工具”被指定成了一个不存在的路径。另外Qt版本必须与MSVC编译器架构匹配——64位编译器配msvc2017_64的qmake32位编译器配msvc2017_32的qmake交叉搭配是铁定跑不起来的。4.3 实测编译一个最小工程配置完成后用一个最小工程验证整个链路通不通。这一步很有必要比你在真实项目里试错要快得多。在Qt Creator里新建一个普通的Qt Widgets Application项目。在“构建套件选择”界面中勾选刚才创建的“MSVC2017 x64”Kit。直接点左下角的绿色三角运行或者先选择Release模式“构建”。观察“编译输出”窗口如果能看到类似“cl”相关的编译命令并且最终“编译完成”无报错说明MSVC2017编译器在Qt Creator里已经安装并生效了。我实际测试时的输出大概是这样的14:19:32: Running steps for project testMsvc... 14:19:32: Configuration unchanged, skipping qmake step. 14:19:32: Starting: C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC\Tools\MSVC\14.16.27023\bin\Hostx64\x64\cl.exe ...看到cl.exe真正被调用就说明Qt Creator已经认出了MSVC2017工具链。这里顺便再说一句首次编译时Qt Creator可能会提示找不到rc.exe或者masm.exe这类资源编译器/汇编器那是因为Windows SDK的一些辅助工具没有被加入PATH。解决办法是回到Build Tools安装器里单独勾选“Windows 10 SDK”的“桌面工具”组件或者直接在Kit的“环境”配置里加载vcvarsall.bat让Qt Creator自动继承整个编译环境。5. 高频报错与排查实录5.1 “编译器未包含main类型”到底怎么破这是搜索热度很高的报错在Qt Creator里表现为当你尝试编译时编译输出提示类似“compiler does not include main type”或者编译器的描述信息解析不出来。根据我的排查经验这个报错绝大多数是以下几个原因编译器路径填错了。很多人把路径填到了某个VC目录或者“BuildTools”根目录而不是精确到bin\Hostx64\x64\cl.exe。不精确Qt Creator就无法识别出编译器的类型和ABI于是报“未包含main type”。选错了编译器类型。添加编译器时下拉菜单里可能既有“MSVC”也有“MinGW”如果你选的是MinGW类型然后填了cl.exe的路径同样会报这个错因为MinGW的解析逻辑和MSVC完全不同。Qt版本与编译器不匹配。比如你选了cl.exe作为编译器但你的Qt版本是mingw73_32Qt Creator发现工具链与Qt库无法对应也会给你来这么一句。Windows SDK组件缺失。MSVC编译器本质上只是一个前端它需要调用Windows SDK里的头文件和库来完成项目解析。如果SDK组件没装全Qt Creator在“读取”编译器的默认头文件路径时失败也会误判为编译器不可用。排查方法是先用命令行手动验证编译器本身没问题就是cl能正常打印版本信息然后回到Qt Creator里重新检查编译器添加页的每个字段特别是“ABI”是否选择到了正确的MSVC ABI不要选成“unknown”或者“MinGW”。如果你的编译器配置页面里ABI下拉框是空的说明Qt Creator没识别出工具集这时候建议重启Qt Creator或者换一个Qt Creator版本试试。5.2 Kit显示红叉、qmake报Unknown模块另一个常见问题是配置好Kit后构建套件列表里这张Kit卡一直显示红叉展开来看不是“qmake未设置”就是“编译器未设置”。针对“qmake未设置”你去Kit页面的“Qt版本”下拉框如果里面是空的点“管理”选择“添加”然后定位到Qt安装目录下msvc2017_64\bin\qmake.exe。添加完成后Qt版本名称会显示成类似“Qt 5.14.2 (5.14.2)”的条目。注意不要误选成MinGW版本目录下的qmake否则这个Kit还是用不了。如果你编译某个模块时报“Unknown module in Qt: serialport”之类的问题那不是编译器的问题是Qt安装包本身没装这个模块。解决办法是回到Qt安装器里添加serialport模块或者重新下载一个包含这些模块的Qt离线安装包。跟MSVC2017工具链无关别搞混。5.3 隐藏但致命中文路径、环境变量和旧缓存有一个问题非常隐蔽就是Windows当前用户名为中文或者把Qt和Build Tools安装在了带中文的路径下。MSVC工具链对这类路径的支持一直不算友好轻则解析失败重则整个项目编译死循环。我自己处理过一个朋友的机器他的用户名是中文每次编译Qt程序到一半就报一些莫名其妙的fatal error后来把Qt和项目移到D:\QtProjects\下问题立刻消失。另外旧缓存和残留配置也会捣乱。如果你之前装过别的编译器或者以前配过另一个版本的MSVCQt Creator会在配置目录里缓存一些检测结果这时候即使你后来把新编译器装好了它还是会拿旧缓存去识别。处理办法是在“选项”——“Kits”页面右下角找到“重置”按钮或者直接关闭Qt Creator删除C:\Users\用户名\AppData\Roaming\QtProject下的配置文件再重启注意先备份。5.4 LNK1104: cannot open file kernel32.lib如果你最终编译时出现这个链接错误别急这不是编译器坏了是Windows SDK库路径没生效。通常是因为Kit里“Windows SDK版本”那一栏是空的或者选了不存在的SDK版本。解决办法是在Kit配置里把“Windows SDK版本”手动选成安装好的版本比如10.0.17763.0如果列表里没有回到Build Tools安装器在“单个组件”页签里勾选“Windows 10 SDK”装完重启Qt Creator再选一次。6. 几条真实经验的补充最后再分享几个我实际摸索出来的小技巧。第一如果你以后要长期维护多个Qt项目有MSVC2017、MSVC2019甚至MinGW同时存在的需求不要急着删任何一个工具链。Qt Creator对多Kit支持得很好你可以在同一个工程里配置多个构建套件编译时一键切换谁都不用卸载。第二Build Tools安装完成后不要手动去改系统环境变量里的PATH尤其是在里面加cl.exe的路径。这种做法会让某些命令行工具误以为编译器已经全局就绪但MSVC的编译环境其实必须经过vcvarsall.bat加载缺少那一堆环境变量直接敲cl是会出各种奇怪的找不到头文件错误的。Qt Creator能正常用是因为它自己会加载对应的环境脚本不需要你手动改全局PATH。第三关于“绿色版”“精简版”MSVC编译器网上搜得到很多号称“免安装的MSVC2017压缩包”我强烈建议不要碰。MSVC编译器技术上是需要和Windows SDK、注册表信息、标准库头文件深度耦合的缺一个组件编译时就会产生各种无头绪的报错。表面省了半个小时的安装时间后面排查起来可能花你一整天。用官方Build Tools是省心和合规的最优解。按这个教程走下来正常情况下你不会再卡在“编译器未包含main类型”“Kit红叉”这些经典坑里。至少我在几台不同Windows版本、不同Qt版本5.12、5.14、5.15的机器上都试过这条路都走得通。如果哪一步出了意外回到报错对应的排查段再核对一遍九成问题都出在编译器路径或ABI选择上。