VS Code 调试配置怎样传递环境变量

VS Code 调试配置传递环境变量，通常在所选调试器的 launch.json 配置中填写 env；若调试器支持，也可用 envFile 读取项目文件。本文用内置 Node.js 调试器说明：变量传给新启动的调试进程，不会自动改写已有终端或已经运行的程序。

官方地址：https://code.visualstudio.com/。下面使用无敏感的 APP_MODE 与 DEMO_PORT，目标是在断点处看到它们；操作图均为原创界面说明，不是截图或实际运行证据。其他语言须以对应调试扩展的字段说明为准。

1. 打开项目并准备调试入口

通过 File（文件）→ Open Folder（打开文件夹）打开一个专用演示目录；在 Explorer（资源管理器）点击 New File（新建文件），创建 env-check.js，将下面内容写入并保存。不要只打开一个游离文件，否则项目级配置的位置容易混淆。

// 只读取两项演示变量，避免把整个环境或密钥打印出来
const mode = process.env.APP_MODE;
const port = process.env.DEMO_PORT;
// 在下一行左侧边栏设置断点，停下时查看上面的局部变量
console.log({ mode, port });

点击 console.log 所在行的左侧边栏，出现红色断点标记即可。然后打开左侧 Run and Debug（运行和调试）视图，准备创建 launch.json。此时应能在资源管理器看到 env-check.js，文件没有未保存标记，断点已经显示；这只是准备完成，不代表变量已经注入。

2. 创建并保存环境变量配置

在 Run and Debug 视图选择 create a launch.json file（创建 launch.json 文件），选择 Node.js；若已经有配置，通过顶部齿轮按钮打开它。在资源管理器展开 .vscode，确认编辑的是当前项目的 launch.json，而不是 settings.json 或另一个项目的同名文件。

将配置整理为下面的 JSONC。launch.json 支持注释，env 的值在本例中全部使用字符串；program 指向刚才的文件。这里只保留一个名称清楚的配置，方便下一步选中。

{
  // 调试配置格式版本，不是 VS Code 软件版本
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "项目环境演示",
      // 固定入口和工作目录，避免调试到另一个文件
      "program": "${workspaceFolder}/env-check.js",
      "cwd": "${workspaceFolder}",
      // 变量仅传给本配置启动的 Node.js 进程
      "env": {
        "APP_MODE": "preview",
        "DEMO_PORT": "4711"
      },
      "console": "internalConsole"
    }
  ]
}

保存后，配置名称应出现在 Run and Debug 顶部下拉框中。如果编辑器标出不支持的字段，先确认 type 与实际调试器匹配，不要忽略提示。单个值就用 env，多个项目变量可以在同一个配置中增加 envFile：

// 加入刚才的配置对象；这里仅展示字段片段，不能单独作为完整 launch.json
"envFile": "${workspaceFolder}/.env.debug"

再通过 Explorer 的 New File 创建 .env.debug，保存以下内容。Node.js 调试器会读取这类定义文件，env 中的同名变量优先于文件值，所以添加文件后 APP_MODE 仍按 env 的 preview 取值。

# 无敏感演示变量文件，不是需要执行的 shell 脚本
APP_MODE=file-demo
# 没有在 env 中覆盖的键才使用文件值
DEMO_NOTE=local-check

此步完成的可见状态是 launch.json 已保存、配置名称可选、.env.debug 位于项目根目录；有文件不代表程序已经读取。若只是学习最小方案，可以先不添加 envFile。

3. 启动指定会话并核对变量

在 Run and Debug 顶部下拉框选择“项目环境演示”，点击绿色启动按钮或按 F5。程序在断点暂停后，展开 VARIABLES（变量）中的局部作用域，观察 mode 与 port；也可在 WATCH（监视）添加 mode、port 表达式。预期分别为字符串 preview 与 4711，此处是按示例推导的预期，不是本文实测输出。

若需要查看 envFile 中没有被覆盖的演示项，可以在暂停的当前会话 Debug Console（调试控制台）输入 process.env.DEMO_NOTE，预期为 local-check。不要输入 process.env 导出全部环境。确认完成后，通过调试工具栏的 Stop（停止）结束进程，修改变量后再重新启动该配置。

判断注入是否有效，应看目标进程读取的值，而不是在已有集成终端执行 echo。调试配置中的 env 不会自动设置终端的全局环境，也不会把变量补进已经运行的 attach 目标。attach 场景需在启动目标程序时准备环境。

常见未生效原因与配置归档

${env:NAME} 是配置中的变量引用语法，不是新建目标进程环境项的语法。不要假设同一个 env 对象先设置一项后，另一个字段的 ${env:NAME} 就能按赋值顺序读取它；配置替换不是 shell 脚本。明确值先用普通字符串，确有继承需求时再核对 VS Code 所在环境。

完成后保留可共享的 launch.json 和仅含占位值的 .env.example，说明需要安装的运行时与启动名称。真实密钥不要写入可提交配置或日志；本地敏感环境文件应按项目规则排除版本控制。环境文件不是保密工具。

相关问题

launch.json 的变量会影响普通终端运行吗？不会自动影响。普通终端、任务和调试配置是不同入口，应分别准备环境。

Python、Go 可以照抄 type 为 node 的配置吗？不可以。调试器类型、入口字段和环境文件支持要按相应扩展说明配置。

同一项目可以有两套变量吗？可以建立不同名称的 launch 配置，启动前确认选中的名称。避免把生产密钥和本地教学值放在可共享文件里。

参考：https://code.visualstudio.com/docs/nodejs/nodejs-debugging；调试界面：https://code.visualstudio.com/docs/debugtest/debugging；变量替换：https://code.visualstudio.com/docs/reference/variables-reference。