调试时环境变量不生效，须确认launch.json位于项目根目录.vscode文件夹内，env或envfile字段显式配置变量；若用runtimeexecutable（如npm），env仅注入父进程，需改用program直调js入口以确保100%透传。
调试时环境变量不生效？先确认 launch.json 是否在正确位置
VSCode 的 Node.js 调试环境变量只通过 .vscode/launch.json 中的 env 或 envFile 字段注入，process.env 不会自动读取系统 shell 的环境变量。如果你在终端里 export NODE_ENV=development 后直接按 F5 调试，这些变量不会传递进去。
-
launch.json必须放在项目根目录下的.vscode/文件夹内，不是随便放一个地方就能被识别 - 如果项目有多个 workspace（比如用
code .打开的是文件夹，但实际是多根工作区），确保你编辑的是当前激活文件夹对应的.vscode/launch.json - 修改后无需重启 VSCode，但必须重新启动调试会话（停止再点 ▶️）才能生效
env 和 envFile 该怎么选？看变量是否需要复用或保密
env 适合写死少量、非敏感变量；envFile 更适合管理多组配置（如 dev/staging/prod）或避免把密钥硬编码进版本库。
- 用
env：直接在launch.json里写键值对，比如"NODE_ENV": "development", "PORT": "3001" - 用
envFile：指定一个.env文件路径（支持相对路径），VSCode 会按行解析KEY=VALUE格式——注意它不支持# 注释、空行或引号包裹值（API_KEY="abc"会被当成字面量"abc"，含双引号） - 若同时配置了
env和envFile，后者优先级更高，同名变量会被覆盖
{
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch via NPM",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"envFile": "${workspaceFolder}/.env.local",
"env": {
"NODE_OPTIONS": "--enable-source-maps"
}
}
]
}
为什么 process.env 里看不到变量？检查调试入口是否绕过了 env 注入
常见陷阱是用了 runtimeExecutable（比如指向 npm 或 yarn），此时 VSCode 实际启动的是 npm 进程，再由 npm 启动你的脚本——env 只注入到 npm 进程，不一定透传给子进程，尤其某些 npm 版本或脚本写法会导致丢失。
- 最稳的方式：去掉
runtimeExecutable，直接调试 JS 入口文件（如"program": "${workspaceFolder}/src/index.js"），这样env会 100% 注入到 Node 进程 - 如果必须用 npm script，确认你的
package.json脚本没有用cross-env以外的方式覆盖环境变量（比如NODE_ENV=production npm start在 shell 中运行没问题，但在 VSCode 调试里这种写法无效） - 验证方法：在代码里加一行
console.log(process.env.NODE_ENV)，断点停住后看输出；或者在调试控制台执行process.env查看完整对象
Windows 用户特别注意 PATH 和反斜杠问题
Windows 下 env 里的 PATH 变量容易出错，VSCode 默认用正斜杠，但 Node.js 在 Windows 上对路径分隔符敏感。
- 不要写
"PATH": "C:mytools;%PATH%"—— 反斜杠会被 JSON 解析为转义字符，变成非法字符串 - 正确写法是双反斜杠：
"PATH": "C:\mytools;%PATH%"，或者统一用正斜杠："PATH": "C:/mytools;%PATH%" - 如果依赖本地 CLI 工具（比如
prisma），确保该工具所在目录已加到env.PATH，否则spawn或exec会报Error: spawn prisma ENOENT
调试配置里环境变量看似简单，但实际生效依赖 launch.json 位置、入口方式、平台路径规则三者配合。最容易被忽略的是：你以为改了 .env 文件就自动生效，其实得确认 envFile 路径拼写正确，且文件编码是 UTF-8 无 BOM——否则某些值会解析失败。
