Node.js环境配置dotenv

在 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. 安全最佳实践

1. Git 忽略：

   # .gitignore
   .env
   .env*.local
   

2. 配置模板：
   创建 .env.example 作为模板：

   PORT=
   DB_HOST=
   API_KEY=
   

3. 敏感信息保护：

   • 永远不要提交包含真实凭证的 .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，可以实现：
✅ 安全隔离敏感配置
✅ 轻松管理多环境部署
✅ 保持代码库的整洁性
✅ 简化开发/测试/生产环境切换

记得定期审计环境变量权限，特别是在团队协作项目中！