VS Code launch.json 调试配置完全指南-范庆林的技术博客

launch.json 是做什么的

VS Code 的调试行为由 .vscode/launch.json 描述。打开调试面板（F5），VS Code 列出 configurations 数组里的每条配置；选中一条启动即可。

一份最小的文件长这样：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Run app.js",
      "program": "${workspaceFolder}/app.js"
    }
  ]
}

字段含义：

type：调试器类型，如 node、coreclr、chrome
request：launch 启动新进程；attach 附加到已运行进程
name：面板上显示的名字

核心字段

字段	作用
`program`	启动的可执行文件 / 入口
`args`	传给程序的参数（数组）
`cwd`	当前工作目录
`env`	环境变量（对象）
`envFile`	环境变量文件路径（如 `.env`）
`preLaunchTask`	启动前先跑的 task（在 `tasks.json` 里定义）
`postDebugTask`	调试结束后跑的 task
`console`	`internalConsole` / `integratedTerminal` / `externalTerminal`
`port`	attach 模式要连的端口
`stopOnEntry`	启动时立刻停在第一行
`serverReadyAction`	服务器起来后自动打开浏览器

Node.js 示例

启动 Express / Koa 服务，监听 3000 后自动打开浏览器：

{
  "type": "node",
  "request": "launch",
  "name": "Run API",
  "program": "${workspaceFolder}/src/index.ts",
  "preLaunchTask": "tsc -p tsconfig.json",
  "outFiles": ["${workspaceFolder}/dist/**/*.js"],
  "runtimeArgs": ["-r", "ts-node/register"],
  "args": ["--port", "3000"],
  "env": { "NODE_ENV": "development" },
  "envFile": "${workspaceFolder}/.env",
  "console": "integratedTerminal",
  "serverReadyAction": {
    "pattern": "listening on port ([0-9]+)",
    "uriFormat": "http://localhost:%s",
    "action": "openExternally"
  }
}

三个易错点：

outFiles 是 sourcemap 映射路径，TypeScript 项目要写对，否则断点不会停。
runtimeArgs 是给 Node 本身的；args 是给被调试程序的。
serverReadyAction.pattern 必须能匹配启动日志里的关键行。

.NET 示例

启动 ASP.NET Core 项目，附加到现有进程：

{
  "type": "coreclr",
  "request": "launch",
  "name": "Run ASP.NET Core",
  "program": "${workspaceFolder}/src/MyApp/bin/Debug/net8.0/MyApp.dll",
  "args": [],
  "cwd": "${workspaceFolder}/src/MyApp",
  "env": { "ASPNETCORE_ENVIRONMENT": "Development" },
  "serverReadyAction": {
    "pattern": "Now listening on:\\s+(https?://\\S+)",
    "uriFormat": "%s",
    "action": "openExternally"
  }
}

或 attach 到已运行的进程：

{
  "type": "coreclr",
  "request": "attach",
  "name": "Attach to MyApp",
  "processName": "dotnet",
  "pipeTransport": {
    "pipeProgram": "ssh",
    "pipeArgs": ["-T", "user@server"],
    "debuggerPath": "/usr/share/dotnet/dotnet"
  }
}

pipeTransport 用于远程容器 / 服务器：SSH 进去后再调试。

复合调试：前后端一起跑

前端 + 后端的项目，可以用复合调试一次启动两个进程：

{
  "compounds": [
    {
      "name": "Full Stack",
      "configurations": ["Run API", "Run Frontend"],
      "preLaunchTask": "build-all",
      "stopAll": true
    }
  ]
}

选中 "Full Stack" 一启动，前后端两个进程一起进调试状态；结束调试时一起退出。

预设变量

常用变量（写成 ${name}）：

变量	含义
`${workspaceFolder}`	当前工作区根路径
`${workspaceFolderBasename}`	工作区目录名
`${file}`	当前文件绝对路径
`${relativeFile}`	当前文件相对工作区路径
`${fileBasename}`	当前文件名（带后缀）
`${fileBasenameNoExtension}`	当前文件名（去后缀）
`${env:VAR}`	环境变量 VAR
`${defaultBuildTask}`	默认 build task 名

常见错误

断点变灰色圆圈：sourcemap / outFiles 没配对，或 program 路径错。
Cannot find runtime：runtimeArgs 与 args 混了，前者是给 Node / dotnet 本身的。
Console 输出乱码：Node 项目用 integratedTerminal，不要用默认的 internalConsole。

使用准则

每个项目独立 launch.json，提交进 Git。
多用 ${workspaceFolder} 等变量，避免硬编码绝对路径。
前后端联调优先用 compounds，比手工开两个调试窗口省心。
调试容器 / 远端用 pipeTransport + attach，不要尝试 launch。

参考资料