1. 为什么在 VS2019 里搭 Qt而不是直接上 Qt Creator先把结论摆在前面VS2019 加 Qt 这套组合到今天依然是 Windows 桌面端做工业软件、上位机、仪器控制类项目的常见选择。原因不复杂Qt Creator 本身没问题但当你面对的是一个已经用 C#/C 混编、依赖 MSBuild 工程体系、还要和第三方 SDK 做静态链接的老项目时把 Qt 塞进 VS 里往往比把整个项目迁到 Qt Creator 里省事得多。我最早做这套配置是在一个数据采集盒子的上位机项目上。需求很简单界面用 Qt 做底层采集卡 SDK 只给了 MSVC 的 lib 和头文件配套的调试工具链也在 Visual Studio 里。如果强行用 Qt Creator光是把采集卡 SDK 的编译参数对齐就要折腾两天而 VS 这边只要把 Qt 的插件装好剩下的事情和普通 C 工程没区别。这就是环境选型服务于项目约束的典型场景不是哪个 IDE 更好而是哪个组合让你少写胶水代码。这套环境解决的核心问题是让 Qt 的构建流程qmake 或 CMake和 MSVC 的编译调试流程在同一套工程里共存。装好之后你能得到的是在 VS 的解决方案资源管理器里直接看到 .ui 文件、.qrc 资源文件双击 .ui 能拉起 Qt DesignerF5 能断点调试Qt 的信号槽在智能提示里也能正常识别。适合谁参考有一定 C 基础、需要在 Windows 上做带界面的本地程序、手头又有 VS 授权的开发者。如果你只是写个纯 Qt 的小工具Qt Creator 反而更轻快这篇就不必看了。有个前提必须说清楚VS2019 和 Qt 之间有版本对应关系不是随便下载两个安装包就能拼上。VS2019 对应的是 MSVC 2017 和 MSVC 2019 两套编译器工具集而 Qt 官方预编译包在 5.15 之前基本只提供 msvc2017 的二进制版本5.15 之后才普遍提供 msvc2019。这一点如果搞错会出现链接期符号不匹配或者干脆插件识别不到编译器的情况。下面章节会把这个对应关系彻底拆开讲。另外提醒一句VS2019 是 16.x 系列社区版、专业版、企业版在 Qt 插件支持上没有区别插件只认 VS 的安装路径和版本号。所以不必纠结版本档次稳定装好一个就行。2. 组件清单与安装顺序顺序错了就得重来2.1 三个必须装的东西以及它们的先后关系这套环境涉及三个独立安装包Visual Studio 2019 本体、Qt 运行库与开发库、Qt 的 VS 插件Qt VS Tools。很多人失败就失败在顺序上。正确的顺序是先装 Visual Studio 2019并且确保勾选了使用 C 的桌面开发工作负载再装 Qt在线安装器或离线包都行最后装 Qt VS Tools 插件并在插件里手动指定 Qt 的安装路径。为什么顺序不能反因为 Qt 的安装器会去检测系统里的编译器如果 VS 还没装它可能不会给你装对应的 msvc 套件或者装了但默认套件是 MinGW。而 Qt VS Tools 插件更依赖前两者的产物它需要读取 Qt 目录下的bin、include、lib结构还需要调用 VS 自带的 MSBuild。顺序对了后面全是点几下的事顺序错了轻则重新跑一遍安装器补组件重则要清注册表。安装 Visual Studio 2019 的时候工作负载那里只勾C 的桌面开发就够了。单个组件里建议额外确认这几项MSVC v142 - VS 2019 C x64/x86 生成工具、Windows 10 SDK版本选一个和你项目目标系统匹配的、C CMake 工具如果你打算用 CMake 而不是 qmake。别嫌 SDK 大Qt 编译时会去找 Windows SDK 的头文件缺了会在 include 阶段直接报错。2.2 Qt 版本怎么选5.15.2 还是 6.x这是被问得最多的问题。我的建议分两种情况维护老项目、依赖的第三方库比较旧、或者你用的教程资料大多是 Qt5 时代的那就选Qt 5.15.2。这个版本是 Qt5 的最后一个长期支持分支稳定、资料全、坑少。它的官方离线包对个人开发者依然可获取省去在线安装器联网慢的麻烦。全新项目、没有历史包袱、想用新版特性比如更完善的 Qt6 图形栈、CMake 支持更彻底那就上 Qt 6。但注意 Qt6 默认只用 CMake 构建qmake 虽然还在但官方已经不推荐了。对于第一次搭 VS2019 环境的人我倾向推荐 Qt 5.15.2 的 msvc2019 套件理由是它和 VS2019 的编译器完全对得上且社区里绝大多数 VSQt 的配置文章都是基于这个组合遇到问题好搜。下面这张表把常见组合列清楚VS 版本对应 MSVC 工具集推荐 Qt 套件备注VS2017MSVC 2017 (v141)msvc2017 32/64老项目常见VS2019MSVC 2019 (v142)msvc2019 64本文主推组合VS2019MSVC 2019 (v142)msvc2017 64可用需保证 ABI 兼容VS2022MSVC 2022 (v143)msvc2019 64通常兼容但官方组合是 msvc2022选 Qt 安装组件时安装器会列出一堆套件MinGW、msvc2017、msvc2019、Android、UWP 等等。你只需要勾 msvc2019 64-bit如果确实要在 VS 里编 32 位程序再补一个 msvc2019 32-bit。MinGW 那套完全不用装装了也不会被 VS 用到纯粹占硬盘。Additional Libraries 里如果不需要 Qt Charts、Qt Data Visualization 这些扩展模块可以都取消。2.3 安装路径里的隐藏雷区两个安装路径都有讲究。Qt 的路径里绝对不能有中文和空格。默认它喜欢装到C:\Qt\Qt5.15.2这个没问题有人图省事装在D:\我的软件\Qt下面后面 qmake 解析路径时就会出现乱码或者找不到文件的情况而且这种错误往往报在编译中途排查起来很烦。VS 的安装路径一般不用改但如果你要装多个版本的 VS 并存注意 Qt VS Tools 支持在同一台机器上为不同 VS 版本分别指定 Qt 版本这个在后面的配置章节会讲。还有一个细节Qt 安装完成后的目录结构要认一下以 5.15.2 为例C:\Qt\Qt5.15.2\ 5.15.2\ msvc2019_64\ bin\ - qmake.exe、windeployqt.exe 在这里 include\ lib\ plugins\ Tools\ QtCreator\ - 如果你勾了 Creator 会有这个记住msvc2019_64这一层的路径插件配置时填的就是它填成上一级的5.15.2或者Qt5.15.2都会失败。3. Qt VS Tools 插件的安装与 Qt 版本绑定3.1 插件获取与安装Qt VS Tools 是官方出的扩展安装方式有两种。第一种是直接在 VS 里走扩展 - 管理扩展 - 联机搜索 Qt Visual Studio Tools 下载安装装完重启 VS。第二种是官网下载对应的 .vsix 文件手动安装。我一般用第一种省事但要注意VS2019 对应的插件版本和 VS2022 不通用下载时看清楚它的支持范围。装完之后VS 顶部菜单栏会多出一个 扩展 下的 Qt VS Tools 菜单项。如果没看到先去扩展 - 管理扩展 - 已安装里确认它是否存在且已启用有时候是没重启 VS 导致的。3.2 注册 Qt 版本这一步是全局唯一的入口菜单里点 Qt VS Tools - Qt Versions会弹出一个管理对话框把 Qt 安装路径注册进去。填的时候有几个点要注意Name可以随便起建议起成Qt5.15.2_msvc2019_64这种能看出套件和位数的名字尤其当你以后要同时维护 32 位和 64 位构建时名字含糊必踩坑。Path必须指向包含bin的那一级也就是C:\Qt\Qt5.15.2\5.15.2\msvc2019_64。填好后点确认插件会自动检测 qmake如果路径正确它会把 qmake 的版本信息读出来显示。这里有个高频报错提示找不到 qmake 或者 qmake 无法执行。绝大多数是因为路径填深了一层或浅了一层少数是因为 Qt 是 MinGW 版而 VS 用的是 MSVC自动检测虽然通过但编译时就会炸。识别方法是看msvc2019_64\bin下面应该同时有qmake.exe和Qt5Core.dll这些文件如果只有qmake.exe且它依赖一堆 MinGW 的 dll那就是 MinGW 套件赶紧换。3.3 项目级的 Qt 环境绑定Qt 版本是全局注册的但每个项目要单独指定用哪个版本。做法是右键项目 - Qt Project Settings在 Qt Installation 下拉框里选刚才注册的版本。这个下拉框如果没有内容说明全局注册没成功回去检查上一步。绑定的意义在于编译时插件会去调用对应 Qt 的moc.exe、uic.exe、rcc.exe来处理元对象、界面文件和资源文件。这三个工具的位置和参数都由这个绑定决定。如果换 Qt 版本最省事的办法是把新版本注册进去然后在每个项目里切换下拉框不要试图手动改工程文件里的路径容易改出问题。一个常见困惑新建项目时插件会在工程文件里生成一堆 Qt 相关的 MSBuild 属性这些属性是跟 Qt 版本绑定的。如果你后来升级了 Qt 小版本比如从 5.15.2 换到 5.15.x 的其他版本只要目录结构一样通常直接换下拉框就行不用重新生成项目。4. 从零跑通第一个工程的完整链路4.1 新建工程的两种模板怎么用Qt VS Tools 提供两类模板Qt Widgets Application 和 Qt Console Application分别对应带界面的和纯命令行的。第一次验证环境我建议先用Qt Widgets Application因为它能把 uic界面编译器、moc元对象编译器、rcc资源编译器三条线全走一遍任何一个环节没配好都会立刻暴露。创建时向导会问你选哪个 Qt 版本、用 qmake 还是 CMake 还是 Qt 自带的 msbuild 集成方式。早期插件默认走 qmake 生成的 .vcxproj新版本更多推 CMake。对于本文这套 VS2019 环境选qmake是最稳妥的路径原因后面 4.3 会讲。给项目起名时也别用中文虽然 VS 工程名支持中文但 Qt 的构建系统对中文工程名偶尔会出问题。生成出来的解决方案里你会看到一个.ui文件、一个main.cpp、一个mainwindow.cpp/h以及一个.qrc资源文件如果向导里勾了。在 VS 里双击.ui文件如果配置正确它会自动打开 Qt Designer你拖几个控件进去保存回到 VS 编译。4.2 编译运行与产物目录第一次点 F5插件会先把.ui编译成ui_xxx.h把.qrc编译成qrc_xxx.cpp这些中间文件默认放在工程目录下的GeneratedFiles文件夹里。这个目录是自动生成的不要手动往里放东西也不建议把它纳入版本控制.gitignore里加上它。编译成功后可执行文件在哪取决于你的输出目录设置。默认在项目目录\x64\Debug或者项目目录\Debug下面。直接双击运行大概率会报错——报找不到 Qt5Core.dll之类的错误这不是环境没搭好而是运行时缺少 Qt 的动态库。开发阶段最简单的办法是把C:\Qt\Qt5.15.2\5.15.2\msvc2019_64\bin加到系统 PATH 环境变量里或者更推荐用 VS 的调试环境自动带上。在 VS 里配置运行时 PATH 的做法是项目属性 - 调试 - 环境加一行PATHC:\Qt\Qt5.15.2\5.15.2\msvc2019_64\bin;%PATH%这样 F5 调试时能找到所有 Qt DLL不用污染系统环境变量。这个方法比改 PATH 干净而且换 Qt 版本时只改这一处。4.3 qmake 和 CMake 在这个环境里到底选哪个这是本文要重点讲清的一个取舍。Qt 支持用 qmake、CMake 以及某些版本下的 Qbs 来构建VS 这边通过插件都能对接。它们在这套环境里的差别qmake插件支持最成熟生成的是传统的.vcxproj所有源文件、头文件、资源文件都显示在解决方案资源管理器里双击 .ui 直接进 Designer调试体验和普通 C 工程一致。缺点是 qmake 本身语法简陋大型项目依赖管理费力而且 Qt6 已经不再主推。CMake现代 Qt 的推荐方式跨平台一致依赖管理用find_package很清爽。但在 VS2019 里走 CMake 时VS 用的是打开文件夹模式或者生成 CMake 工程插件对 .ui 双击、moc 的智能提示支持不如 qmake 路径顺滑。另外 CMake 生成的文件组织方式和 qmake 不同UI 文件改动后重新生成的行为也有差异。结合VS2019 里搭 Qt这个具体场景我的建议是如果你是这个环境的新手先用 qmake 跑通把工具链吃透如果项目从第一天就打算跨平台且团队熟悉 CMake那直接上 CMake但要接受 IDE 体验上的一些毛刺。这两条路没有绝对对错只有和项目匹配度的问题。下面给一个 CMake 的最小CMakeLists.txt参考方便你在需要时切换cmake_minimum_required(VERSION 3.16) project(MyQtApp LANGUAGES CXX) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTOUIC ON) set(CMAKE_AUTORCC ON) find_package(Qt5 COMPONENTS Widgets REQUIRED) add_executable(MyQtApp main.cpp mainwindow.cpp mainwindow.h mainwindow.ui ) target_link_libraries(MyQtApp PRIVATE Qt5::Widgets)那三个AUTOMOC/AUTOUIC/AUTORCC是 CMake 集成 Qt 的关键分别负责自动处理信号槽、界面文件、资源文件。忘了开其中一个编译就会报找不到ui_xxx.h或者vtable未定义的经典错误。5. 高频报错逐个拆从现象到根因的排查链路5.1 报找不到 Qt 相关头文件现象是编译器报Cannot open include file: QApplication: No such file or directory。这类错误百分之九十不是 Qt 没装而是项目的 Qt 版本没绑定或者绑定错了。排查顺序右键项目 - Qt Project Settings看 Qt Installation 是不是空的下拉如果是空的回 Qt VS Tools - Qt Versions 检查全局注册如果全局注册正常但项目里还是选不了检查这个项目是不是当年从别的机器拷过来的它的 .vcxproj 里可能硬编码了旧路径。还有一种情况是头文件确实存在但包含路径没进工程。正常的 Qt 工程属性里C/C - 常规 - 附加包含目录应该自动带上 Qt 的include目录。如果是手动从空工程加进来的就得自己补。这也是我建议直接用模板新建工程验证环境的原因模板会把该配的都配好。5.2 报 unknown module(s) in Qt: serialport这个报错在热搜里出现频率很高值得单独拆。现象是 qmake 或工程配置阶段提示找不到 serialport 模块但你在代码里明明写了#include QSerialPort。根因通常是安装 Qt 时没有勾选 Qt Serial Port 这个附加模块。它不属于默认核心模块需要单独选装。解决办法是重新运行 Qt 维护工具在组件里找到对应版本的 Qt Serial Port勾上、更新。装完之后qmake 工程里要在.pro文件加一行QT serialportCMake 工程里则要find_package(Qt5 COMPONENTS SerialPort REQUIRED)并链接Qt5::SerialPort。加完之后重新生成工程报错就消失了。类似的模块报错还有unknown module in Qt: charts、network等套路一样先确认模块装没装再确认工程文件有没有声明。这个先查元件、再查接线的思路和硬件排查里查电源、查信号是一回事。5.3 运行时闪退与 DLL 缺失调试时程序启动就闪退事件查看器里能看到异常模块名。除了 4.2 说的 PATH 问题还有两个隐蔽原因Debug 和 Release 混用。Qt 在 Windows 上有 debug 和 release 两套 dll名字后缀分别是d和无后缀如Qt5Cored.dll和Qt5Core.dll。如果你 Debug 配置下 PATH 里指到了 release 的 bin链接能过但运行会崩。检查办法是看调试输出里的加载模块确认都是带d的。插件目录没被找到。Qt 的plugins目录下有platforms\qwindows.dll这个没找到会导致程序直接退出报错信息是This application failed to start because no Qt platform plugin could be initialized。开发阶段把plugins\platforms一起加进 PATH 或者用调试环境变量解决发布阶段用windeployqt.exe自动拷贝。5.4 中文乱码源文件编码和运行编码不一致VS2019 默认的源文件编码是 GB2312/GBK取决于系统区域设置而 Qt 内部字符串处理默认按 UTF-8。两边不一致界面上的中文就变成问号或方块。解决办法有两条我推荐第一条把源文件统一存成 UTF-8 with BOM。VS2019 里可以在文件 - 高级保存选项里改单个文件的编码但文件多了很麻烦。更彻底的做法是在.pro或.vcxproj里加编译选项/utf-8让 MSVC 按 UTF-8 解析源文件。VS2019 项目属性 - C/C - 命令行 - 其他选项里加/utf-8即可。代码里用QString::fromLocal8Bit(中文)显式转换。这个适合个别字符串不适合全局。顺带说一句/utf-8这个选项还会影响#pragma execution_character_set的行为加之前和加之后建议都编译看一遍界面确保没有引入新的乱码。5.5 报 could not find any instance of Visual Studio这个报错信息本身和 Qt 无关它经常出现在安装别的工具比如某些数据库或 Node 原生模块时依赖 VS 构建工具的场景。根因是这些工具要找的是 Visual Studio 的生成工具Build Tools而不是完整 IDE或者它找的是特定版本的 VS 而系统里装的版本对不上。排查思路是确认 VS2019 是否勾选了 C 生成工具组件以及是否安装了独立的 Build Tools for Visual Studio 2019。如果你的 VS 只装了 .NET 相关的工作负载C 编译器就不在自然找不到。这提醒我们装 VS 时那个C 的桌面开发工作负载是必须的不只是为了 Qt很多本地原生编译场景都要它。6. 让这套环境真正好用的几个工程习惯6.1 把工程组织成能同时编 32 位和 64 位VS 的解决方案配置管理里可以给每个平台单独配 Qt 绑定。做法是在 Qt Versions 里同时注册 msvc2019_64 和 msvc2019_32 两个版本然后在项目的不同平台配置里分别选。听起来多此一举但如果你要发布给 32 位老客户早期不规划好后期加平台会牵动一堆第三方库那时候再改成本高得多。实践里我会在项目初期就建好 Debug|x64、Release|x64 两个配置32 位只在确有需求时才加。原因是现在的目标机基本是 64 位多一套配置就多一份维护和构建时间。真的需要 32 位时第三方库的 32 位版本才是最大的拦路虎Qt 本身反而是最容易解决的。6.2 用属性表Property Sheet管理 Qt 路径Qt VS Tools 默认把 Qt 的包含目录、库目录、附加依赖项直接写进.vcxproj。这有个坏处换 Qt 版本或换机器时这些路径要逐个工程改。更专业的做法是建一个属性表.props 文件把 Qt 相关的路径配置全放进去然后在多个工程里引用这个属性表。换版本时只改属性表一处所有工程跟着变。具体做法VS 的属性管理器视图里右键对应的配置添加新属性表把VC 目录下的包含目录、库目录以及链接器 - 输入的附加依赖项填进去。这个习惯在多工程解决方案里收益极大我自己在超过三个工程的项目里必用属性表。6.3 发布时的依赖收集开发阶段用 PATH 解决 dll 问题发布时就不能这么干了。Qt 提供了windeployqt.exe放在 Qt 的bin目录下。用法是在命令行进入你的 exe 所在目录执行C:\Qt\Qt5.15.2\5.15.2\msvc2019_64\bin\windeployqt.exe MyApp.exe它会自动扫描 exe 的依赖把需要的 Qt dll、平台插件、以及相关的运行时拷贝到 exe 旁边。注意几个点要在 Release 版 exe 上跑别在 Debug 版上跑否则拷的是带 d 后缀的调试库拷贝完要测试的是干净的机器也就是没装 Qt 的电脑因为你自己机器上 PATH 里有 Qt测不出问题如果用了 QML 或者 Qt Quick还会多出 qml 目录需要--qmldir参数指定源码目录。6.4 关于热词里那些相邻场景的一句提醒搜索热词里能看到不少开发环境搭建的相邻话题比如 STM32 开发环境、Px4 环境、Hadoop 环境、VSCode 配置 Python 等等。这些看着都和搭环境有关但底层逻辑差异很大嵌入式和 Qt 桌面的共性是都要处理交叉编译和库依赖但桌面端不需要烧录和调试探针大数据环境和前端环境主要是包管理和运行时隔离的问题和编译器工具链的纠缠少得多。我的经验是搭开发环境的通用心法是三步先确认工具链版本对应关系再确认安装顺序最后用一个最小可运行工程做验证。这套心法放到上面任何一个场景都成立区别只在于版本对应关系查的是哪张表。QtVS2019 这张表就是本文第 2 章那张。7. 我踩过的几个具体的坑坑一装完插件后菜单不显示重启也没用。当时是因为 VS 的安装实例和插件支持的版本对不上我装的是某个针对 VS2022 的新版插件。去插件的发布页面下载历史版本换成对应 VS2019 的那个版本后立即出现菜单。坑二Qt Designer 双击打不开提示找不到设计器。原因是 Qt 安装时我嫌大把 Tools 下的 Qt Creator 取消了勾选而插件某些版本依赖 Creator 附带的 Designer 可执行文件。补装 Creator 后解决。所以如果你打算在 VS 里双击 .ui装 Qt 时把 Creator 一起装上别省那点空间。坑三QSerialPort 相关代码编译过但链接失败。前面说了模块要装、.pro 要声明还有一个坑是QT serialport加在了.pro里但工程是从 .vcxproj 走 MSBuild 的改成 qmake 工程后需要重新用 qmake 生成 vcxproj光改 .pro 不重新生成是没用的。这个坑我卡了半小时才反应过来因为 VS 里看不到 .pro 的变更提示。坑四换了台电脑把整个工程目录拷贝过去编译报路径找不到。根因是 .vcxproj 里硬编码了老机器的 Qt 路径。解决办法就是 6.2 说的属性表或者换机器后重新走一遍 Qt Project Settings 的绑定。现在我的做法是工程目录里不放任何绝对路径Qt 路径全部通过环境变量和属性表引用。坑五Windows Server 上装某些组件时提示需要 VS2019。这正是热词里那条windowsserver2025 安装 mysql 提示需安装 visual studio 2019的场景。它要的其实是 C 构建工具用来编译原生模块。这种场景不需要完整的 VS IDE装 Build Tools for Visual Studio 2019 并在里面勾选 C 生成工具即可比装完整 IDE 省几个 G。这五个坑的共同点是它们都不在官方文档的标准流程里而是在版本错配、组件缺失、路径硬编码这些边界条件下才会冒出来。这也是为什么我一直强调搭环境的真正难点不是按步骤点下一步而是理解每一步在系统里留下了什么出问题时能顺着那个痕迹往回查。你把这套环境搭一遍再故意换一个 Qt 版本重搭一遍对工具链的理解会比看十篇文章都深。