VS Code 调试器怎样为不同环境选择 launch 配置

VS Code 调试器要适配本地开发、测试环境和远程进程时，最稳妥的做法不是每次打开 launch.json 手改一行，而是为每个调试目标建立一个有明确名字的 configuration。读者在“运行和调试”视图中选中目标配置，再用变量和平台覆盖处理差异；如果目标已经有进程，就选择 attach 类型的配置。

官方地址：https://code.visualstudio.com/docs/debugtest/debugging-configuration

先按调试目标建立配置选择表

先问两个问题：程序需要由 VS Code 启动，还是已经由脚本、容器或远程主机启动？启动时是否需要不同的参数、工作目录或环境变量？前者通常是 request: "launch"，后者通常是 request: "attach"。项目共享配置放在工作区根目录的 .vscode/launch.json，这样成员看到的是同一组入口。

建议先做一张小表，再写 JSON。名称表达用途，配置内容表达差异：

配置名不要写成“我的电脑”或“新配置”。当项目换到另一台机器时，名称仍应能提示正确入口。

用多个 configuration 固定环境差异

下面是 Node.js 调试器的原创 JSONC 示例。具体字段由调试器扩展的 schema 决定，VS Code 官方文档也建议在设置 type 后使用 IntelliSense 检查可用属性。

{
  "version": "0.2.0",
  "configurations": [
    {
      // 本地启动：入口和工作目录都跟随当前工作区
      "name": "dev-local",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/server.js",
      "cwd": "${workspaceFolder}",
      "env": { "APP_ENV": "development" }
    },
    {
      // 测试环境：保留同一入口，只替换任务参数和环境标识
      "name": "test-env",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/server.js",
      "cwd": "${workspaceFolder}",
      "args": ["--port", "4300"],
      "env": { "APP_ENV": "test" }
    },
    {
      // 远程进程：不重复启动程序，改为连接已开放的调试端口
      "name": "remote-attach",
      "type": "node",
      "request": "attach",
      "address": "localhost",
      "port": 9229
    }
  ]
}

这里的关键不是复制三份完整配置，而是让“启动方式”成为显式选择。若测试环境只差一个端口，保留同一入口即可；若远端程序已经运行，再创建一个 attach 配置，避免误启动第二个进程。

用变量和平台覆盖减少手工改配置

路径、环境变量和临时输入适合交给变量系统。${workspaceFolder} 指向工作区，${env:APP_ENV} 读取环境变量；如果需要每次启动时选择值，可在 inputs 中定义选项，再用 ${input:variableId} 引用。数组中的每个参数仍保持为一个参数，不要为了路径空格再手工套转义引号。

{
  "version": "0.2.0",
  "configurations": [
    {
      // 用变量让配置可在不同工作区复用
      "name": "select-environment",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/server.js",
      "args": ["--env", "${input:targetEnv}"],
      "env": { "APP_ENV": "${env:APP_ENV}" },
      "linux": {
        // 只覆盖 Linux 的脚本参数，调试器类型仍由顶层决定
        "args": ["--env", "linux-${input:targetEnv}"]
      }
    }
  ],
  "inputs": [
    {
      // 让启动前选择变成可见选项，减少直接编辑 JSON 的次数
      "id": "targetEnv",
      "type": "pickString",
      "description": "选择调试环境",
      "options": ["dev", "test", "staging"],
      "default": "dev"
    }
  ]
}

平台覆盖适合路径分隔符、脚本参数或本地运行时差异，不适合把一整套环境配置复制到三个区块。官方规则是覆盖项优先于配置级属性，而 type 决定由哪个调试器接管，不能放进平台区块。

在运行和调试视图完成一次可见核对

保存文件后打开“运行和调试”视图，在配置下拉框选择目标名称，再按启动按钮。先确认下拉框名称正确，再核对三个可见状态：启动任务是否按预期执行、调试会话是否出现在会话列表、程序读取到的环境标识是否与所选 configuration 一致。若启动后路径错误，优先检查工作区根目录和变量解析，不要先改成绝对路径。

如果配置下拉框没有目标，通常是文件位置、JSONC 逗号或调试器扩展 schema 的问题；如果配置能选但无法启动，检查 type、request、入口文件和扩展支持的字段。远程场景则先确认目标进程确实以可调试方式启动，再检查 address 和 port。

相关问题

什么时候应该拆成多个 launch 配置？

只要启动方式、端口、环境标识或入口任务不同，就值得拆分；只有展示顺序不同，不必复制一份配置。

可以把密码直接写进 launch.json 吗？

不建议。工作区配置会进入版本控制，敏感值应由安全的环境注入方式提供，文章示例只使用非敏感的环境标识。

平台覆盖能不能改变调试器类型？

不能。type 决定调试器，平台区块只覆盖平台相关属性；需要换调试器时应建立另一条完整 configuration。