vscode本身不读取.env文件，process.env仅反映操作系统或调试器注入的变量；秘钥必须通过dotenv加载（代码侧）或launch.json的env字段注入（调试侧），二者不能混用或错序。
VSCode 本身不读取 .env 文件，process.env 只反映操作系统或调试器注入的变量；秘钥必须通过 dotenv 加载（代码侧）或 launch.json 的 env 字段注入（调试侧），二者不能混用或错序。
为什么 process.env.MY_SECRET 总是 undefined？
常见原因不是 Node 没装好，而是环境变量根本没进进程。Node.js 原生只认启动时已存在的系统级变量（比如 shell 里 export MY_SECRET=xxx 后再运行 node app.js）。VSCode 终端能跑 node -v ≠ 调试器（F5）能读到变量 —— 它俩是独立进程，环境隔离。如果你靠 require('dotenv').config() 加载秘钥，但 app.js 已被其他模块提前 require 过，那 process.env 就永远拿不到值（模块缓存导致“迟到”）。
launch.json 中的 env 字段怎么写才生效？
这是最直接、最可控的方式，尤其适合开发阶段传秘钥。必须注意三点：
-
env必须写在configurations数组里的具体配置对象内（比如type: "node"那个），不能放在外层 - 路径和平台要对：Windows 用
terminal.integrated.env.windows，macOS/Linux 用terminal.integrated.env.linux或osx，但launch.json里的env是跨平台的 - 敏感值别硬编码进 JSON：用
${env:MY_SECRET}引用系统变量，或配合 VSCode 的envFile字段加载本地.env（仅限调试，不用于生产）
示例（.vscode/launch.json）：
{
"version": "0.2.0",
"configurations": [{
"type": "node",
"request": "launch",
"name": "Run with secrets",
"program": "${workspaceFolder}/app.js",
"env": {
"NODE_ENV": "development",
"API_KEY": "${env:API_KEY}",
"DB_PASSWORD": "dev-only-password"
},
"envFile": "${workspaceFolder}/.env.local"
}]
}
dotenv 加载失败的典型陷阱
即使你写了 require('dotenv').config()，也可能白忙一场：
-
.env文件路径不对：config({ path: './.env' })中的./是相对于当前执行目录（即node命令所在路径），不是文件所在目录；建议显式写绝对路径：path: require('path').join(__dirname, '.env') - 变量值带引号或空格：
API_KEY="abc123"会被当成字符串字面量，process.env.API_KEY实际是"abc123"（含双引号）；正确写法是API_KEY=abc123 - 没加
.gitignore：.env提交到仓库 = 秘钥泄露；务必确认.gitignore里有.env、.env.local - Node.js 版本太低：
dotenv@16+不支持 Node.js 10；若用旧版 Node，锁死dotenv@8.6.0
VSCode 终端和调试器的环境变量不一致怎么办？
这是最常被忽略的点：终端（Ctrl+`）和调试器（F5）是两套环境。终端的 $PATH 和变量来自 shell 配置（如 ~/.zshrc），而调试器只认 launch.json 或系统全局变量。如果 node -v 在终端能跑，但 F5 报 Cannot find module 'dotenv'，说明调试器没继承 NODE_PATH 或 PATH —— 此时要在 launch.json 的 env 里手动补全："NODE_PATH": "${env:NODE_PATH}"，或直接指定 "NODE_OPTIONS": "--loader ts-node/esm" 等参数。
真正麻烦的是跨平台协作：Mac 用户的 ~/.zshrc 里 export API_KEY=xxx，Windows 同事根本读不到。统一用 launch.json + envFile 或 CI/CD 注入，比依赖本地 shell 更可靠。
