本文详解为何 source .env 无法让 Node.js 进程读取环境变量，并提供基于 dotenv 的标准解决方案，涵盖安装、配置、常见陷阱及最佳实践。
本文详解为何 `source .env` 无法让 node.js 进程读取环境变量，并提供基于 `dotenv` 的标准解决方案，涵盖安装、配置、常见陷阱及最佳实践。
在 Node.js 开发中，.env 文件常用于管理本地开发环境的配置（如端口、数据库地址、API 密钥等）。但一个常见误区是：在 Shell 中执行 source .env 并不能自动将变量注入 Node.js 进程的 process.env。这是因为 source 仅将变量注入当前 Shell 环境，而 Node.js 启动时会创建独立的子进程——它默认继承的是父 Shell 的环境快照，且不会动态感知后续 Shell 中通过 source 设置的变量（除非显式导出并启动新 Shell）。
要让 Node.js 正确读取 .env 中的 PORT=5000，必须在 JavaScript 运行时主动加载并解析该文件。推荐使用官方维护、社区广泛采用的 dotenv 包：
✅ 正确步骤（以 Express 应用为例）
-
安装依赖
npm install dotenv
-
在入口文件（如 index.js 或 app.js）顶部立即加载
⚠️ 关键：require('dotenv').config() 必须放在所有业务代码之前（尤其是 app.listen() 之前），确保环境变量在任何逻辑执行前已就绪：const express = require('express'); const app = express(); // ✅ 必须放在最上方（模块引入后立即调用） require('dotenv').config(); // 现在 process.env.PORT 已可用 const PORT = process.env.PORT || 3000; if (!process.env.PORT) { throw new Error('Missing PORT in .env file or environment'); } app.listen(PORT, () => { console.log(`✅ Server running on http://localhost:${PORT}`); }); -
验证 .env 文件位置与格式
- .env 文件应与入口 JS 文件位于同一目录下（默认行为）；若需自定义路径，可传入选项：
require('dotenv').config({ path: './config/.env' }); - 确保无语法错误：键名不带空格，值无需引号（除非含空格或特殊字符），注释以 # 开头：
PORT=5000 DATABASE_URL=postgres://localhost/myapp # NODE_ENV=development ← 注释行会被忽略
- .env 文件应与入口 JS 文件位于同一目录下（默认行为）；若需自定义路径，可传入选项：
❌ 常见错误与注意事项
- source .env 无效的原因：Shell 变量 ≠ 进程环境变量。Node.js 不会回溯读取 Shell 的临时变量，即使你随后运行 node index.js，该命令启动的新进程只继承 Shell 启动时的初始环境。
- 未重启服务：修改 .env 或添加 dotenv.config() 后，必须手动重启 Node.js 进程（如 Ctrl+C 后重新运行 node index.js），热重载工具（如 nodemon）通常能自动触发，但仍需确认其监听了 .env 文件变化（可通过 nodemon --watch .env index.js 显式指定）。
- 重复调用 config()：dotenv.config() 默认只执行一次（幂等），但多次调用无害；不过建议仅在应用启动时调用一次。
- 生产环境提醒：dotenv 仅用于开发/测试。生产环境应通过操作系统级环境变量（如 Linux 的 export PORT=5000 或容器编排工具的 env 配置）设置敏感信息，避免将 .env 提交至版本库（务必在 .gitignore 中加入 .env）。
✅ 总结
process.env 是 Node.js 进程启动时捕获的环境快照，无法通过 Shell 的 source 动态更新。可靠方案是：使用 dotenv 在 JS 入口处主动解析 .env 文件，并将其键值对挂载到 process.env 上。遵循“早加载、明路径、勤验证、慎提交”的原则，即可稳定、安全地管理环境配置。
