VS Code launch 怎样给调试配置传递环境文件

在 VS Code 的 launch.json 调试配置中添加 "envFile": "${workspaceFolder}/.env.debug"，即可让支持该属性的调试器读取环境文件。本文以内置 Node.js 调试器、type: node 和 request: launch 为例；其他语言应以其调试扩展支持的属性为准，不能机械复制。

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

Node.js 调试文档：https://code.visualstudio.com/docs/nodejs/nodejs-debugging

典型现象是：在终端中运行正常，按 F5 后却读不到变量。环境文件存在，并不表示每一个启动入口都会加载它。以下操作只传入 APP_STAGE 和 API_BASE 两个无敏感演示值，不连接外部服务。配图均为原创界面说明图，示例未在本文环境执行。

1. 打开工作区并准备可观察的环境变量

通过菜单 File → Open Folder 打开一个用于演示的文件夹，而不是仅打开一个孤立 JavaScript 文件。然后在左侧 Explorer（资源管理器）点击 New File，分别创建 .env.debug 和 env-probe.cjs。选择 .cjs 是为了让这个简短示例不依赖项目的模块类型配置。

在 .env.debug 中填入以下内容并保存。环境文件不是 shell 脚本，不需要写 export，也不要把 shell 命令或变量展开当作必然支持的语法。

# 只提供无敏感演示变量，不放真实口令或生产凭据
APP_STAGE=debug-file
API_BASE=https://example.invalid

在 env-probe.cjs 中保存下面的程序。变量被集中读入 snapshot，便于在断点处观察；它不发起网络请求，也不输出整个进程环境。

// 只观察本文定义的两个变量，避免泄露完整环境
const snapshot = {
  stage: process.env.APP_STAGE,
  apiBase: process.env.API_BASE
};
// 在下一行左侧行号栏设置断点，观察 snapshot 的字段
console.log(snapshot);

此步完成的可见状态是 Explorer 中出现两个文件，编辑器标签不再显示未保存标记。真实项目的私有环境文件应按团队规则忽略提交；只共享脱敏示例文件，不把调试便利性当成提交密钥的理由。

2. 在 launch.json 中绑定 envFile

点击活动栏的 Run and Debug（运行和调试） 图标，选择 create a launch.json file，再选择 Node.js 调试器。已有配置时，可打开工作区 .vscode/launch.json 并在 configurations 数组中追加一个对象，不要覆盖项目其他启动项。

下面是独立演示工作区的完整 JSONC 配置。VS Code 的 launch.json 允许注释；复制到只接受严格 JSON 的其他系统时，应先移除注释。

{
  "version": "0.2.0",
  "configurations": [
    {
      // 名称对应运行和调试面板中的可选启动项
      "name": "Node：环境文件演示",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/env-probe.cjs",
      // 显式指定工作区内的环境文件，不依赖当前编辑文件位置
      "envFile": "${workspaceFolder}/.env.debug",
      "cwd": "${workspaceFolder}",
      "console": "internalConsole"
    }
  ]
}

保存后，在 Run and Debug 顶部的配置下拉框中应能选到“Node：环境文件演示”。如果属性有红色波浪线，先看当前 type 和 request；不同调试器的配置属性并非通用设置。这里把 envFile 放在启动对象中，而不是放进全局 settings.json 或 tasks.json。

${workspaceFolder} 代表工作区文件夹路径，它让 envFile 得到明确的文件位置。多根工作区中应确认配置所属文件夹，必要时使用对应的命名工作区变量。修改 cwd 是控制程序工作目录，不是把 envFile 变成所有目录中的自动搜索规则。

3. 选择配置启动调试并排除覆盖项

打开 env-probe.cjs，在 console.log 所在行左侧行号栏单击，设置断点。回到 Run and Debug 的下拉框，明确选中 Node：环境文件演示，再点击绿色启动按钮或按 F5。不要改用另一个“运行代码”扩展按钮，否则启动入口可能根本不读取这份 launch.json。

当程序停在断点处，在左侧 Variables（变量）区域展开 snapshot，或在 Watch（监视）中添加 snapshot.stage、snapshot.apiBase。在文件与配置均如本文、没有额外覆盖时，应分别看到 debug-file 和 https://example.invalid。读者也可以继续执行后看 Debug Console 的定向输出；不要为排障打印所有环境变量。

如果值不符合预期，先看当前选中的启动项，再检查 envFile 的实际路径、拼写与保存状态。还要检查启动对象是否有同名 env：

{
  // 配置片段：同名 env 会覆盖环境文件中的 APP_STAGE
  "envFile": "${workspaceFolder}/.env.debug",
  "env": {
    "APP_STAGE": "launch-override"
  }
}

这是配置片段，不是可以单独运行的完整 launch.json。若把它合入本例的启动对象，APP_STAGE 应取 launch-override。需要恢复文件值时，只删除该启动对象中这一条覆盖项，不要删除团队的整个 env 对象。之后点击调试工具栏的 Stop，保存文件并重新启动会话，避免用旧进程判断新文件。

改完环境文件会立即改变已经运行的进程吗？不要这样假设。停止原会话并重新启动，才适合判断这次启动时传入的值。

envFile 会给所有集成终端设置变量吗？它服务于相应调试配置，不是终端全局环境设置。普通终端执行、任务与不同调试器有各自的环境来源。

attach 到现有进程能补上启动时缺失的变量吗？本例是 launch。不要把 attach 配置当作重建现有进程启动环境的方法；应在进程真正的启动位置设置环境并重新启动它。

若要撤销演示，只移除新增启动对象与自己创建的演示文件；真实项目保留原配置。实际采用时，把入口、文件位置、覆盖优先级和新会话这四件事对应起来，通常比反复修改同一个变量名更有效。

参考：VS Code Node.js 调试文档、调试配置官方说明。