launch.json必须放在.vscode目录下，因为VSCode仅在此路径识别工作区调试配置；放错位置会导致F5无反应、断点失效、webRoot解析错误等问题。
项目专用调试方案必须放在 .vscode/launch.json 里，且只对当前文件夹生效；直接改用户级 settings.json 或全局配置，断点不会命中、路径会错乱、webRoot 识别失败。
为什么 launch.json 必须放在 .vscode 目录下
VSCode 的调试行为由工作区配置驱动，而 .vscode 就是工作区配置的唯一法定位置。你用“文件 → 打开文件夹”打开项目后，VSCode 只读取该目录下的 .vscode/launch.json，其他位置的同名文件会被忽略。
常见错误现象：
- 把
launch.json放在桌面或用户根目录，F5 启动时提示 “No configuration” - 调试时断点灰色，控制台报
Could not resolve source location - 变量监视显示
undefined，但实际代码已执行
根本原因：VSCode 没找到项目上下文，${workspaceFolder} 解析为空或错误路径，webRoot 和 sourceMapPathOverrides 全部失效。
launch.json 中 webRoot 和 sourceMapPathOverrides 怎么配才不翻车
webRoot 是浏览器调试器查找源码的起点，sourceMapPathOverrides 是把打包后路径映射回原始源码的关键。两者配错，断点就永远点不中。
React 项目典型写法：
{
"type": "chrome",
"request": "launch",
"name": "Launch Chrome",
"url": "http://localhost:3000",
"webRoot": "${workspaceFolder}/src",
"sourceMapPathOverrides": {
"webpack:///src/*": "${webRoot}/*"
}
}
Vue CLI 项目需额外加 breakOnLoad：
{
"type": "chrome",
"request": "launch",
"name": "vuejs: chrome",
"url": "http://localhost:8080",
"webRoot": "${workspaceFolder}/src",
"breakOnLoad": true,
"sourceMapPathOverrides": {
"webpack:///src/*": "${webRoot}/*"
}
}
注意事项：
-
webRoot必须指向真实存在的目录，不能是构建输出目录（如dist） -
sourceMapPathOverrides的左边是 sourcemap 里写的路径（常含webpack:///），右边是本地路径，二者必须严格对应 - 使用 Vite 的项目，sourcemap 路径前缀可能是
file:///，此时要改成"file:///*": "${webRoot}/*"
多环境调试怎么共存（比如本地开发 + 测试服 + mock 接口）
一个 launch.json 文件可以定义多个 configurations，每个配置用不同 name 区分，F5 启动前在 VSCode 调试面板顶部下拉选择即可。
示例：同一 React 项目，三个调试入口
{
"version": "0.2.0",
"configurations": [
{
"type": "chrome",
"request": "launch",
"name": "Local dev",
"url": "http://localhost:3000",
"webRoot": "${workspaceFolder}/src"
},
{
"type": "chrome",
"request": "launch",
"name": "Test server",
"url": "https://test.example.com",
"webRoot": "${workspaceFolder}/src",
"pathMapping": {
"/static/js/": "${workspaceFolder}/build/static/js/"
}
},
{
"type": "chrome",
"request": "launch",
"name": "Mock API",
"url": "http://localhost:3000",
"webRoot": "${workspaceFolder}/src",
"env": {
"REACT_APP_API_BASE": "http://localhost:3001"
}
}
]
}
关键点：
-
pathMapping用于测试服场景，把线上资源路径映射到本地构建产物目录 -
env字段仅在启动调试会话时注入环境变量，不影响终端或构建过程 - 所有配置共享同一个
webRoot，但 URL、环境、路径映射可各自独立
C/C++ 项目调试必须同时配 tasks.json 和 launch.json
VSCode 不编译，只调度。C/C++ 调试链路依赖两步：先用 tasks.json 编译生成带 -g 的可执行文件，再用 launch.json 启动 gdb 加载它。
常见错误：
- 只配了
launch.json，没配tasks.json，F5 报Cannot find executable - 编译命令漏了
-g，断点能打上但无法停住，变量全显示<optimized out> -
launch.json中的program路径写死为./a.out，但tasks.json实际输出的是./main
最小可行配置组合：
.vscode/tasks.json：
{
"version": "2.0.0",
"tasks": [
{
"label": "build",
"type": "shell",
"command": "g++",
"args": [
"-g",
"${file}",
"-o",
"${fileDirname}/${fileBasenameNoExtension}"
],
"group": "build",
"isDefault": true
}
]
}
.vscode/launch.json：
{
"version": "0.2.0",
"configurations": [
{
"name": "(gdb) Launch",
"type": "cppdbg",
"request": "launch",
"program": "${fileDirname}/${fileBasenameNoExtension}",
"args": [],
"stopAtEntry": false,
"cwd": "${fileDirname}",
"environment": [],
"externalConsole": false,
"MIMode": "gdb",
"miDebuggerPath": "/usr/bin/gdb",
"setupCommands": [
{
"description": "Enable pretty-printing for gdb",
"text": "-enable-pretty-printing",
"ignoreFailures": true
}
]
}
]
}
注意：miDebuggerPath 在 Windows 上通常是 "C:\msys64\mingw64\bin\gdb.exe"，Linux/macOS 多为 /usr/bin/gdb，路径不对会导致调试器启动失败。
最易被忽略的一点：所有路径变量（${workspaceFolder}、${fileDirname} 等）在 Windows 下自动转反斜杠，但在 sourceMapPathOverrides 或 pathMapping 中若手动写了 \，反而会破坏匹配——一律用正斜杠 /，VSCode 内部会做适配。
