Node.js 如何读取环境变量？

Node.js 读环境变量用 process.env.变量名，未设置时为 undefined。支持启动时传入、.env 文件（Node 20+ 原生 --env-file 或 dotenv 库）。本文给出完整用法与生产实践。

观测云编辑部 2026-09-28 3 分钟阅读更新于 2026-09-28

通过 process.env 对象读取，未设置时是 undefined：

const apiKey = process.env.API_KEY;

if (apiKey) {
  console.log('API_KEY 已配置');
} else {
  console.error('环境变量 API_KEY 未设置');
}

怎么设置环境变量

# Linux/macOS：导出到当前 shell
export API_KEY=your_api_key
node app.js

# 或一行内联（仅这条命令生效）
API_KEY=your_api_key node app.js

# Windows PowerShell
$env:API_KEY="your_api_key"
node app.js

.env 文件（开发标配）

项目根目录建 .env：

API_KEY=your_api_key
DB_URL=postgres://localhost:5432/mydb

Node 20.6+ 原生支持：

node --env-file=.env app.js

原生--env-file中，已存在的进程环境优先于文件；多个文件的覆盖关系应按版本确认。老版本用 dotenv 库（npm install dotenv，入口首行 require('dotenv').config()）。

安全红线：.env 必须加进 .gitignore，忽略规则不会清除已跟踪内容和历史，已泄露密钥需轮换并按流程清理。

生产实践

启动时校验必需变量：缺失就快速失败，别带着 undefined 跑：

const required = ['API_KEY', 'DB_URL'];
for (const key of required) {
  if (!process.env[key]) {
    console.error(`缺少必需环境变量: ${key}`);
    process.exit(1);
  }
}

给非敏感配置默认值：先在变量缺失时取默认值，再校验数字格式与业务允许范围（通常1–65535；需要自动分配端口时可允许0）；不要用 Number(...) || 3000 静默吞掉无效输入或0
类型转换：环境变量全是字符串，'false' 是真值！布尔判断写 process.env.DEBUG === 'true'；
密钥优先用密钥管理服务（KMS/Vault/云厂商 Secret Manager），环境变量是兜底方案。