VS Code launch.json 怎样为多根工作区指定调试目标

在 VS Code 里同时打开 api-service 和 web-client 后，调试配置最容易出错的地方不是 JSON 语法，而是“这个配置属于哪个根目录”。解决办法是先保存多根工作区，再把每个目标的 name 写出文件夹后缀，并用 ${workspaceFolder:根目录名} 同时约束程序路径和工作目录。

官方地址：https://code.visualstudio.com/

下面以两个根目录为例：API 项目的入口是 src/index.ts，网页项目的入口是 src/main.ts。示例只讨论多根工作区的调试配置，不涉及具体语言扩展的断点功能。

先确认多根工作区的文件夹作用域

先在资源管理器中确认两个根目录的名字确实不同。菜单路径是“文件 → 将文件夹添加到工作区”，分别加入 api-service 与 web-client；然后执行“文件 → 将工作区另存为”，保存为 store.code-workspace。这样以后重新打开的是一个包含多个根目录的工作区，而不是两个互相独立的 VS Code 窗口。

这里要记住一个边界：.code-workspace 描述工作区有哪些文件夹，根目录里的 .vscode/launch.json 描述该文件夹可以提供哪些调试配置。把 API 的配置放进 web-client 的目录，配置即使能被发现，也会让相对路径和默认工作目录变得难以判断。

在目标根目录创建 launch.json

在资源管理器中右键 api-service，选择“新建文件夹”，创建 .vscode，再新建 launch.json。如果从“运行和调试”视图创建配置，要先在左侧的根目录下打开目标文件夹，避免把文件生成到另一个项目的 .vscode 目录。

示例把 API 和 Web 两个目标放在同一个工作区配置文件中，靠名称和路径区分它们。JSON 本身不能写注释，所以解释放在代码块后面：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "启动 API (api-service)",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder:api-service}/src/index.ts",
      "cwd": "${workspaceFolder:api-service}",
      "console": "integratedTerminal"
    },
    {
      "name": "启动 Web (web-client)",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder:web-client}/src/main.ts",
      "cwd": "${workspaceFolder:web-client}",
      "console": "integratedTerminal"
    }
  ]
}

name 是下拉菜单里给人看的识别名；program 是要启动的入口；cwd 决定程序读取相对路径时从哪里开始。示例中的注释不能直接塞进 JSON，否则严格解析器会报错；这些字段的用途应写在配置旁边或教程说明里。

用 workspaceFolder 绑定路径和 cwd

多根工作区不要把本机绝对路径写进 program 或 cwd。使用 ${workspaceFolder:api-service} 时，VS Code 会按根目录名称展开路径；使用不带名称的 ${workspaceFolder} 时，则要特别确认当前配置究竟由哪个文件夹提供，容易在同名项目中产生误解。

如果入口文件在根目录的子目录，只替换后半段即可：

{
  // 这段只演示 API 目标，路径根绑定到 api-service。
  "name": "启动 API (api-service)",
  "type": "node",
  "request": "launch",
  // program 指向真正入口，避免沿用另一个根目录的相对路径。
  "program": "${workspaceFolder:api-service}/src/index.ts",
  // cwd 与 program 使用同一根目录，保证配置文件和相对资源可被找到。
  "cwd": "${workspaceFolder:api-service}"
}

变量名必须和资源管理器中显示的根目录名称一致，包括大小写和空格。若根目录重命名，配置名称不会自动替你修正；这时应同步修改变量表达式和调试目标的显示名称。

从运行和调试面板核对目标

按菜单“运行 → 打开调试”或点击左侧“运行和调试”图标，在顶部下拉框中选择带有 (api-service) 或 (web-client) 后缀的目标。先选“启动 API (api-service)”，再检查编辑器中显示的配置字段：program 和 cwd 都应包含 ${workspaceFolder:api-service}。

如果下拉列表里出现两个难以区分的“启动”配置，先回到每个 launch.json 的 name，加入项目名后缀；如果启动后读取到了 web-client 的配置文件，再检查 cwd 是否仍使用了不带名称的变量或硬编码路径。

常见问题与回退方案

为什么只看到一个 launch.json？ 多根工作区会搜索各根目录下的调试配置，但文件必须放在目标根目录的 .vscode 中，且需要安装对应的调试扩展。先确认文件夹层级，再重新打开运行和调试视图。

为什么变量展开后路径不对？ 优先检查根目录名称和变量里的名称是否一致，再检查 program、cwd 是否混用了不同项目的前缀。不要先改成绝对路径，因为那会掩盖作用域配置问题。

什么时候使用不带名称的 workspaceFolder？ 单根工作区或配置天然只属于当前根目录时可以使用；多根工作区里需要明确目标的配置，建议使用带名称的写法，并让 name 与它保持一致。

小结

多根工作区指定调试目标可以归纳为三点：先保存并确认根目录名称；再让 name 直接显示项目后缀；最后用同一个命名的 workspaceFolder 约束 program 和 cwd。这样即使 API 和 Web 都有自己的 launch.json，运行和调试面板也能清楚地告诉你当前启动的是哪一个项目。