如何在 VSCode 中为 Node 环境配置环境变量文件 .env

今天聊一个让不少开发者头疼的话题：在 VSCode 里给 Node.js 项目配置环境变量文件 .env。

先说说核心判断：VSCode 本身不会主动去读取、解析或注入任何 .env 文件——这个事实很重要，因为所有“变量没生效”的问题，本质上都出在运行时加载环节，而不是编辑器配置。

launch.json 的 envFile 字段只对调试生效

这是最常用也最省事的做法——不用动代码，但得明白它的适用范围：仅限于 VSCode 调试器启动的 Node.js 进程。

操作上要注意几点：

• .env 文件放项目根目录，跟 package.json 同级，编码必须是 UTF-8 无 BOM。怎么看？右下角状态栏就能查，不对的话点 “Sa ve with Encoding” 改成 “UTF-8”。
• 在 .vscode/launch.json 的配置里加上 envFile 字段，路径必须用 ${workspaceFolder} 表达式，比如这样："envFile": "${workspaceFolder}/.env"。千万别写成 ./.env 或 .env，某些版本里相对路径不太靠谱，而且也别指望它自动合并 .env.local 或者处理什么覆盖逻辑。
• 修改完 .env 文件后，记得重启调试会话——VSCode 不会热重载这个文件。

终端里运行 node 命令时 .env 不生效？别怪 VSCode

VSCode 内置终端是独立的 shell 进程，跟编辑器是解耦的，不会自动去 source 或解析 .env 文件。所以如果你在终端里直接敲 node index.js，指望 .env 里的变量自动生效，那就不太现实。

几个实用建议：

• Windows 下的 cmd 或 PowerShell 不支持 NODE_ENV=development node index.js 这种写法——要么报错，要么静默忽略。
• 正确的做法：安装 cross-env，命令是 npm install --sa ve-dev cross-env。然后在 package.json 的 scripts 里写 "dev": "cross-env NODE_ENV=development node index.js"。
• 如果要用 launch.json 启动带环境变量的终端命令，把 runtimeExecutable 设成 "cross-env"，runtimeArgs 写成 ["NODE_ENV=development", "node", "index.js"]。注意：别把环境变量塞进 args 字段里，那是传给 Node.js 的参数，不是 shell 环境变量。

require('dotenv').config() 必须在入口文件最顶部

这是最可靠的方式——在代码层面加载环境变量，但顺序和路径非常容易出错。

• 如果你用 ESM（ES Module），推荐写法是 import 'dotenv/config';，而且要放在所有其他 import 之前，包括 import { createServer } from 'http' 这种系统模块。
• CommonJS 下同理：require('dotenv').config(); 必须在 const app = express(); 或者数据库连接之前执行——差一行都可能出问题。
• 路径错误是最常见的坑：require('dotenv').config({ path: './config/.env' }) 里的路径是相对于当前 JS 文件的，不是项目根目录。比如入口是 src/index.js，.env 在根目录，那就要写成 { path: '../.env' }。
• 还有一个隐藏问题：文件如果包含 BOM 或者不可见的 Unicode 字符（比如零宽空格），dotenv 会静默失败，process.env 全为空。用 VSCode 打开 .env，切换到纯文本模式检查一下有没有异常字符。

DotENV 插件只负责高亮，跟运行无关

很多人装了插件后看到 .env 文件有颜色，就以为变量能用了——其实不然。插件只做两件事：语法高亮和颜色标记。

• 检查右下角语言模式是不是 Environment，如果不是，点一下切换过来，否则插件不触发高亮。
• 如果你用自定义文件名比如 .env.staging，得手动在 settings.json 里配置："files.associations": { "*.staging": "environment" }。
• 记住一条：插件完全不参与运行时加载。process.env.API_URL 还是 undefined 的话，这很正常——插件只是帮你少写错一个等号而已。

最后说一个容易被忽略的点：envFile 和 require('dotenv').config() 是两条独立路径，可以同时用，也可以只用一条。但如果同时用了，要注意变量优先级——envFile 加载的变量会覆盖 dotenv 解析的同名变量，而系统环境变量又会覆盖这两者。调试时看到的值，未必是你代码里真正拿到的值。这点很关键，值得多想一下。