1. 为什么我宁愿只装 Build Tools 也不装完整 Visual Studio很多人第一次在 Windows 上配 Qt MSVC 环境第一反应就是去官网下载 Visual Studio 2022 Community 完整安装包然后一路下一步。结果装完发现C 盘少了 20 多个 G开机多了一堆后台服务而真正用到的其实只有编译器、链接器和 Windows SDK 这几样东西。如果你只是拿 Qt 写桌面程序或者做嵌入式上位机、工控界面完整 IDE 里 90% 的功能你一年都不会点开一次。Qt 5.15.2 是 Qt5 系列最后一个长期支持版本官方对它的维护周期长、第三方库兼容性好尤其是串口、图表、WebEngine 这些模块在 5.15.2 上踩的坑比 Qt6 少得多。而它默认搭配的 MSVC 套件就是 msvc2019 和 msvc2019_64对应的编译器版本是 MSVC 19.29 左右。这个编译器并不要求你装 Visual Studio 2019 的完整 IDE微软单独提供了Build Tools for Visual Studio 2019里面包含 MSVC 编译器、Windows SDK、CMake、Ninja 等命令行工具体积只有完整 IDE 的三分之一左右而且不会往系统里塞 IDE 相关的服务和组件。我自己的主力开发机常年保持Qt Creator Build Tools这套组合装完大概 6 到 8 G比完整 VS 省下一大半空间。更重要的是Build Tools 安装过程可以精确勾选组件不会莫名其妙给你装上 UWP、Xamarin、Azure 开发套件这些完全用不到的东西。对于需要批量部署开发环境的团队来说这一点尤其关键——你可以把安装配置写成脚本新机器半小时内就能拉起一套可用的 Qt 编译环境。不过这里有个前提要说清楚免 Visual Studio 完整安装不等于免 MSVC 编译器。Qt 的 msvc2019 套件本质上调用的是cl.exe、link.exe这些命令行工具它们必须来自微软的 MSVC 工具链。Build Tools 就是官方提供的只含工具链、不含 IDE的合法获取途径。下面我会把整个流程拆开讲包括版本匹配、组件勾选、Qt Creator 套件配置、以及几个我踩过的坑。2. 版本匹配这件事比你想的要严格2.1 Qt 5.15.2 的 msvc2019 套件到底依赖什么Qt 官方在编译 5.15.2 的 Windows 包时使用的编译器是 MSVC 2019工具集 v142目标平台是 x64 和 x86。这意味着你在本机也必须提供v142 工具集而不是 v143VS2022 的默认工具集。虽然 v143 在大多数情况下能编译 Qt5 的代码但一旦涉及 Qt 官方预编译库的链接ABI 层面的细微差异可能导致LNK2019未解析符号或者运行期崩溃。所以结论很明确装 Build Tools 2019不要装 Build Tools 2022。如果你机器上已经有 VS2022也可以在安装器里额外勾选MSVC v142 - VS 2019 C x64/x86 生成工具这个单独组件但那样就绕回了完整 VS 的路线不符合我们轻量的初衷。项目推荐值说明Qt 版本5.15.2Qt5 最后 LTS模块稳定MSVC 工具集v142 (MSVC 19.29)与官方预编译包 ABI 一致Windows SDK10.0.19041 或 10.0.18362兼容 Win7 到 Win11目标架构x64 为主x86 按需与 Qt 套件名对应CMake3.16 以上Qt5 的 CMake 支持要求2.2 为什么 Windows SDK 版本不能随便选Build Tools 安装器默认会勾最新版 Windows SDK比如 10.0.22621。这个版本本身没问题但如果你要兼容 Windows 7 或者一些老旧的工控机就必须选 10.0.19041 及以下。Qt 5.15.2 官方文档里标注支持的最低 Windows 版本是 Win7 SP1而高版本 SDK 生成的程序可能引用 Win8 才有的 API导致在老系统上直接报不是有效的 Win32 应用程序。我的做法是同时装 10.0.19041 和 10.0.22621 两个 SDK在 Qt Creator 的套件里通过Windows SDK Version环境变量切换。这样既能开发新系统程序也能给老设备出包。SDK 本身不大多装一个也就几百兆。2.3 一个容易被忽略的细节vcvarsall.bat 的路径Build Tools 装完后编译环境变量是通过vcvarsall.bat或者vcvars64.bat注入的。这个脚本的位置在C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.batQt Creator 在自动检测 MSVC 套件时会去注册表里找 VS 安装路径。如果你只装了 Build Tools注册表项是存在的但有时候 Qt Creator 版本较老比如 4.11 以下识别不到需要手动指定。这个后面在套件配置章节会详细讲。3. 用官方安装器精准勾选组件3.1 下载与启动安装器去微软官方 Visual Studio 下载页面找到Visual Studio 2019 生成工具Build Tools for Visual Studio 2019的下载链接。注意不要点成 VS2022 的 Build Tools两者工具集不同。下载下来是一个几兆的vs_buildtools.exe运行后它会先安装一个小的引导程序然后弹出组件选择界面。这里有个网络上的常见问题安装器下载组件时速度可能很慢。我的经验是避开晚上高峰期或者在公司网络环境下操作。安装器本身支持断点续传中断了重新运行会接着下不用从头来。3.2 必须勾选的组件清单在安装器的工作负载标签页勾选C 生成工具。然后在右侧的安装详细信息里确保以下组件被选中MSVC v142 - VS 2019 C x64/x86 生成工具最新这是核心提供 cl.exe 和 link.exeWindows 10 SDK (10.0.19041.0)兼容性最好的 SDK 版本C CMake 工具用于 Windows如果你打算用 CMake 构建项目适用于 Windows 的 C Clang 工具可选某些第三方库需要MSVC v142 - VS 2019 C ARM64 生成工具只有做 ARM 平台才需要不要勾选的组件任何与 .NET、UWP、Xamarin、Azure、Node.js 相关的东西以及Visual Studio 核心编辑器。后者会给你装一个精简版 IDE虽然不大但完全没必要。提示安装器右下角会显示当前选择占用的磁盘空间。如果超过 8G说明你多勾了东西回去检查一遍。3.3 安装路径的选择默认路径是C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools。我建议保持默认不要改到 D 盘。原因是 Qt Creator 和一些构建脚本会硬编码这个路径去查找vcvarsall.bat改了之后需要额外配置环境变量徒增麻烦。如果 C 盘实在紧张可以在安装前用符号链接把目录映射到其他盘但这是进阶操作新手不建议折腾。安装过程大概 15 到 30 分钟取决于网速和磁盘性能。装完后不需要重启但建议重启一次让环境变量生效。4. Qt Creator 里把套件配起来4.1 让 Qt Creator 自动检测打开 Qt Creator进入工具→选项→Kits套件。在编译器标签页正常情况下你应该能看到自动检测到的Microsoft Visual C Compiler 16.0 (amd64)之类的条目。这个 16.0 就是 MSVC 2019 的内部版本号MSVC 19.29 对应 VS 16.11。如果没检测到点击添加→MSVC→C然后手动指定编译器路径C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Tools\MSVC\14.29.30133\bin\Hostx64\x64\cl.exe注意中间的14.29.30133是具体的小版本号你机器上可能略有不同去VC\Tools\MSVC\目录下看一眼实际文件夹名。4.2 配置 Qt Versions在Qt Versions标签页点击添加选择你 Qt 5.15.2 安装目录下的qmake.exeD:\Qt\5.15.2\msvc2019_64\bin\qmake.exe添加后 Qt Creator 会自动读取版本信息显示Qt 5.15.2 MSVC2019 64bit。如果显示红色警告通常是 qmake 依赖的 DLL 找不到检查一下 Qt 的 bin 目录是否在系统 PATH 里。4.3 组装 Kit回到Kits标签页点击添加然后逐项配置Name自己起个名字比如Qt 5.15.2 MSVC2019 64bitCompiler选刚才检测到的 MSVC 编译器Qt version选 5.15.2 msvc2019_64Debugger这个需要单独装见下一节CMake Tool如果装了 CMake 组件这里会自动出现配置完点Apply如果所有项都是绿色对勾说明套件可用。4.4 调试器从哪来Build Tools 默认不包含调试器cdb.exe。Qt Creator 在 Windows 上调试 MSVC 编译的程序需要 Windows SDK 里的调试工具。解决办法是在 Build Tools 安装器里额外勾选Windows 10 SDK 的调试工具或者单独下载 Windows SDK 安装器只装 Debugging Tools for Windows。装完后 cdb.exe 的位置在C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe在 Qt Creator 的Debuggers标签页添加这个路径然后回到 Kit 里选中它。没有调试器的话你只能运行不能断点开发效率会大打折扣。5. 那些让我折腾半天的坑5.1 Could not find any instance of Visual Studio 报错这个报错我在不止一台机器上遇到过。原因通常是 Qt Creator 通过注册表查找 VS 实例时只认完整 IDE 的注册项而 Build Tools 的注册项在另一个位置。解决办法有两个方法一升级 Qt Creator 到 4.12 以上版本新版本对 Build Tools 的识别做了改进。方法二手动在系统环境变量里添加VSINSTALLDIR值为C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools然后重启 Qt Creator。这个变量会让 Qt Creator 直接走路径查找绕过注册表。5.2 编译时报 Cannot open include file: windows.h这是典型的 Windows SDK 没配好。检查两点一是 Build Tools 里确实勾了 Windows SDK 组件二是 Qt Creator 的 Kit 里Environment一栏有没有正确注入 SDK 路径。正常情况下 Qt Creator 会自动调用vcvarsall.bat来设置环境但如果你的 Build Tools 装在非默认路径这个调用可能失败。手动验证方法打开x64 Native Tools Command Prompt for VS 2019Build Tools 装完后开始菜单里会有在里面输入cl如果能显示编译器版本信息说明工具链本身没问题问题出在 Qt Creator 的环境注入上。5.3 链接时提示 LNK1104: 无法打开文件 xxx.lib这种错误八成是架构不匹配。比如你的 Qt 套件是 64 位的但项目里链接了一个 32 位的第三方库。检查方法用dumpbin /headers xxx.lib看 Machine 字段x64 的库显示machine (x64)x86 显示machine (x86)。另一个可能是库路径没加到.pro文件里。Qt 的.pro里要用LIBS -L路径 -l库名的格式注意-l后面跟的是去掉.lib后缀的名字。5.4 运行期缺少 vcruntime140.dllMSVC 编译的程序默认动态链接 VC 运行时。如果你把 exe 拷到没装 VC 运行时的机器上就会报缺少vcruntime140.dll、msvcp140.dll等。解决办法有两种静态链接运行时在.pro里加QMAKE_CXXFLAGS_RELEASE /MT同时 Qt 本身也得是静态编译的否则会冲突。打包运行时 DLL把vcruntime140.dll、msvcp140.dll、vcruntime140_1.dll跟 exe 放一起。这几个 DLL 在 Build Tools 的VC\Redist\MSVC\目录下能找到。我一般用第二种配合windeployqt工具一起打包省事。6. 命令行构建脱离 Qt Creator 也能干活6.1 用 vcvars64.bat 初始化环境有时候你需要写自动化脚本或者在没有 Qt Creator 的服务器上构建。这时候就得手动初始化 MSVC 环境。写一个build.batecho off call C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat set PATHD:\Qt\5.15.2\msvc2019_64\bin;%PATH% cd /d %~dp0 qmake project.pro nmake release这个脚本先注入 MSVC 环境变量再把 Qt 的 bin 加到 PATH然后调用 qmake 生成 Makefile最后用 nmake 编译。注意vcvars64.bat必须在同一个 cmd 会话里 call不能直接运行否则环境变量不会保留。6.2 jom 比 nmake 快在哪Qt 官方推荐用jom代替nmake做并行编译。jom 是 Qt 自己维护的 nmake 替代品支持-j参数指定并行任务数。在.pro项目里如果用了jom -j8八核机器上编译速度能快三到四倍。jom 的位置在 Qt 安装目录的Tools\QtCreator\bin\jom\jom.exe或者单独下载。用法jom -j8 release6.3 CMake 项目的构建流程如果你的项目用 CMake 而不是 qmake流程略有不同call vcvars64.bat cmake -G Ninja -DCMAKE_PREFIX_PATHD:\Qt\5.15.2\msvc2019_64 -DCMAKE_BUILD_TYPERelease .. cmake --build . --parallel 8这里用 Ninja 作为生成器比 MSBuild 快不少。Ninja 在 Build Tools 的 CMake 组件里自带不用单独装。7. 几个提升效率的配置技巧7.1 把常用工具加进系统 PATH每次开命令行都要 call vcvars64 很烦。我的做法是在系统 PATH 里永久加入 Qt 的 bin 目录和 Build Tools 的Hostx64\x64目录这样qmake、cl、link随时可用。但要注意不要同时把 x86 和 x64 的编译器路径都加进去否则会冲突。只加你主要用的那个架构。7.2 Qt Creator 的构建套件克隆如果你同时要出 32 位和 64 位两个版本可以在 Kit 配置里克隆一份改一下 Qt version 和编译器架构就行。项目里通过工具→Kits快速切换不用改代码。7.3 用 ccache 加速重复编译MSVC 本身没有 ccache 支持但可以用clcache这个第三方工具。原理是缓存编译中间产物头文件没变时直接复用。配置方法是在.pro里加QMAKE_CXX clcache cl实测在大型项目上能省 50% 以上的重复编译时间。不过 clcache 对增量编译的缓存命中率依赖头文件依赖分析小项目提升不明显。7.4 定期清理构建目录Qt 项目的build-xxx-Debug目录会越积越大尤其是用了预编译头之后。我习惯在.pro同级目录放一个clean.batecho off for /d %%i in (build-*) do rd /s /q %%i一键清掉所有构建产物。注意别把源码目录误删了build-*这个前缀要跟 Qt Creator 的默认命名规则一致。8. 关于免完整 VS的边界与取舍这套方案不是万能的有几个场景你还是得装完整 Visual Studio需要调试 Windows 内核驱动Build Tools 不含 WDK 集成需要做 C/CLI 混合编程托管代码支持在 Build Tools 里不完整需要 VS 的代码分析工具静态分析、性能剖析这些只有完整 IDE 有团队要求统一 IDE 版本有些公司规范强制装完整 VS但对绝大多数 Qt 桌面开发、工控上位机、嵌入式 HMI 项目来说Build Tools 完全够用。我手上三个量产项目都是这套环境编译的稳定跑了两年多没出过工具链层面的问题。最后分享一个我自己的检查清单每次在新机器上配环境时按这个顺序走基本不会漏装 Build Tools 2019勾 v142 SDK 19041 CMake 调试工具装 Qt 5.15.2 msvc2019_64 离线包装 Qt Creator可以单独下也可以用 Qt 在线安装器里的打开 Qt Creator检查编译器、Qt Version、调试器是否自动识别新建一个空 Widgets 项目编译运行确认能出窗口打个断点确认调试器能用用 windeployqt 打包拷到另一台没装 Qt 的机器上跑一遍这七步走完环境就算彻底配好了。后面再遇到什么奇怪的链接错误大概率是第三方库的架构或者运行时版本问题跟工具链本身无关。