Environment Configuration

何时使用此技能

• 新项目启动：进行初始环境配置
• 多环境管理：分离开发、预发布和生产环境
• 团队协作：共享一致的开发环境配置

操作指南

步骤 1：.env 文件结构

.env.example (模板文件):

# 应用配置
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000

# 数据库配置
DATABASE_URL=postgresql://user:password@localhost:5432/myapp
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=10

# Redis 缓存
REDIS_URL=redis://localhost:6379
REDIS_TTL=3600

# 认证配置
JWT_ACCESS_SECRET=change-me-in-production-min-32-characters
JWT_REFRESH_SECRET=change-me-in-production-min-32-characters
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

# 邮件服务
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# 外部 API 密钥
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_PUBLISHABLE_KEY=pk_test_xxx
AWS_ACCESS_KEY_ID=AKIAXXXXXXXX
AWS_SECRET_ACCESS_KEY=xxxxxxxx
AWS_REGION=us-east-1
AWS_S3_BUCKET=myapp-uploads

# 监控配置
SENTRY_DSN=https://xxx@sentry.io/xxx
LOG_LEVEL=info

# 功能开关
ENABLE_2FA=false
ENABLE_ANALYTICS=true

.env.local (每个开发者自己的配置):

# 开发者个人设置（需添加到 .gitignore）
DATABASE_URL=postgresql://localhost:5432/myapp_dev
LOG_LEVEL=debug

.env.production:

NODE_ENV=production
PORT=8080
APP_URL=https://myapp.com

DATABASE_URL=${DATABASE_URL}  # 从环境变量中注入
REDIS_URL=${REDIS_URL}

JWT_ACCESS_SECRET=${JWT_ACCESS_SECRET}
JWT_REFRESH_SECRET=${JWT_REFRESH_SECRET}

LOG_LEVEL=warn
ENABLE_2FA=true

步骤 2：类型安全的环境变量 (TypeScript)

config/env.ts:

import { z } from 'zod';
import dotenv from 'dotenv';

// 加载 .env 文件
dotenv.config();

// 定义验证模式
const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  PORT: z.coerce.number().default(3000),

  DATABASE_URL: z.string().url(),

  JWT_ACCESS_SECRET: z.string().min(32),
  JWT_REFRESH_SECRET: z.string().min(32),

  SMTP_HOST: z.string(),
  SMTP_PORT: z.coerce.number(),
  SMTP_USER: z.string().email(),
  SMTP_PASSWORD: z.string(),

  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),

  LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
});

// 验证并导出
export const env = envSchema.parse(process.env);

// 使用方式：
// import { env } from './config/env';
// console.log(env.DATABASE_URL); // 类型安全！

错误处理:

try {
  const env = envSchema.parse(process.env);
} catch (error) {
  if (error instanceof z.ZodError) {
    console.error('❌ 环境变量无效:');
    error.errors.forEach((err) => {
      console.error(`  - ${err.path.join('.')}: ${err.message}`);
    });
    process.exit(1);
  }
}

步骤 3：按环境配置分离

config/index.ts:

interface Config {
  env: string;
  port: number;
  database: {
    url: string;
    pool: { min: number; max: number };
  };
  jwt: {
    accessSecret: string;
    refreshSecret: string;
    accessExpiry: string;
    refreshExpiry: string;
  };
  features: {
    enable2FA: boolean;
    enableAnalytics: boolean;
  };
}

const config: Config = {
  env: process.env.NODE_ENV || 'development',
  port: parseInt(process.env.PORT || '3000'),

  database: {
    url: process.env.DATABASE_URL!,
    pool: {
      min: parseInt(process.env.DATABASE_POOL_MIN || '2'),
      max: parseInt(process.env.DATABASE_POOL_MAX || '10'),
    },
  },

  jwt: {
    accessSecret: process.env.JWT_ACCESS_SECRET!,
    refreshSecret: process.env.JWT_REFRESH_SECRET!,
    accessExpiry: process.env.JWT_ACCESS_EXPIRY || '15m',
    refreshExpiry: process.env.JWT_REFRESH_EXPIRY || '7d',
  },

  features: {
    enable2FA: process.env.ENABLE_2FA === 'true',
    enableAnalytics: process.env.ENABLE_ANALYTICS !== 'false',
  },
};

// 验证必需字段
const requiredEnvVars = [
  'DATABASE_URL',
  'JWT_ACCESS_SECRET',
  'JWT_REFRESH_SECRET',
];

for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`缺少必需的环境变量: ${envVar}`);
  }
}

export default config;

步骤 4：按环境区分配置文件

config/environments/development.ts:

export default {
  logging: {
    level: 'debug',
    prettyPrint: true,
  },
  cors: {
    origin: '*',
    credentials: true,
  },
  rateLimit: {
    enabled: false,
  },
};

config/environments/production.ts:

export default {
  logging: {
    level: 'warn',
    prettyPrint: false,
  },
  cors: {
    origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
    credentials: true,
  },
  rateLimit: {
    enabled: true,
    windowMs: 15 * 60 * 1000,
    max: 100,
  },
};

config/index.ts (整合):

import development from './environments/development';
import production from './environments/production';

const env = process.env.NODE_ENV || 'development';

const configs = {
  development,
  production,
  test: development,
};

export const environmentConfig = configs[env];

步骤 5：Docker 环境变量配置

docker-compose.yml:

version: '3.8'

services:
  app:
    build: .
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.local
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp

  redis:
    image: redis:7-alpine

输出格式

project/
├── .env.example           # 环境变量模板（可提交）
├── .env                   # 本地环境配置（需 gitignore）
├── .env.local             # 个人开发配置（需 gitignore）
├── .env.production        # 生产环境配置（需 gitignore 或使用密钥管理工具）
├── config/
│   ├── index.ts           # 主配置文件
│   ├── env.ts             # 环境变量验证
│   └── environments/
│       ├── development.ts
│       ├── production.ts
│       └── test.ts
└── .gitignore

.gitignore:

.env
.env.local
.env.*.local
.env.production

约束条件

强制性规则 (必须遵守)

1. 提供 .env.example：列出所有必需的环境变量
2. 验证机制：缺少必需环境变量时应报错
3. .gitignore 配置：绝不能提交 .env 文件

禁止事项 (绝不能做)

1. 提交密钥：绝不能提交 .env 文件
2. 硬编码：不要在代码中硬编码环境相关的设置

最佳实践

1. 12 要素应用：通过环境变量管理配置
2. 类型安全：使用 Zod 进行运行时验证
3. 密钥管理：使用 AWS Secrets Manager, Vault 等工具

参考链接

• dotenv
• Zod
• 12 要素应用 – 配置

元数据

版本信息

• 当前版本：1.0.0
• 最后更新：2025-01-01
• 兼容平台：Claude, ChatGPT, Gemini

标签

#环境变量 #配置管理 #env变量 #dotenv #配置工具 #实用工具

使用示例

示例 1：基础用法

示例 2：高级用法