在 Node.js 项目中,dotenv
是一个用于管理环境变量的流行工具,它通过 .env
文件加载配置,使得不同环境的配置管理更加方便和安全。以下是详细指南:
1. 安装 dotenv
npm install dotenv
2. 创建 .env
文件
在项目根目录创建 .env
文件,格式示例:
# 基础配置
PORT=3000
NODE_ENV=development
# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASS=secret
# API Keys
API_KEY=your_api_key_here
3. 使用 dotenv 加载配置
在项目入口文件(如 app.js
或 index.js
)的最顶部添加:
require('dotenv').config();
// 或带路径配置(如果.env文件不在根目录)
// require('dotenv').config({ path: '/custom/path/.env' });
4. 访问环境变量
const port = process.env.PORT;
const dbHost = process.env.DB_HOST;
5. 多环境配置策略
开发环境
- 使用
.env.development
- 本地运行自动加载
生产环境
-
使用系统环境变量(云平台配置)
-
禁用 .env 文件加载
(安全考虑):
if (process.env.NODE_ENV !== 'production') { require('dotenv').config(); }
测试环境
-
创建
.env.test
-
在测试脚本中指定:
before(() => { require('dotenv').config({ path: '.env.test' }); });
6. 安全最佳实践
-
Git 忽略:
# .gitignore .env .env*.local
-
配置模板:
创建.env.example
作为模板:PORT= DB_HOST= API_KEY=
-
敏感信息保护:
- 永远不要提交包含真实凭证的
.env
文件 - 生产环境使用加密的 Secret Management 服务(如 AWS Secrets Manager)
- 永远不要提交包含真实凭证的
7. 高级配置选项
require('dotenv').config({
path: '.env.production', // 指定文件路径
encoding: 'utf8', // 文件编码
override: true // 覆盖已存在的系统变量
});
8. TypeScript 支持
安装类型定义:
npm install @types/dotenv
类型声明示例:
declare global {
namespace NodeJS {
interface ProcessEnv {
NODE_ENV: 'development' | 'production';
PORT?: string;
DB_HOST: string;
}
}
}
9. 常见问题解决
问题:变量未加载
- 检查
.env
文件路径是否正确 - 确认文件使用 UTF-8 编码
- 确保变量没有空格(正确:KEY=value,错误:KEY = value)
问题:变量被覆盖
- 系统环境变量优先级高于
.env
文件 - 使用
override: true
强制覆盖
10. 生态系统扩展
-
dotenv-expand:支持变量扩展
DOMAIN=example.com API_URL=https://${DOMAIN}/api
-
cross-env:跨平台环境变量设置
cross-env NODE_ENV=development node app.js
通过合理使用 dotenv,可以实现:
✅ 安全隔离敏感配置
✅ 轻松管理多环境部署
✅ 保持代码库的整洁性
✅ 简化开发/测试/生产环境切换
记得定期审计环境变量权限,特别是在团队协作项目中!