本文详解为何 source .env 无法让 node.js 进程读取环境变量，并提供基于 dotenv 的标准解决方案，包含安装、配置、验证及常见注意事项。
本文详解为何 source .env 无法让 node.js 进程读取环境变量，并提供基于 dotenv 的标准解决方案，包含安装、配置、验证及常见注意事项。
在 Unix/Linux/macOS 终端中执行 source .env 确实会将变量注入当前 Shell 进程（因此 echo $PORT 能正确输出），但 Node.js 启动时会创建一个全新的子进程，它不会自动继承 Shell 中通过 source 设置的变量（除非显式导出为 export PORT=5000，且该 Shell 是启动 Node 进程的父进程）。更关键的是：.env 文件本身不是 Shell 脚本，source 仅适用于可执行脚本格式；若 .env 仅为键值对（如 PORT=5000），source 实际上可能未生效或引发语法错误。
因此，Node.js 应用需借助专用库——dotenv——在运行时主动解析 .env 文件并挂载到 process.env。
✅ 正确做法：使用 dotenv 加载环境变量
-
安装依赖
npm install dotenv
-
在应用入口文件（如 index.js 或 app.js）顶部立即加载
⚠️ 必须在任何依赖 process.env 的代码之前调用 dotenv.config()，推荐作为第一行（除注释外）：
// index.js require('dotenv').config(); // ← 关键：必须最先执行！ const express = require('express'); const app = express(); const PORT = process.env.PORT || 3000; if (!process.env.PORT) { throw new Error('Missing PORT in environment variables'); } app.listen(PORT, () => { console.log(`✅ Server running on http://localhost:${PORT}`); }); -
确保 .env 文件格式规范
- 文件名必须为 .env（无扩展名或其他前缀）；
- 每行一个变量，使用 KEY=VALUE 格式；
- 不支持空格环绕等号（❌ PORT = 5000 → ❌；✅ PORT=5000 → ✅）；
- 支持引号包裹含空格/特殊字符的值（如 DB_URL="mongodb://localhost:27017/myapp"）；
- 注释以 # 开头（如 # This is a comment）。
? 验证与调试技巧
-
检查是否加载成功：
console.log('Loaded env:', process.env.PORT); // 应输出 '5000' console.log('All env keys:', Object.keys(process.env)); -
指定自定义 .env 路径（如项目根目录外）：
require('dotenv').config({ path: './config/.env' }); -
区分开发/生产环境（推荐配合 NODE_ENV）：
const envFile = process.env.NODE_ENV === 'production' ? '.env.production' : '.env'; require('dotenv').config({ path: envFile });
⚠️ 注意事项与最佳实践
- 不要提交 .env 到 Git：将其加入 .gitignore，避免敏感信息泄露；
- dotenv 仅用于开发环境：生产环境应通过系统级环境变量（如 Linux export PORT=5000）或容器编排工具（Docker/K8s）注入；
- 重启服务是必须的：修改 .env 后务必重启 Node 进程，dotenv 不支持热重载；
- 避免重复加载：多次调用 config() 可能导致覆盖或警告，建议仅在入口处调用一次；
- 类型安全提示：TypeScript 用户可配合 @types/dotenv 并声明 process.env.PORT 类型，提升开发体验。
遵循以上步骤，即可确保 process.env.PORT 在 Node.js 进程中稳定可用，彻底解决“环境变量始终为 undefined”的典型问题。
