尧图网页设计 
说实话Windows 下写 Qt 程序大多数人第一反应是打开 Qt Creator。但如果你是一个重度 VS Code 用户或者平时要在多个语言、多个工具链之间来回切换你会发现 Qt Creator 那种全家桶式的工作流其实有点重。用 VS Code 搭配 Qt 和 qmake完全可以做出一个轻量、可控、启动速度极快的 C/Qt 开发环境。这篇文章我会从零开始把整套搭建过程、每个配置文件的作用、以及我踩过的坑一次性讲清楚。这个东西能做什么简单说就是在 VS Code 里面完成 Qt 项目的创建、编译、调试支持语法提示、跳转定义、F5 断点调试。适合三类人一是习惯 VS Code 编辑体验的开发者二是想要轻量级 Qt 开发环境的学生或个人开发者三是在 CI 环境里需要用命令行方式构建 Qt 项目的朋友。如果你项目规模比较大、团队协作对 CMake 有硬性要求那这篇文章里的 qmake 部分可以根据情况替换成 CMake但思路完全通用。1. 方案选型为什么是 VS Code、Qt、qmake 这个组合先说结论这套组合的核心优势是各干各的活但拼起来很顺手。VS Code 负责编辑和交互Qt 提供框架库qmake 负责构建规则。三者是独立组件出了问题可以单独替换不像 Qt Creator 那样把编辑器、构建器、调试器打包在一起配置文件藏得比较深改动起来反而费劲。1.1 qmake 与 CMake 的选择思路先说 qmake。它是 Qt 自带的构建工具核心概念是.pro文件里面声明源文件、头文件、Qt 模块、配置项。它的优势在于Qt 原生写一个QT widgets或者QT networkqmake 就自动帮你把对应的库、头文件路径、编译选项全部处理好不需要手动去链接Qt5Widgets.lib或者Qt5Core.lib也不用去查 include path 应该怎么写。对于中小型 Qt 项目qmake 的写法和心智负担都最低。CMake 的优势是通用性强尤其在现代 C 项目里几乎是事实标准。但它对 Qt 新手有一个不小的门槛你需要自己处理find_package(Qt5)、target_link_libraries、CMAKE_PREFIX_PATH这些概念稍不注意就出现 Could not find a package configuration file 这种让人抓狂的错误。我的建议是个人项目、课程设计、内部工具用 qmake 足够如果是准备开源、或者将来要对接大型 CI 体系直接学 CMake 也行。本文主要讲 qmake 路线但后面我会补充 CMake 切换的一些要点。1.2 编译器选型MSVC 还是 MinGW这是 Windows 下 Qt 开发最关键的决策点之一。Qt 官方安装包对 Windows 有两种主流版本MSVC 版本例如msvc2019_64需要安装 Visual Studio 2019/2022 的 C 桌面开发组件使用cl.exe做为编译器用nmake做构建器。这是最正统的 Windows-native 路线支持 Windows API 调用、性能好、和 Qt Creator 的默认配置一致。缺点是如果你平时不用 VS单为这个安装几个 GB 的 VS Build Tools确实有点占磁盘。MinGW 版本例如mingw81_64使用 GNU 编译器g和mingw32-make。安装包体积小不依赖 Visual Studio对习惯 Linux 下 gcc 命令的开发者非常友好。缺点是部分 Windows API 相关的行为与 MSVC 编译的程序有细微差异某些第三方库比如只提供 MSVC 预编译包的库链接起来很麻烦。我个人的建议如果你只在 Windows 上做 Qt 开发而且不排斥安装 VS Build Tools优先选 MSVC。如果你同时做跨平台开发、希望在 Linux/Windows 之间复用同样的 gcc 参数习惯选 MinGW 也完全可行。后面所有配置我会以 MSVC 路线为主同时标注 MinGW 路线的差异点。1.3 VS Code 在习惯层面的优势VS Code 的杀手级功能是用户自定义工作区。给 Qt 项目单独建一个.vscode文件夹里面放四个 JSON 配置这个项目在别的电脑上也能以同样方式构建。配合 Git 管理配置文件、workspace级别的 settings可以做到配置即代码。这条路径的扩展生态也很成熟C IntelliSense 由ms-vscode.cpptools提供比老牌的插件不知道友好多少倍。对于多语言开发者来说一个 VS Code 顶掉编辑器和 IDE 两套工具少学不少快捷键。2. 环境准备VS Code、Qt、编译器的安装与版本选择在写任何配置文件之前先把三个基础组件安装好。这里每一步的版本选择都是有讲究的直接照抄最新版可能反而出错。2.1 Qt 版本选择与安装源访问 Qt 官方下载页面或清华镜像站选择 Qt 5.15 系列或 Qt 6.x LTS。目前我写作此篇时 Qt 5.15 仍是大量开源项目的稳定选择Qt 6 在新项目中也已经非常成熟。需要留意的是Qt 5.15.2 的 MSVC 版本自带的是msvc2019_64这意味着它要求至少 VS2019 的编译环境和运行库。如果你的机器上只有 VS2022运行库一般也能兼容但保险起见建议安装与 Qt 版本配套的 VS Build Tools。安装时选择组件很关键MSVC 2019 64-bit或MinGW 8.1.0 64-bit这套工具链组件千万不要只勾选 Qt 库本体。Qt Debug Symbols建议勾上有了它调试时才可以看到 Qt 内部的函数调用栈。顺手把Sources组件装上步骤调试时可以直接跳转到 Qt 源码内部排查问题非常实用。安装路径尽量选一个不带空格、不带中文的目录例如D:\Qt\Qt5.15.2。虽然 qmake 在现代版本对路径空格的支持好了一些但 VS Code 的 task 解析、调试器的符号加载对带空格的路径依然会出各种奇怪问题不值得去挑战。2.2 编译器与构建工具安装如果走 MSVC 路线你需要安装 Visual Studio Build Tools 或者完整版 Visual Studio。在安装器中勾选使用 C 的桌面开发工作负载它会自动安装MSVC x64编译器、Windows SDK和CMake等工具。注意VS Code 的终端默认是 PowerShell而不是 VS 的开发人员命令提示符。MSVC 编译器不能直接用因为cl.exe依赖一系列环境变量INCLUDE、LIB、PATH需要在启动 VS Code 之前通过 VsDevCmd.bat 初始化或者配置一个 PowerShell profile 自动加载环境。这个细节非常坑很多人就是在这里卡住的。如果走 MinGW 路线Qt 安装包的Tools目录下自带 MinGW 工具链一般不需要额外安装。但要注意Qt 官方 MinGW 版本对应的mingw32-make必须从 Qt 自带目录调用不能混用系统里其他 MinGW 的 make因为可能版本不匹配。2.3 VS Code 本体与扩展安装VS Code 本体下载安装即可注意安装时勾选添加到 PATH以及支持 Open with Code 右键菜单。接下来打开扩展面板必装三个扩展C/C扩展 ID: ms-vscode.cpptools提供 IntelliSense、调试、代码导航。Qt Tools扩展 ID: shd101wyy.sublime-text-qt或其他类似扩展提供.pro文件语法高亮和 Qt 类库的补全。这类扩展的质量参差不齐即使没有也基本能用只是体验差点。Chinese (Simplified) Language Pack可选如果你需要中文界面。另外如果你打算用 CMake那还需要安装CMake Tools。等 qmake 流程走顺之后再切 CMake 会平滑很多。3. 核心配置VS Code 中 qmake 项目的四大 JSON 文件VS Code 对每个项目的配置集中在.vscode文件夹下写对这四个文件环境就搭建成功了。它们分别是tasks.json构建任务、launch.json调试配置、c_cpp_properties.jsonIntelliSense 路径、settings.json工作区设置。下面逐一说明。3.1 tasks.json定义编译与构建命令这个文件告诉 VS Code 怎么把一个.pro项目编译成 exe。我以 MSVC nmake 为例子。{ version: 2.0.0, tasks: [ { label: qmake, command: qmake, args: [ -spec, win32-msvc, ${workspaceFolder}/myapp.pro, CONFIGdebug, CONFIGqml_debug, OUT_DIRbuild ], group: build, problemMatcher: [$msCompile] }, { label: nmake, command: nmake, args: [/f, Makefile.Debug], dependsOn: qmake, group: build, problemMatcher: [$msCompile] } ] }DEPENDSON的写法表示先执行 qmake再执行 nmakeVS Code 会自动按依赖顺序执行。problemMatcher让编译错误直接以红色波浪线出现在代码里省去切换终端的操作。如果你的环境变量里没有 qmake比如你只加了 Qt 的 bin 目录到 PATH但没加 qmake 所在的目录你需要在 tasks 里把 command 写成全路径例如command: D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/bin/qmake.exe建议把 Qt 相关路径手动加到系统环境变量 PATH 中后续所有操作都会方便D:\Qt\Qt5.15.2\5.15.2\msvc2019_64\bin D:\Qt\Qt5.15.2\Tools\QtCreator\bin D:\Qt\Qt5.15.2\Tools\mingw810_64\bin (MinGW 路线时需要)3.2 launch.json调试器怎么启动你的程序按 F5 调试实际上是先启动 gdb/lldb 或 Visual Studio 调试器然后加载你的 exe。MSVC 写法的调试器是cppvsdbgMinGW 写法的调试器是gdb。这里给出 MSVC 的例子。{ version: 0.2.0, configurations: [ { name: Qt Debug (MSVC), type: cppvsdbg, request: launch, program: ${workspaceFolder}/build/debug/myapp.exe, args: [], stopAtEntry: false, cwd: ${workspaceFolder}, environment: [ { name: PATH, value: D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/bin;${env:PATH} } ], console: integratedTerminal, preLaunchTask: nmake } ] }注意几个点program必须指向实际生成的 exe 路径不要想当然写成项目根目录。environment里加 Qt 的 bin 路径是因为 Qt 的 DLL 如果不在 PATH 里运行时会报找不到 Qt5Cored.dll。这一步很有必要。preLaunchTask指定 F5 之前先执行 nmake保证程序是最新的。console设置为integratedTerminal这样std::cout的输出可以在 VS Code 底部终端看到。如果设置成externalTerminal会弹出一个独立的控制台窗口看 Qt 输出的效果更好视个人喜好。MinGW 路线的差异type改为cppdbgmiDebuggerPath指向 gdb.exe例如D:/Qt/Tools/mingw810_64/bin/gdb.exe。3.3 c_cpp_properties.json让 IntelliSense 不飘红VsCode 的 C 插件默认会扫描整个 workspace 来找头文件但如果 Qt 目录不在你的 workspace 里它就没有线索。这个文件专门用来告诉插件Qt 的头文件在哪里宏定义是什么配置正确后代码补全、跳转定义、悬停文档都能正常工作。{ configurations: [ { name: Win64, includePath: [ ${workspaceFolder}/**, D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/include, D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/include/QtCore, D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/include/QtGui, D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/include/QtWidgets ], defines: [ _DEBUG, UNICODE, _UNICODE, WIN32, _WIN64, QT_CORE_LIB, QT_GUI_LIB, QT_WIDGETS_LIB ], compilerPath: cl.exe, cStandard: c17, cppStandard: c17, intelliSenseMode: windows-msvc-x64 } ], version: 4 }IDE 的 includePath 写的越多维护成本越高。如果 Qt 升级版本你需要全部改一遍。一个偷懒的技巧是直接用 qmake 生成一个包含编译命令的compile_commands.json但 VS Code 原生对它的支持在大型项目里依然不算完美我后面会提到。3.4 settings.json为了让终端加载 MSVC 环境变量VS Code 的终端默认并不会加载 VS 的环境变量所以你在终端里直接敲cl多半会提示不是内部命令。这里提供两种常用方案。方案一在 settings.json 里配置终端启动命令。{ terminal.integrated.shellArgs.windows: [ /k, C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\BuildTools\\VC\\Auxiliary\\Build\\vcvars64.bat ] }注意shellArgs.windows在新版本 VS Code 中已经废弃你应当使用terminal.integrated.profiles.windows来自定义 profile。这是一个比较新的配置方式我下面会给出一个兼容写法。方案二推荐在 PowerShell 的 profile 里写一个函数启动 VS Code 前手动初始化环境。具体做法是打开 PowerShell执行notepad $PROFILE加上这一段function vsq { $vcvars C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat cmd /c $vcvars set | ForEach-Object { if ($_ -match ^(.*?)(.*)$) { Set-Item -Path env:$($matches[1]) -Value $matches[2] } } code . }之后在终端里输入vsq它会初始化 MSVC 环境并用 VS Code 打开当前目录。这种方式最可靠因为 VS Code 的所有子终端都会继承这个环境变量tasks、调试器都能找到cl.exe和nmake。如果你不想折腾 PowerShell另一个替代方案是直接用 Qt 自带的命令行快捷方式在开始菜单中Qt 5.15.2 (MSVC 2019 64-bit)它会弹出一个已经设置好环境的命令窗口在该窗口里运行code .。这也完全可行唯一不便的是每次都要通过这个入口打开 VS Code。4. qmake 项目创建与完整编译流程配置好 JSON 文件之后核心是创建一个最小可用的 Qt Widgets 项目然后走一遍完整的 qmake 构建链路。这样你对每一步在干什么会有非常具体的感觉。4.1 最小 .pro 文件假设你的项目文件夹名为myapp里面新建myapp.pro。QT core gui widgets TARGET myapp TEMPLATE app CONFIG c17 SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h解释一下QT core gui widgets声明需要哪些 Qt 模块。widgets是 Qt5 之后新增的模块如果你写 Qt4 的老代码只需要core gui。TARGET生成 exe 的名称。TEMPLATEapp表示生成应用程序如果是lib则生成动态库或静态库。CONFIG c17启用 C17 标准。SOURCES/HEADERS源文件列表\是换行符。4.2 一个简单的 Widgets 程序main.cpp#include QApplication #include mainwindow.h int main(int argc, char *argv[]) { QApplication a(argc, argv); MainWindow w; w.show(); return a.exec(); }mainwindow.h#ifndef MAINWINDOW_H #define MAINWINDOW_H #include QMainWindow class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); }; #endifmainwindow.cpp#include mainwindow.h #include QLabel MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { setWindowTitle(QStringLiteral(VS Code Qt qmake 演示)); resize(800, 600); auto *label new QLabel(QStringLiteral(环境搭建成功), this); label-setAlignment(Qt::AlignCenter); setCentralWidget(label); }4.3 手动执行构建链路验证打开 VS Code 终端依次执行以下命令qmake myapp.pro -spec win32-msvc nmake /f Makefile.Debug第一条命令生成Makefile.Debug和Makefile.Release还会自动生成debug/、release/目录。第二条命令调用 nmake 读取Makefile.Debug调用 cl.exe 编译 cpp 文件并链接生成 exe。构建产物通常会出现在debug/myapp.exe。如果这一步失败了大部分原因是终端里没有 MSVC 环境报错为cl 不是内部或外部命令。解决办法就回到 3.4 的初始化环境操作。如果是 MinGW 路线第二条命令应该是mingw32-make -f Makefile.Debug构建成功之后直接运行.\debug\myapp.exe此时应该弹出一个 800x600 的窗口中间显示环境搭建成功。4.4 在 tasks 中跑完整构建并设置快捷键前面 tasks.json 定义了qmake和nmake两个 task但实际使用中你希望按一个键就执行qmake nmake。VS Code 中可以用CtrlShiftB触发默认构建任务。设置方式在终端菜单中选择运行生成任务...或者直接在tasks.json中加一个聚合任务。{ label: Build Qt App, dependsOn: [qmake, nmake], group: { kind: build, isDefault: true } }这样按CtrlShiftBVS Code 会依次执行 qmake 和 nmake。如果编译报错终端里会出现带错误上下文的红色信息点击即可跳转到对应代码行效率非常高。5. 调试、断点与 Qt 源码级排查到这一步环境已经能编译运行了但是开发过程免不了调试。VS Code 对 Qt 调试的配置要点比普通 C 项目稍稍多一点。5.1 F5 启动调试的完整链路只要launch.json里配置了preLaunchTaskF5 的流程就是先执行构建任务生成最新 exe然后启动调试器。断点设置在main.cpp或者mainwindow.cpp的任意行调试启动后程序会在断点处暂停。调试器上方会出现调用堆栈和变量窗口。如果要深入 Qt 源码内部查看信号槽执行流程你需要在 Qt 安装时选中Sources组件调试器会自动定位到源码目录。这比在黑盒情况下猜 Qt 内部行为高效得多。5.2 常见调试器报错与处理我遇到最多的问题是Unable to start debugging. Launch options string provided by the system is empty.多半是program的路径不对或者 exe 不存在。调试器可以启动但没有符号变量全显示为地址这是 Debug 构建信息不完整检查CONFIG debug是否在 qmake 阶段传到命令行。如果你在 tasks 里只写了CONFIGrelease或没写CONFIG那nmake /f Makefile.Release编译出来的就是 Release 版符号信息缺失。运行时报0xc000007b通常是 32 位/64 位混用或者缺少 DLL 运行库检查 Qt 版本是msvc2019_64还是msvc201932 位确保 exe 是 64 位且 PATH 中加载了对应位数的 QT 目录。5.3 在 VS Code 中查看 Qt 类成员在代码中输入某个 QObject 对象然后点.VS Code 会自动弹出该类的成员方法列表。这个功能的引擎是 cpptools 的 IntelliSense前提是 3.3 的 includePath 配置正确。如果补全不出来多半是某个 include 路径没写全最简单的方法是把include/QtWidgets、include/QtGui这几个目录全部加进去宁可多不可少。6. 常见问题与排查技巧实录以下问题几乎每个从 Qt Creator 切换到 VS Code 的人都会遇到我把它们的表象、原因、解决办法整理成一个速查表。6.1 问题速查表问题现象根本原因解决办法qmake 不是内部或外部命令Qt bin 目录没进 PATH把 Qt 的 msvc2019_64/bin 和 QtCreator/bin 加入 PATHcl 不是内部或外部命令MSVC 环境变量未加载用 vcvars64.bat 初始化终端或在自定义 PowerShell profile 中加载无法打开包含文件: QApplicationincludePath 没加 Qt includec_cpp_properties.json 里补全 Qt 各模块 include 目录依赖的 DLL 找不到运行时 PATH 里没有 Qt bin在 launch.json environment 或系统 PATH 中加入 Qt binlink LNK1104: 无法打开文件 qt5widgets.lib链接器找不到 Qt 库路径重新执行 qmake它会生成正确的 Makefile检查 .pro 是否写对了 QT widgetsLNK2038 运行时库不匹配Debug/Release 混编全部使用 Debug 模式编译链接或者全部 Release不要混调试时提示找不到 vcruntime140d.dll缺少 VS 调试运行库安装 VS Build Tools 后重新启动或者把 Qt 的对应 debug 运行库 DLL 放入运行目录找不到 Makefile.Debug没有先执行 qmake先跑 qmake再跑 nmake/mingw32-make程序一跑就崩溃断点没触发链接的是 Release 库检查 qmake 命令中是否加了CONFIGdebug确保链接的是带d后缀的库6.2 最容易被忽略的路径问题Windows 文件的路径隐含很多坑。比如如果你把项目放在C:\Users\张三\My App\这个路径里既有中文又有空格。VS Code 在处理这种路径时tasks 的 command 解析、调试器的符号加载都可能出幺蛾子。最稳妥的方案是项目目录用纯英文路径例如D:\Dev\MyApp。如果实在改不了在 tasks.json 中给command加cwd: D:/Dev/MyApp并且尽量不用相对路径。避免使用网络驱动器调试器对 UNC 路径的兼容性很差。6.3 我的独家避坑技巧第一qmake 生成的 Makefile 里编译器路径可能是硬编码的所以一旦你将整个 Qt 目录移动了位置重新执行 qmake 比手动改 Makefile 靠谱得多。很多事情不要试图手工去修 Makefile那是非常低效的。第二VS Code 的 C 插件缓存很顽固。有时你明明改了 includePathIntelliSense 还是报旧错误。我常用的方法是CtrlShiftP打开命令面板执行C/C: Reset IntelliSense Database或者直接删掉项目根目录下的.vscode里的缓存目录。这个操作不损坏任何工程配置但能解决九成以上实际上能编译编辑器里就是飘红的问题。第三把构建产物放到独立目录。建议在 tasks.json 里给 qmake 加OUT_DIRbuild/debug这样的参数或者在 .pro 文件里手动指定DESTDIR $$PWD/bin OBJECTS_DIR $$PWD/build/obj MOC_DIR $$PWD/build/moc RCC_DIR $$PWD/build/rcc这样源文件目录永远是干净的后续做 Git 清理和 CI 构建都方便很多。6.4 调试模式与 Release 模式的构建隔离qmake 默认使用 shadow build 机制Debug 和 Release 产物理论上互不干扰。但如果你在 .pro 里写了CONFIG debug_and_release而 tasks.json 里又没有明确传递CONFIG参数那么有可能出现.obj文件互相覆盖或链接器拿到错误版本的库。我的做法是给两个 task 分别命名build-debug和build-release在 args 里明确加上CONFIGdebug或CONFIGrelease并在 launch.json 的program路径里反映出来。7. 从 qmake 平滑切换到 CMake 的要点如果你走到某一阶段因为项目变大或者协作需要决定从 qmake 换成 CMake不用推翻整套 VS Code 配置。你只需要做两件事在 .pro 文件同目录新建CMakeLists.txt写法示例cmake_minimum_required(VERSION 3.16) project(myapp VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(Qt5 REQUIRED COMPONENTS Core Gui Widgets) add_executable(myapp main.cpp mainwindow.cpp mainwindow.h ) target_link_libraries(myapp PRIVATE Qt5::Core Qt5::Gui Qt5::Widgets )修改 tasks.json用 cmake cmake --build 替换 qmake nmake。CMake 对 Qt 的自动化处理比 qmake 严格很多必须显式指定find_package。如果你不设置CMAKE_PREFIX_PATH指向 Qt 安装路径它找不到 Qt5Config.cmake。在 tasks.json 里可以加environment: [{name: CMAKE_PREFIX_PATH, value: D:/Qt/Qt5.15.2/5.15.2/msvc2019_64}]这样就不会报错了。8. 结合实际项目经验谈环境维护配置这套环境最核心的收益是可控每一步编译命令都是显式的每个配置文件都可以进 Git。QMake 生成的 Makefile 不需要提交.vscode里的 JSON 配置一定要提交这样团队新成员克隆仓库后装好 Qt 和 VS Code改一下路径变量就能开始工作。在长期使用中我逐渐养成了几个习惯每周至少执行一次qmake -r递归重生成保持 Makefile 与 .pro 文件同步升级 Qt 版本后先删掉 build 目录再全量重建避免旧生成文件污染调试异常时先确认 exe 是否真的是最新构建VS Code 的 preLaunchTask 有时候因为文件时间戳判断不准会跳过重新链接宁可手动跑一次构建再 F5。环境搭建只是起点真正带来效率提升的是把它调试到顺手的状态快捷键怎么设、自动保存怎么配、代码格式化用 clang-format 还是 Qt 自带风格、头文件的 include 顺序怎么组织这些细节决定了日常编码的流畅度。把这些习惯一点点沉淀到配置文件和模板项目里下次建新项目时十分钟就能恢复到最佳状态。 Windows下VS Code+Qt+qmake开发环境搭建指南
说实话Windows 下写 Qt 程序大多数人第一反应是打开 Qt Creator。但如果你是一个重度 VS Code 用户或者平时要在多个语言、多个工具链之间来回切换你会发现 Qt Creator 那种全家桶式的工作流其实有点重。用 VS Code 搭配 Qt 和 qmake完全可以做出一个轻量、可控、启动速度极快的 C/Qt 开发环境。这篇文章我会从零开始把整套搭建过程、每个配置文件的作用、以及我踩过的坑一次性讲清楚。这个东西能做什么简单说就是在 VS Code 里面完成 Qt 项目的创建、编译、调试支持语法提示、跳转定义、F5 断点调试。适合三类人一是习惯 VS Code 编辑体验的开发者二是想要轻量级 Qt 开发环境的学生或个人开发者三是在 CI 环境里需要用命令行方式构建 Qt 项目的朋友。如果你项目规模比较大、团队协作对 CMake 有硬性要求那这篇文章里的 qmake 部分可以根据情况替换成 CMake但思路完全通用。1. 方案选型为什么是 VS Code、Qt、qmake 这个组合先说结论这套组合的核心优势是各干各的活但拼起来很顺手。VS Code 负责编辑和交互Qt 提供框架库qmake 负责构建规则。三者是独立组件出了问题可以单独替换不像 Qt Creator 那样把编辑器、构建器、调试器打包在一起配置文件藏得比较深改动起来反而费劲。1.1 qmake 与 CMake 的选择思路先说 qmake。它是 Qt 自带的构建工具核心概念是.pro文件里面声明源文件、头文件、Qt 模块、配置项。它的优势在于Qt 原生写一个QT widgets或者QT networkqmake 就自动帮你把对应的库、头文件路径、编译选项全部处理好不需要手动去链接Qt5Widgets.lib或者Qt5Core.lib也不用去查 include path 应该怎么写。对于中小型 Qt 项目qmake 的写法和心智负担都最低。CMake 的优势是通用性强尤其在现代 C 项目里几乎是事实标准。但它对 Qt 新手有一个不小的门槛你需要自己处理find_package(Qt5)、target_link_libraries、CMAKE_PREFIX_PATH这些概念稍不注意就出现 Could not find a package configuration file 这种让人抓狂的错误。我的建议是个人项目、课程设计、内部工具用 qmake 足够如果是准备开源、或者将来要对接大型 CI 体系直接学 CMake 也行。本文主要讲 qmake 路线但后面我会补充 CMake 切换的一些要点。1.2 编译器选型MSVC 还是 MinGW这是 Windows 下 Qt 开发最关键的决策点之一。Qt 官方安装包对 Windows 有两种主流版本MSVC 版本例如msvc2019_64需要安装 Visual Studio 2019/2022 的 C 桌面开发组件使用cl.exe做为编译器用nmake做构建器。这是最正统的 Windows-native 路线支持 Windows API 调用、性能好、和 Qt Creator 的默认配置一致。缺点是如果你平时不用 VS单为这个安装几个 GB 的 VS Build Tools确实有点占磁盘。MinGW 版本例如mingw81_64使用 GNU 编译器g和mingw32-make。安装包体积小不依赖 Visual Studio对习惯 Linux 下 gcc 命令的开发者非常友好。缺点是部分 Windows API 相关的行为与 MSVC 编译的程序有细微差异某些第三方库比如只提供 MSVC 预编译包的库链接起来很麻烦。我个人的建议如果你只在 Windows 上做 Qt 开发而且不排斥安装 VS Build Tools优先选 MSVC。如果你同时做跨平台开发、希望在 Linux/Windows 之间复用同样的 gcc 参数习惯选 MinGW 也完全可行。后面所有配置我会以 MSVC 路线为主同时标注 MinGW 路线的差异点。1.3 VS Code 在习惯层面的优势VS Code 的杀手级功能是用户自定义工作区。给 Qt 项目单独建一个.vscode文件夹里面放四个 JSON 配置这个项目在别的电脑上也能以同样方式构建。配合 Git 管理配置文件、workspace级别的 settings可以做到配置即代码。这条路径的扩展生态也很成熟C IntelliSense 由ms-vscode.cpptools提供比老牌的插件不知道友好多少倍。对于多语言开发者来说一个 VS Code 顶掉编辑器和 IDE 两套工具少学不少快捷键。2. 环境准备VS Code、Qt、编译器的安装与版本选择在写任何配置文件之前先把三个基础组件安装好。这里每一步的版本选择都是有讲究的直接照抄最新版可能反而出错。2.1 Qt 版本选择与安装源访问 Qt 官方下载页面或清华镜像站选择 Qt 5.15 系列或 Qt 6.x LTS。目前我写作此篇时 Qt 5.15 仍是大量开源项目的稳定选择Qt 6 在新项目中也已经非常成熟。需要留意的是Qt 5.15.2 的 MSVC 版本自带的是msvc2019_64这意味着它要求至少 VS2019 的编译环境和运行库。如果你的机器上只有 VS2022运行库一般也能兼容但保险起见建议安装与 Qt 版本配套的 VS Build Tools。安装时选择组件很关键MSVC 2019 64-bit或MinGW 8.1.0 64-bit这套工具链组件千万不要只勾选 Qt 库本体。Qt Debug Symbols建议勾上有了它调试时才可以看到 Qt 内部的函数调用栈。顺手把Sources组件装上步骤调试时可以直接跳转到 Qt 源码内部排查问题非常实用。安装路径尽量选一个不带空格、不带中文的目录例如D:\Qt\Qt5.15.2。虽然 qmake 在现代版本对路径空格的支持好了一些但 VS Code 的 task 解析、调试器的符号加载对带空格的路径依然会出各种奇怪问题不值得去挑战。2.2 编译器与构建工具安装如果走 MSVC 路线你需要安装 Visual Studio Build Tools 或者完整版 Visual Studio。在安装器中勾选使用 C 的桌面开发工作负载它会自动安装MSVC x64编译器、Windows SDK和CMake等工具。注意VS Code 的终端默认是 PowerShell而不是 VS 的开发人员命令提示符。MSVC 编译器不能直接用因为cl.exe依赖一系列环境变量INCLUDE、LIB、PATH需要在启动 VS Code 之前通过 VsDevCmd.bat 初始化或者配置一个 PowerShell profile 自动加载环境。这个细节非常坑很多人就是在这里卡住的。如果走 MinGW 路线Qt 安装包的Tools目录下自带 MinGW 工具链一般不需要额外安装。但要注意Qt 官方 MinGW 版本对应的mingw32-make必须从 Qt 自带目录调用不能混用系统里其他 MinGW 的 make因为可能版本不匹配。2.3 VS Code 本体与扩展安装VS Code 本体下载安装即可注意安装时勾选添加到 PATH以及支持 Open with Code 右键菜单。接下来打开扩展面板必装三个扩展C/C扩展 ID: ms-vscode.cpptools提供 IntelliSense、调试、代码导航。Qt Tools扩展 ID: shd101wyy.sublime-text-qt或其他类似扩展提供.pro文件语法高亮和 Qt 类库的补全。这类扩展的质量参差不齐即使没有也基本能用只是体验差点。Chinese (Simplified) Language Pack可选如果你需要中文界面。另外如果你打算用 CMake那还需要安装CMake Tools。等 qmake 流程走顺之后再切 CMake 会平滑很多。3. 核心配置VS Code 中 qmake 项目的四大 JSON 文件VS Code 对每个项目的配置集中在.vscode文件夹下写对这四个文件环境就搭建成功了。它们分别是tasks.json构建任务、launch.json调试配置、c_cpp_properties.jsonIntelliSense 路径、settings.json工作区设置。下面逐一说明。3.1 tasks.json定义编译与构建命令这个文件告诉 VS Code 怎么把一个.pro项目编译成 exe。我以 MSVC nmake 为例子。{ version: 2.0.0, tasks: [ { label: qmake, command: qmake, args: [ -spec, win32-msvc, ${workspaceFolder}/myapp.pro, CONFIGdebug, CONFIGqml_debug, OUT_DIRbuild ], group: build, problemMatcher: [$msCompile] }, { label: nmake, command: nmake, args: [/f, Makefile.Debug], dependsOn: qmake, group: build, problemMatcher: [$msCompile] } ] }DEPENDSON的写法表示先执行 qmake再执行 nmakeVS Code 会自动按依赖顺序执行。problemMatcher让编译错误直接以红色波浪线出现在代码里省去切换终端的操作。如果你的环境变量里没有 qmake比如你只加了 Qt 的 bin 目录到 PATH但没加 qmake 所在的目录你需要在 tasks 里把 command 写成全路径例如command: D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/bin/qmake.exe建议把 Qt 相关路径手动加到系统环境变量 PATH 中后续所有操作都会方便D:\Qt\Qt5.15.2\5.15.2\msvc2019_64\bin D:\Qt\Qt5.15.2\Tools\QtCreator\bin D:\Qt\Qt5.15.2\Tools\mingw810_64\bin (MinGW 路线时需要)3.2 launch.json调试器怎么启动你的程序按 F5 调试实际上是先启动 gdb/lldb 或 Visual Studio 调试器然后加载你的 exe。MSVC 写法的调试器是cppvsdbgMinGW 写法的调试器是gdb。这里给出 MSVC 的例子。{ version: 0.2.0, configurations: [ { name: Qt Debug (MSVC), type: cppvsdbg, request: launch, program: ${workspaceFolder}/build/debug/myapp.exe, args: [], stopAtEntry: false, cwd: ${workspaceFolder}, environment: [ { name: PATH, value: D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/bin;${env:PATH} } ], console: integratedTerminal, preLaunchTask: nmake } ] }注意几个点program必须指向实际生成的 exe 路径不要想当然写成项目根目录。environment里加 Qt 的 bin 路径是因为 Qt 的 DLL 如果不在 PATH 里运行时会报找不到 Qt5Cored.dll。这一步很有必要。preLaunchTask指定 F5 之前先执行 nmake保证程序是最新的。console设置为integratedTerminal这样std::cout的输出可以在 VS Code 底部终端看到。如果设置成externalTerminal会弹出一个独立的控制台窗口看 Qt 输出的效果更好视个人喜好。MinGW 路线的差异type改为cppdbgmiDebuggerPath指向 gdb.exe例如D:/Qt/Tools/mingw810_64/bin/gdb.exe。3.3 c_cpp_properties.json让 IntelliSense 不飘红VsCode 的 C 插件默认会扫描整个 workspace 来找头文件但如果 Qt 目录不在你的 workspace 里它就没有线索。这个文件专门用来告诉插件Qt 的头文件在哪里宏定义是什么配置正确后代码补全、跳转定义、悬停文档都能正常工作。{ configurations: [ { name: Win64, includePath: [ ${workspaceFolder}/**, D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/include, D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/include/QtCore, D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/include/QtGui, D:/Qt/Qt5.15.2/5.15.2/msvc2019_64/include/QtWidgets ], defines: [ _DEBUG, UNICODE, _UNICODE, WIN32, _WIN64, QT_CORE_LIB, QT_GUI_LIB, QT_WIDGETS_LIB ], compilerPath: cl.exe, cStandard: c17, cppStandard: c17, intelliSenseMode: windows-msvc-x64 } ], version: 4 }IDE 的 includePath 写的越多维护成本越高。如果 Qt 升级版本你需要全部改一遍。一个偷懒的技巧是直接用 qmake 生成一个包含编译命令的compile_commands.json但 VS Code 原生对它的支持在大型项目里依然不算完美我后面会提到。3.4 settings.json为了让终端加载 MSVC 环境变量VS Code 的终端默认并不会加载 VS 的环境变量所以你在终端里直接敲cl多半会提示不是内部命令。这里提供两种常用方案。方案一在 settings.json 里配置终端启动命令。{ terminal.integrated.shellArgs.windows: [ /k, C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\BuildTools\\VC\\Auxiliary\\Build\\vcvars64.bat ] }注意shellArgs.windows在新版本 VS Code 中已经废弃你应当使用terminal.integrated.profiles.windows来自定义 profile。这是一个比较新的配置方式我下面会给出一个兼容写法。方案二推荐在 PowerShell 的 profile 里写一个函数启动 VS Code 前手动初始化环境。具体做法是打开 PowerShell执行notepad $PROFILE加上这一段function vsq { $vcvars C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvars64.bat cmd /c $vcvars set | ForEach-Object { if ($_ -match ^(.*?)(.*)$) { Set-Item -Path env:$($matches[1]) -Value $matches[2] } } code . }之后在终端里输入vsq它会初始化 MSVC 环境并用 VS Code 打开当前目录。这种方式最可靠因为 VS Code 的所有子终端都会继承这个环境变量tasks、调试器都能找到cl.exe和nmake。如果你不想折腾 PowerShell另一个替代方案是直接用 Qt 自带的命令行快捷方式在开始菜单中Qt 5.15.2 (MSVC 2019 64-bit)它会弹出一个已经设置好环境的命令窗口在该窗口里运行code .。这也完全可行唯一不便的是每次都要通过这个入口打开 VS Code。4. qmake 项目创建与完整编译流程配置好 JSON 文件之后核心是创建一个最小可用的 Qt Widgets 项目然后走一遍完整的 qmake 构建链路。这样你对每一步在干什么会有非常具体的感觉。4.1 最小 .pro 文件假设你的项目文件夹名为myapp里面新建myapp.pro。QT core gui widgets TARGET myapp TEMPLATE app CONFIG c17 SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h解释一下QT core gui widgets声明需要哪些 Qt 模块。widgets是 Qt5 之后新增的模块如果你写 Qt4 的老代码只需要core gui。TARGET生成 exe 的名称。TEMPLATEapp表示生成应用程序如果是lib则生成动态库或静态库。CONFIG c17启用 C17 标准。SOURCES/HEADERS源文件列表\是换行符。4.2 一个简单的 Widgets 程序main.cpp#include QApplication #include mainwindow.h int main(int argc, char *argv[]) { QApplication a(argc, argv); MainWindow w; w.show(); return a.exec(); }mainwindow.h#ifndef MAINWINDOW_H #define MAINWINDOW_H #include QMainWindow class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); }; #endifmainwindow.cpp#include mainwindow.h #include QLabel MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { setWindowTitle(QStringLiteral(VS Code Qt qmake 演示)); resize(800, 600); auto *label new QLabel(QStringLiteral(环境搭建成功), this); label-setAlignment(Qt::AlignCenter); setCentralWidget(label); }4.3 手动执行构建链路验证打开 VS Code 终端依次执行以下命令qmake myapp.pro -spec win32-msvc nmake /f Makefile.Debug第一条命令生成Makefile.Debug和Makefile.Release还会自动生成debug/、release/目录。第二条命令调用 nmake 读取Makefile.Debug调用 cl.exe 编译 cpp 文件并链接生成 exe。构建产物通常会出现在debug/myapp.exe。如果这一步失败了大部分原因是终端里没有 MSVC 环境报错为cl 不是内部或外部命令。解决办法就回到 3.4 的初始化环境操作。如果是 MinGW 路线第二条命令应该是mingw32-make -f Makefile.Debug构建成功之后直接运行.\debug\myapp.exe此时应该弹出一个 800x600 的窗口中间显示环境搭建成功。4.4 在 tasks 中跑完整构建并设置快捷键前面 tasks.json 定义了qmake和nmake两个 task但实际使用中你希望按一个键就执行qmake nmake。VS Code 中可以用CtrlShiftB触发默认构建任务。设置方式在终端菜单中选择运行生成任务...或者直接在tasks.json中加一个聚合任务。{ label: Build Qt App, dependsOn: [qmake, nmake], group: { kind: build, isDefault: true } }这样按CtrlShiftBVS Code 会依次执行 qmake 和 nmake。如果编译报错终端里会出现带错误上下文的红色信息点击即可跳转到对应代码行效率非常高。5. 调试、断点与 Qt 源码级排查到这一步环境已经能编译运行了但是开发过程免不了调试。VS Code 对 Qt 调试的配置要点比普通 C 项目稍稍多一点。5.1 F5 启动调试的完整链路只要launch.json里配置了preLaunchTaskF5 的流程就是先执行构建任务生成最新 exe然后启动调试器。断点设置在main.cpp或者mainwindow.cpp的任意行调试启动后程序会在断点处暂停。调试器上方会出现调用堆栈和变量窗口。如果要深入 Qt 源码内部查看信号槽执行流程你需要在 Qt 安装时选中Sources组件调试器会自动定位到源码目录。这比在黑盒情况下猜 Qt 内部行为高效得多。5.2 常见调试器报错与处理我遇到最多的问题是Unable to start debugging. Launch options string provided by the system is empty.多半是program的路径不对或者 exe 不存在。调试器可以启动但没有符号变量全显示为地址这是 Debug 构建信息不完整检查CONFIG debug是否在 qmake 阶段传到命令行。如果你在 tasks 里只写了CONFIGrelease或没写CONFIG那nmake /f Makefile.Release编译出来的就是 Release 版符号信息缺失。运行时报0xc000007b通常是 32 位/64 位混用或者缺少 DLL 运行库检查 Qt 版本是msvc2019_64还是msvc201932 位确保 exe 是 64 位且 PATH 中加载了对应位数的 QT 目录。5.3 在 VS Code 中查看 Qt 类成员在代码中输入某个 QObject 对象然后点.VS Code 会自动弹出该类的成员方法列表。这个功能的引擎是 cpptools 的 IntelliSense前提是 3.3 的 includePath 配置正确。如果补全不出来多半是某个 include 路径没写全最简单的方法是把include/QtWidgets、include/QtGui这几个目录全部加进去宁可多不可少。6. 常见问题与排查技巧实录以下问题几乎每个从 Qt Creator 切换到 VS Code 的人都会遇到我把它们的表象、原因、解决办法整理成一个速查表。6.1 问题速查表问题现象根本原因解决办法qmake 不是内部或外部命令Qt bin 目录没进 PATH把 Qt 的 msvc2019_64/bin 和 QtCreator/bin 加入 PATHcl 不是内部或外部命令MSVC 环境变量未加载用 vcvars64.bat 初始化终端或在自定义 PowerShell profile 中加载无法打开包含文件: QApplicationincludePath 没加 Qt includec_cpp_properties.json 里补全 Qt 各模块 include 目录依赖的 DLL 找不到运行时 PATH 里没有 Qt bin在 launch.json environment 或系统 PATH 中加入 Qt binlink LNK1104: 无法打开文件 qt5widgets.lib链接器找不到 Qt 库路径重新执行 qmake它会生成正确的 Makefile检查 .pro 是否写对了 QT widgetsLNK2038 运行时库不匹配Debug/Release 混编全部使用 Debug 模式编译链接或者全部 Release不要混调试时提示找不到 vcruntime140d.dll缺少 VS 调试运行库安装 VS Build Tools 后重新启动或者把 Qt 的对应 debug 运行库 DLL 放入运行目录找不到 Makefile.Debug没有先执行 qmake先跑 qmake再跑 nmake/mingw32-make程序一跑就崩溃断点没触发链接的是 Release 库检查 qmake 命令中是否加了CONFIGdebug确保链接的是带d后缀的库6.2 最容易被忽略的路径问题Windows 文件的路径隐含很多坑。比如如果你把项目放在C:\Users\张三\My App\这个路径里既有中文又有空格。VS Code 在处理这种路径时tasks 的 command 解析、调试器的符号加载都可能出幺蛾子。最稳妥的方案是项目目录用纯英文路径例如D:\Dev\MyApp。如果实在改不了在 tasks.json 中给command加cwd: D:/Dev/MyApp并且尽量不用相对路径。避免使用网络驱动器调试器对 UNC 路径的兼容性很差。6.3 我的独家避坑技巧第一qmake 生成的 Makefile 里编译器路径可能是硬编码的所以一旦你将整个 Qt 目录移动了位置重新执行 qmake 比手动改 Makefile 靠谱得多。很多事情不要试图手工去修 Makefile那是非常低效的。第二VS Code 的 C 插件缓存很顽固。有时你明明改了 includePathIntelliSense 还是报旧错误。我常用的方法是CtrlShiftP打开命令面板执行C/C: Reset IntelliSense Database或者直接删掉项目根目录下的.vscode里的缓存目录。这个操作不损坏任何工程配置但能解决九成以上实际上能编译编辑器里就是飘红的问题。第三把构建产物放到独立目录。建议在 tasks.json 里给 qmake 加OUT_DIRbuild/debug这样的参数或者在 .pro 文件里手动指定DESTDIR $$PWD/bin OBJECTS_DIR $$PWD/build/obj MOC_DIR $$PWD/build/moc RCC_DIR $$PWD/build/rcc这样源文件目录永远是干净的后续做 Git 清理和 CI 构建都方便很多。6.4 调试模式与 Release 模式的构建隔离qmake 默认使用 shadow build 机制Debug 和 Release 产物理论上互不干扰。但如果你在 .pro 里写了CONFIG debug_and_release而 tasks.json 里又没有明确传递CONFIG参数那么有可能出现.obj文件互相覆盖或链接器拿到错误版本的库。我的做法是给两个 task 分别命名build-debug和build-release在 args 里明确加上CONFIGdebug或CONFIGrelease并在 launch.json 的program路径里反映出来。7. 从 qmake 平滑切换到 CMake 的要点如果你走到某一阶段因为项目变大或者协作需要决定从 qmake 换成 CMake不用推翻整套 VS Code 配置。你只需要做两件事在 .pro 文件同目录新建CMakeLists.txt写法示例cmake_minimum_required(VERSION 3.16) project(myapp VERSION 1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(Qt5 REQUIRED COMPONENTS Core Gui Widgets) add_executable(myapp main.cpp mainwindow.cpp mainwindow.h ) target_link_libraries(myapp PRIVATE Qt5::Core Qt5::Gui Qt5::Widgets )修改 tasks.json用 cmake cmake --build 替换 qmake nmake。CMake 对 Qt 的自动化处理比 qmake 严格很多必须显式指定find_package。如果你不设置CMAKE_PREFIX_PATH指向 Qt 安装路径它找不到 Qt5Config.cmake。在 tasks.json 里可以加environment: [{name: CMAKE_PREFIX_PATH, value: D:/Qt/Qt5.15.2/5.15.2/msvc2019_64}]这样就不会报错了。8. 结合实际项目经验谈环境维护配置这套环境最核心的收益是可控每一步编译命令都是显式的每个配置文件都可以进 Git。QMake 生成的 Makefile 不需要提交.vscode里的 JSON 配置一定要提交这样团队新成员克隆仓库后装好 Qt 和 VS Code改一下路径变量就能开始工作。在长期使用中我逐渐养成了几个习惯每周至少执行一次qmake -r递归重生成保持 Makefile 与 .pro 文件同步升级 Qt 版本后先删掉 build 目录再全量重建避免旧生成文件污染调试异常时先确认 exe 是否真的是最新构建VS Code 的 preLaunchTask 有时候因为文件时间戳判断不准会跳过重新链接宁可手动跑一次构建再 F5。环境搭建只是起点真正带来效率提升的是把它调试到顺手的状态快捷键怎么设、自动保存怎么配、代码格式化用 clang-format 还是 Qt 自带风格、头文件的 include 顺序怎么组织这些细节决定了日常编码的流畅度。把这些习惯一点点沉淀到配置文件和模板项目里下次建新项目时十分钟就能恢复到最佳状态。