dotenv — Node.js 环境变量加载器

dotenv 是一个零依赖模块，可将 .env 文件中的环境变量加载到 process.env 中。

使用场景

适用于需要加载 .env 文件、配置环境变量、处理 API 密钥和敏感配置、设置多环境变量，或使用 dotenv/dotenvx 的情况。

触发关键词包括：“dotenv”、“环境变量”、“env 文件”、“dotenvx”、“process.env”、“加密的 env”等。

安装

npm install dotenv
# 或
bun add dotenv
yarn add dotenv
pnpm add dotenv

基本用法

创建 .env 文件

# .env
HELLO="World"
OPENAI_API_KEY="sk-your-key-here"
DATABASE_URL="postgres://localhost/mydb"
PORT=3000
DEBUG=true

加载到应用程序中

// CommonJS — 在入口文件最上方尽早调用
require('dotenv').config()

console.log(process.env.HELLO)       // "World"
console.log(process.env.OPENAI_API_KEY)

// ES 模块
import 'dotenv/config'

// 或需要自定义配置时：
import dotenv from 'dotenv'
dotenv.config({ path: '/custom/path/to/.env' })

$ node index.js
◇ 注入环境变量 (4) 来自 .env

.gitignore 安全性

切勿将 .env 提交到版本控制系统：

# .gitignore
.env
.env.local
.env.*.local

提交一个 .env.example 模板文件（不含真实密钥），供团队成员参考。

config() 配置选项

dotenv.config({
  path: '/custom/path/to/.env',     // 默认：path.resolve(process.cwd(), '.env')
  encoding: 'utf8',                  // 文件编码，默认 utf8
  debug: true,                       // 启用调试日志
  override: false,                   // 是否覆盖已存在的 process.env 值
  processEnv: {},                    // 自定义目标对象（默认为 process.env）
  quiet: false,                      // v17.2+ 静默模式
})

返回值：

const result = dotenv.config()
// result.parsed → { HELLO: 'World', PORT: '3000' }
// result.error  → 错误对象或 undefined

环境变量配置（DOTENV_CONFIG_*）

可通过环境变量覆盖配置选项（命令行参数优先级更高）：

DOTENV_CONFIG_PATH=/custom/path/.env \
DOTENV_CONFIG_DEBUG=true \
DOTENV_CONFIG_QUIET=true \
node index.js

或在 .env 文件内部设置：

DOTENV_CONFIG_QUIET=true
HELLO="World"

parse() — 手动解析

const dotenv = require('dotenv')

const buf = Buffer.from('HELLO=world\nPORT=3000')
const config = dotenv.parse(buf)
// { HELLO: 'world', PORT: '3000' }

预加载

无需在代码中引入 dotenv，可通过命令行预加载：

node -r dotenv/config your_script.js
node -r dotenv/config your_script.js dotenv_config_path=/custom/path/.env

.env 文件格式说明

基础格式

KEY=value
KEY2="带空格的值"
KEY3='单引号值'

注释

# 这是注释
SECRET_KEY=abc123  # 行尾注释
HASH="包含#的值"  # 包含 # 的值必须用引号包裹

多行值（v15.0.0+）

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
Line1
Line2
-----END RSA PRIVATE KEY-----"

# 或使用 \n
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nLine1\nLine2\n-----END RSA PRIVATE KEY-----"

TypeScript 支持

import dotenv from 'dotenv'
dotenv.config()

// 或
import 'dotenv/config'

// 声明类型增强
declare global {
  namespace NodeJS {
    interface ProcessEnv {
      OPENAI_API_KEY: string
      DATABASE_URL: string
    }
  }
}

dotenvx — 高级功能

dotenvx 是 dotenv 的升级版 CLI 工具，提供加密、变量扩展和多环境管理等高级功能。

安装

npm install -g @dotenvx/dotenvx
# 或
brew install dotenvx
# 或
curl -fsS https://dotenvx.sh/ | sh

变量扩展

# .env
USERNAME="admin"
DATABASE_URL="postgres://${USERNAME}@localhost/mydb"

dotenvx run -- node index.js

命令替换

DATABASE_URL="postgres://$(whoami)@localhost/mydb"

多环境管理

# 创建生产环境文件
echo "HELLO=production" > .env.production

# 加载特定环境
dotenvx run -f=.env.production -- node index.js

# 加载多个文件（左侧优先级更高）
dotenvx run -f=.env.local -f=.env -- node index.js

加密（可安全提交至 Git）

# 加密 .env 文件
dotenvx encrypt -f .env.production

# 生成 .env.keys（包含解密密钥）→ 添加到 .gitignore
# 此时加密后的 .env.production 可安全提交

# 部署时设置解密密钥
heroku config:set DOTENV_PRIVATE_KEY_PRODUCTION="<来自 .env.keys 的密钥>"

# 运行时自动解密
dotenvx run -- node index.js

功能对比表

常见模式与最佳实践

应用程序入口加载

// app.js — 第一行
require('dotenv').config()

const express = require('express')
const app = express()
// 后续所有模块均可通过 process.env 读取值

加载并验证

const dotenv = require('dotenv')
dotenv.config()

const required = ['DATABASE_URL', 'SECRET_KEY']
for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`缺少必需的环境变量: ${key}`)
  }
}

多包仓库（Monorepo）场景

apps/backend/
├── .env          ← 放在应用的运行目录中
├── app.js
└── package.json

多环境文件建议

• .env — 本地开发环境（默认）
• .env.production — 生产环境
• .env.test — 测试环境
• .env.example — 模板文件（提交到 Git，不包含实际值）

不要让 .env.production 继承 .env 中的值 —— 每个环境文件应独立完整。

日志控制

# 抑制注入日志
DOTENV_CONFIG_QUIET=true node index.js

故障排查