开发工具 VS Code launch 注入环境变量 怎样处理

在 VS Code 里按 F5 启动调试时，如果程序读不到预期的环境变量，优先检查当前选中的 launch.json 配置，而不是先改系统环境。对一次调试启动来说，最直接的写法是把键值放进该配置的 env；变量较多或不希望全部写进 JSON 时，再用 envFile 指向环境文件。

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

VS Code 的环境变量注入属于具体调试配置。先确认工作区、配置项和调试器类型，再判断变量值；不要把 settings.json、终端启动脚本和 launch.json 当成同一个作用域。

• env：直接为本次调试配置提供键值，适合少量、明确的调试变量。
• envFile：从文件读取环境变量，适合本地开发配置较多的场景。
• ${workspaceFolder}：引用当前工作区目录，避免把路径写死。
• ${env:NAME}：读取启动 VS Code 时已经存在的环境变量，不等于在当前配置里新建变量。

先找到真正生效的 launch 配置

按 ⇧⌘D（Windows、Linux 为 Ctrl+Shift+D）打开“运行和调试”，选择创建或打开 launch.json。项目级配置通常位于工作区根目录的 .vscode/launch.json，而且 configurations 数组中的每个对象都会出现在调试配置下拉框里。

这里最容易出现的误判是：文件写对了，但启动时选中了另一个配置。先看下拉框中的 name，确认它对应的是正在编辑的对象；多根工作区还要确认配置属于正确的工作区文件夹。第一张说明图把入口、配置对象和三个相关字段放在同一界面里，帮助定位“改了但没生效”的第一层原因。

用 env 注入少量固定变量

如果只是给本地调试设置模式、日志级别或测试开关，可以直接在目标配置里加入 env。下面的 JSON 保持有效格式，没有插入注释；关键字段的作用写在代码块后，避免让配置文件因为注释语法而无法解析。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "调试当前程序",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/app.js",
      "cwd": "${workspaceFolder}",
      "env": {
        "APP_MODE": "debug",
        "LOG_LEVEL": "info"
      }
    }
  ]
}

env 是键值对象，作用范围是这个调试配置启动的程序。cwd 只负责工作目录，不会自动创建环境变量；program 负责指定入口。实际项目使用 Python、Java、C++ 或其他调试器时，type 和可用属性应以该调试器提供的 IntelliSense 为准，不能把一个调试器的字段直接套到另一个调试器。

变量较多时改用 envFile

当本地调试变量比较多，可以把它们放在环境文件中，再在 launch 配置里指定 envFile。文件内容按环境变量文件的约定使用键值行，例如：

# 这里只保存本地调试所需的非敏感示例值
APP_MODE=debug
API_BASE=/api
LOG_LEVEL=info

对应的 launch 配置可以写成：

{
  "name": "读取本地调试环境",
  "type": "node",
  "request": "launch",
  "program": "${workspaceFolder}/app.js",
  "envFile": "${workspaceFolder}/.env.debug"
}

不要把真实密钥、访问令牌或生产凭据提交到工作区；可以把环境文件加入版本控制忽略规则，并为团队提供不含敏感值的示例文件。若同一配置同时定义了 env 和 envFile，以调试器文档说明的合并和覆盖规则为准；Node.js 调试文档明确说明，env 中的同名值会覆盖文件加载的值，因此排查时先找重复键。

用变量替换处理路径和已有环境

配置需要在不同机器或不同工作区复用时，不要把用户目录写死。${workspaceFolder} 代表当前工作区目录，${env:NAME} 则读取 VS Code 进程启动时已有的 NAME 环境变量。二者的边界很重要：前者是 VS Code 提供的路径变量，后者是外部环境输入，并不会因为你在 env 中写了另一个键就自动推导出来。

{
  "name": "复用工作区环境",
  "type": "node",
  "request": "launch",
  "program": "${workspaceFolder}/app.js",
  "cwd": "${workspaceFolder}",
  "env": {
    "API_BASE": "${env:DEV_API_BASE}",
    "CONFIG_DIR": "${workspaceFolder}/config"
  }
}

如果 DEV_API_BASE 在启动 VS Code 前不存在，引用结果就不会变成你期望的地址。此时可改用 envFile 或直接在当前配置的 env 中给出明确值。路径中包含空格时，数组中的每个参数仍保持为单独参数，不要为了“保护空格”再额外包一层转义引号。

启动后怎样确认变量已经注入

保存配置后，在“运行和调试”视图选择目标配置并按 F5。成功条件不是看编辑器有没有红色波浪线，而是程序实际读取到的值与当前配置一致。可以在断点处观察变量，也可以在程序的调试输出中打印非敏感的模式值；调试期间不要输出密钥或令牌。

如果仍然为空，按这个顺序排查：

1. 确认调试下拉框选中的 name 与正在编辑的配置相同。
2. 确认程序使用的变量名和 env 或 envFile 中的键完全一致，大小写不要凭感觉修改。
3. 确认 envFile 路径是当前工作区可访问的文件，并检查同名键是否被覆盖。
4. 检查 type 对应的调试扩展是否安装并支持这些属性；属性不支持时，VS Code 通常会在配置处提示校验问题。
5. 如果依赖外部环境变量，重启调试会话，必要时重启 VS Code 后再看 ${env:NAME} 的来源是否存在。

常见问题

把变量写进 settings.json 能让 F5 读取吗？

不能把它当成通用替代方案。调试启动变量应优先写在当前调试器支持的 launch.json 配置中；设置文件、终端启动脚本和调试配置属于不同入口。

envFile 写了变量，env 还能再写同名键吗？

可以出现同名键，但会引入覆盖判断。以 Node.js 调试为例，env 中的值会覆盖文件加载的同名值；如果不是 Node.js，应以对应调试器的官方属性说明为准。

为什么换了终端里的环境变量，launch.json 还是旧值？

${env:NAME}读取的是 VS Code 进程能够看到的环境。若 VS Code 早于终端启动，后来才在终端里设置变量，不一定会反映到已经运行的编辑器进程；重启 VS Code 或直接使用 envFile 更容易复现。

怎样处理敏感变量？

不要把真实密钥写入文章示例、版本库或调试输出。使用本地忽略的环境文件、系统密钥管理和最小权限凭据，并只在断点或控制台展示脱敏后的状态。