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

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 Module
import 'dotenv/config'
// 或当需要自定义配置时：
import dotenv from 'dotenv'
dotenv.config({ path: '/custom/path/to/.env' })

安全 永远不要将 .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 → Error 或 undefined

环境变量配置（DOTENV_CONFIG_） 配置选项可以通过环境变量覆盖（CLI 参数优先）：

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="value with spaces"
KEY3='single quoted value'

注释

# 这是一个注释
SECRET_KEY=abc123 # 行末注释
HASH="value-with-#-in-it" # 值包含 # 必须用引号包裹

多行值（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 是一个升级的 CLI 工具，提供了高级功能，如加密、变量扩展和多环境管理。

安装

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

变量扩展

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

命令替换

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

多环境管理

# .env.production
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=""
# 自动解密在运行时
dotenvx run -- node index.js

用例比较 需求 | 工具 | 功能 ---|---|--- 加载 .env 到 process.env | dotenv | 加载 .env 文件 加密 env + 安全 Git 提交 | dotenvx encrypt | 加密 .env 文件 变量扩展 ${VAR} | dotenvx run | 扩展变量 命令替换 $(cmd) | dotenvx run | 替换命令 多环境切换 | dotenvx run -f=.env.ENV | 切换环境 生产部署解密 | dotenvx + DOTENV_PRIVATE_KEY | 解密 .env 文件

常见模式和最佳实践 应用程序入口加载

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