Node.js 环境变量管理（dotenv）

dotenv 将 .env 文件中的配置加载到 process.env，实现配置与代码分离。

安装与基本使用

安装

npm install dotenv

创建 .env 文件

# .env 文件
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASS=secret123
API_KEY=your-api-key
NODE_ENV=development

加载配置

// 方式一：尽早加载
require('dotenv').config();

// 方式二：ES Module
import 'dotenv/config';

// 访问环境变量
console.log(process.env.DB_HOST);    // localhost
console.log(process.env.DB_PORT);    // 5432
console.log(process.env.NODE_ENV);   // development

配置选项

指定路径

require('dotenv').config({
  path: './config/.env.local'  // 自定义路径
});

常用选项

require('dotenv').config({
  path: './.env',           // 文件路径
  encoding: 'utf8',         // 编码
  debug: process.env.DEBUG, // 调试模式
  override: true            // 覆盖已存在的变量
});

process.env 使用

读取与默认值

const host = process.env.DB_HOST || 'localhost';
const port = parseInt(process.env.DB_PORT, 10) || 3306;
const debug = process.env.DEBUG === 'true';
const timeout = Number(process.env.TIMEOUT) || 5000;

类型转换

// 字符串
const apiKey = process.env.API_KEY;

// 数字
const port = parseInt(process.env.PORT, 10);

// 布尔值
const isDev = process.env.NODE_ENV === 'development';

// 数组
const hosts = process.env.HOSTS?.split(',') || [];

// JSON 对象
const config = JSON.parse(process.env.CONFIG || '{}');

多环境配置

环境文件命名

.env                # 默认
.env.local          # 本地覆盖（不提交 git）
.env.development    # 开发环境
.env.test           # 测试环境
.env.production     # 生产环境

按环境加载

const env = process.env.NODE_ENV || 'development';
require('dotenv').config({ path: `.env.${env}` });

Git 忽略配置

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

dotenv-safe 校验

npm install dotenv-safe

// 创建 .env.example 作为模板
require('dotenv-safe').config();

// 缺少必要变量时会报错

注意事项

• .env 文件不要提交到 Git，包含敏感信息
• 提供 .env.example 模板文件供参考
• process.env 的值都是字符串，需手动转换类型
• 生产环境建议使用系统环境变量或配置中心

要点总结

• dotenv.config() 加载 .env 文件到 process.env
• 使用 || 提供默认值
• 多环境使用 .env.{environment} 文件
• 配置 .gitignore 防止敏感信息泄露
• dotenv-safe 可校验必要变量是否存在