在 VS Code 中，C++ 的编译与调试并不像集成 IDE 那样由一个按钮自动完成。它的灵活性来自 .vscode 目录下的两个 JSON 文件：tasks.json 负责定义编译任务，launch.json 负责定义调试配置。理清两者的边界，后续所有配置都会变得简单。
一、先分清两个文件的职责
如果把 VS Code 比作一个可编程的工作台，那么 tasks.json 就是任务调度表。它告诉 VS Code 执行哪条命令、给这条命令传什么参数、在哪个目录下执行。对 C++ 开发来说，最典型的任务就是调用 g++ 或 clang 把 .cpp 文件编译成可执行文件。这个文件通常放在工作区的 .vscode 隐藏目录下，VS Code 打开当前文件夹时会自动读取。
launch.json 则是调试入口。它只关心一件事：当用户按下 F5 时，调试器应该启动哪个程序、使用哪种调试协议、是否需要先运行某个编译任务。可以说 tasks.json 解决的是“怎么生成程序”，launch.json 解决的是“怎么让程序在调试器里跑起来”。两者通过 preLaunchTask 这个字段产生关联，调试前自动编译，调试中才能看到最新的代码改动。
一个常见的误区是把编译参数直接塞进 launch.json，或者把调试器路径写进 tasks.json。虽然某些插件允许混合配置，但从可维护性角度看，建议始终让编译和调试各司其职。这样后续切换编译器、增加多文件编译、或者更换调试器时，只需要修改对应的那个文件。
二、创建 tasks.json：把编译变成可重复任务
先来看一个在 Windows 下使用 MinGW g++ 编译当前文件的 tasks.json 示例。需要注意的是，VS Code 的 JSON 文件支持注释，所以下面的字段说明可以放心写进去。
{
"version": "2.0.0",
"tasks": [
{
"label": "build current file",
"type": "shell",
"command": "g++",
"args": [
"-g",
"${file}",
"-o",
"${fileDirname}\\${fileBasenameNoExtension}.exe"
],
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": ["$gcc"]
}
]
}
这个任务的核心是 command 和 args。command 指定可执行命令 g++，args 数组会按顺序拼接成命令行，最终执行的是类似 g++ -g "main.cpp" -o "main.exe" 的指令。这里的 ${file} 表示当前激活的源文件，${fileDirname} 表示源文件所在目录，${fileBasenameNoExtension} 表示去掉扩展名后的文件名。使用这些预定义变量后，不管文件叫什么名字、放在哪个子目录，编译输出都能跟源文件保持一致。
group 字段把任务标记为默认构建任务，这样按 Ctrl+Shift+B 时可以直接触发它，也能被 launch.json 的 preLaunchTask 引用。而 problemMatcher 可以把编译器的错误输出自动关联到 VS Code 的问题面板，点击错误就能跳转到对应代码行。在 Linux 或 macOS 上，可以将输出路径改为 ${fileDirname}/${fileBasenameNoExtension}，因为可执行文件不需要 .exe 后缀。如果 g++ 不在系统 PATH 中，就需要把 command 改成完整路径，例如 C:\\MinGW\\bin\\g++.exe，注意 JSON 字符串里反斜杠需要写成双反斜杠。
如果项目包含多个源文件，单文件编译就不够用了。可以把 args 中的 ${file} 替换成 ${workspaceFolder}\\*.cpp，但更稳妥的做法是写一个 shell 命令，例如 g++ -g ${workspaceFolder}\\src\\*.cpp -o ${workspaceFolder}\\build\\app.exe。此时 command 可以写 g++，args 里列出所有参数；也可以把 type 改成 process 并让 command 指向编译器，但 shell 类型对简单项目已经足够。
三、创建 launch.json：打通调试链路
编译任务就绪之后，还需要让调试器知道去哪里找程序。下面是一个基于 gdb 的 launch.json 示例，适用于 MinGW-w64 环境。
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug with gdb",
"type": "cppdbg",
"request": "launch",
"program": "${fileDirname}\\${fileBasenameNoExtension}.exe",
"args": [],
"stopAtEntry": false,
"cwd": "${fileDirname}",
"environment": [],
"externalConsole": false,
"MIMode": "gdb",
"miDebuggerPath": "C:\\MinGW\\bin\\gdb.exe",
"preLaunchTask": "build current file"
}
]
}
type 固定为 cppdbg 表示使用微软 C/C++ 扩展提供的调试器。request 为 launch 表示启动并调试程序，而不是附加到已有进程。program 必须与 tasks.json 中生成的输出路径完全一致，否则调试器会提示找不到文件。这里继续使用 ${fileDirname}\\${fileBasenameNoExtension}.exe，保证当前源文件编译出来的程序能被正确加载。
MIMode 指定调试器协议为 gdb，如果使用 MSVC 工具链则可以改为 windows。miDebuggerPath 指向 gdb 的绝对路径，这一步经常被忽略。即使 g++ 能在终端里被识别，VS Code 也未必能找到 gdb，因为调试器扩展不会读取你的 shell 环境变量。Windows 用户如果安装的是 MinGW-w64，这个路径可能是 C:\\msys64\\mingw64\\bin\\gdb.exe 或 C:\\MinGW\\bin\\gdb.exe，需要根据实际安装位置填写。Linux 下通常只需要写 /usr/bin/gdb，macOS 使用 lldb 时可以配成 lldb 并把 MIMode 改为 lldb。
最关键的是 preLaunchTask。它的值必须与 tasks.json 中某个任务的 label 完全一致，比如这里都是 build current file。这样每次按 F5 启动调试前，VS Code 会先运行该编译任务，编译成功后才进入调试；编译失败则不会启动调试器，错误信息会出现在终端或问题面板里。externalConsole 控制是否弹出独立控制台窗口，Windows 下如果需要输入输出交互，可以设为 true；在集成终端里调试则设为 false 更方便观察输出。
四、常见问题与排查思路
配置过程中最常见的一个报错是 task 'xxx' not found。这通常不是任务没写，而是 preLaunchTask 的字符串与 tasks.json 里的 label 大小写不一致，或者任务所在的 tasks.json 尚未保存。VS Code 不会自动同步未保存的配置内容。另一个典型问题是调试器启动后立刻退出，并提示 program does not exist。此时应检查 tasks.json 的输出路径和 launch.json 的 program 是否使用了完全相同的变量组合，以及源文件是否真的保存到了预期目录。
还有一类问题是 gdb 路径错误。VS Code 使用的是 miDebuggerPath 指定的 gdb，而不是系统 PATH 中的 gdb。如果启动调试时提示 Unable to start debugging. The value of miDebuggerPath is invalid，需要确认该路径是否真实存在，并且注意 Windows 路径中的反斜杠在 JSON 里必须写成双反斜杠。例如实际路径是 C:\MinGW\bin\gdb.exe，写入 JSON 时应写成 "C:\\MinGW\\bin\\gdb.exe"。另一个容易混淆的点是 cwd，它表示程序运行时的当前工作目录。如果程序依赖相对路径读取文件，最好把 cwd 设置为可执行文件所在目录或项目根目录，否则运行时可能找不到资源文件。
当项目结构变复杂后，建议把输出路径集中到一个 build 目录，而不是散落在源文件旁边。可以给 tasks 添加 options 字段指定 cwd，例如 "cwd": "${workspaceFolder}/build"。同时在 launch.json 中把 program 指向 ${workspaceFolder}/build/app.exe。这样源文件和生成文件分离，清理项目时也只需要删除 build 目录。需要提醒的是，JSON 配置文件对逗号和括号非常敏感，修改后如果无法解析，VS Code 会在窗口右下角给出提示，按照提示检查对应行即可。
最后，如果调试时发现断点不停，可以检查编译参数里是否包含 -g。没有调试符号的可执行文件虽然能启动，但断点会全部失效。此外，某些版本的 C/C++ 扩展需要安装对应平台的调试器组件，如果重装环境后问题依旧，可以尝试在命令面板中运行 C/C++: Edit Configurations (UI) 重新生成配置。理解 tasks 与 launch 的协作关系之后，再回头看这些 JSON 字段，就会发现它们不过是一套清晰的参数映射。
VS CodeC++tasks.json修改时间：2026-09-21 12:18:36