6.2 KiB
6.2 KiB
环境配置指南
环境区分方案
项目支持通过 NODE_ENV 环境变量和不同的 .env 文件来区分开发和生产环境。
配置文件结构
backend/
├── .env # 默认配置（可选，作为后备）
├── .env.development # 开发环境配置
├── .env.production # 生产环境配置
└── .env.test # 测试环境配置（可选）
配置优先级
配置文件按以下优先级加载：
.env.${NODE_ENV}- 根据当前环境加载（最高优先级）.env- 默认配置文件（后备）
例如：
NODE_ENV=development→ 加载.env.developmentNODE_ENV=production→ 加载.env.production- 未设置
NODE_ENV→ 默认加载.env.development，然后.env
开发环境配置
创建 .env.development 文件
# 开发环境配置
NODE_ENV=development
# 开发数据库（本地数据库）
DATABASE_URL="mysql://root:password@localhost:3306/competition_management_dev?schema=public"
# JWT 密钥（开发环境可以使用简单密钥）
JWT_SECRET="dev-secret-key-not-for-production"
# 服务器端口
PORT=3001
# 日志级别
LOG_LEVEL=debug
# CORS 配置（开发环境允许所有来源）
CORS_ORIGIN=*
开发环境数据库命名建议
- 数据库名：
competition_management_dev - 便于区分：开发和生产使用不同的数据库
- 安全：避免误操作生产数据
生产环境配置
创建 .env.production 文件
# 生产环境配置
NODE_ENV=production
# 生产数据库（远程或云数据库）
DATABASE_URL="mysql://prod_user:strong_password@prod-db-host:3306/competition_management?schema=public&sslmode=require"
# JWT 密钥（必须使用强随机字符串）
# 生成方式: openssl rand -hex 32
JWT_SECRET="your-production-secret-key-must-be-strong-and-random-64-chars"
# 服务器端口
PORT=3001
# 日志级别
LOG_LEVEL=error
# CORS 配置（生产环境指定具体域名）
CORS_ORIGIN=https://yourdomain.com
# 数据库连接池配置
DB_POOL_MIN=2
DB_POOL_MAX=10
# SSL/TLS 配置
SSL_ENABLED=true
生产环境数据库配置要点
- 使用独立的数据库服务器
- 启用 SSL 连接（
sslmode=require） - 使用强密码
- 限制数据库用户权限（最小权限原则）
- 定期备份
使用方法
开发环境
# 方式 1: 设置环境变量后启动
NODE_ENV=development pnpm start:dev
# 方式 2: 在 package.json 中配置（推荐）
# 已自动配置，直接运行：
pnpm start:dev
生产环境
# 方式 1: 设置环境变量后启动
NODE_ENV=production pnpm start:prod
# 方式 2: 在部署脚本中设置
export NODE_ENV=production
pnpm start:prod
测试环境（可选）
# 创建 .env.test 文件
NODE_ENV=test
DATABASE_URL="mysql://root:password@localhost:3306/competition_management_test?schema=public"
JWT_SECRET="test-secret-key"
PORT=3002
# 运行测试
NODE_ENV=test pnpm test
数据库命名规范
建议使用以下命名规范来区分不同环境的数据库：
| 环境 | 数据库名 | 说明 |
|---|---|---|
| 开发 | competition_management_dev |
开发环境数据库 |
| 测试 | competition_management_test |
测试环境数据库 |
| 生产 | competition_management |
生产环境数据库 |
| 预发布 | competition_management_staging |
预发布环境数据库 |
创建不同环境的数据库
开发环境数据库
CREATE DATABASE competition_management_dev
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
生产环境数据库
CREATE DATABASE competition_management
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
环境变量管理最佳实践
1. 使用 .gitignore
确保 .env* 文件不被提交到版本控制：
# .env files
.env
.env.local
.env.*.local
.env.development
.env.production
.env.test
2. 提供示例文件
创建 .env.example 或 .env.*.example 文件作为模板：
# 开发环境示例
cp .env.development.example .env.development
# 生产环境示例
cp .env.production.example .env.production
3. 使用环境变量管理工具（生产环境）
- Docker: 使用
docker-compose.yml中的env_file - Kubernetes: 使用
ConfigMap和Secret - 云平台:
- AWS: Secrets Manager
- Azure: Key Vault
- GCP: Secret Manager
4. 验证配置
在应用启动时验证必要的环境变量：
// 可以在 main.ts 中添加验证
if (!process.env.DATABASE_URL) {
throw new Error('DATABASE_URL is required');
}
快速开始
1. 创建开发环境配置
cd backend
# 创建开发环境配置文件
cat > .env.development << EOF
NODE_ENV=development
DATABASE_URL="mysql://root:password@localhost:3306/competition_management_dev?schema=public"
JWT_SECRET="dev-secret-key"
PORT=3001
EOF
2. 创建生产环境配置
# 创建生产环境配置文件（不要提交到 Git）
cat > .env.production << EOF
NODE_ENV=production
DATABASE_URL="mysql://prod_user:password@prod-host:3306/competition_management?schema=public&sslmode=require"
JWT_SECRET="$(openssl rand -hex 32)"
PORT=3001
EOF
3. 初始化数据库
# 开发环境
NODE_ENV=development pnpm prisma:migrate dev
# 生产环境（部署时）
NODE_ENV=production pnpm prisma:migrate deploy
常见问题
Q: 如何确保使用正确的环境配置？
A: 在启动应用前检查 NODE_ENV 环境变量：
echo $NODE_ENV # 应该显示 development 或 production
Q: 生产环境配置应该存储在哪里？
A:
- 不要提交到 Git
- 使用环境变量管理工具（如 Docker secrets、K8s secrets）
- 或使用云平台提供的密钥管理服务
Q: 如何在不同环境间切换？
A: 通过设置 NODE_ENV 环境变量：
# 开发环境
export NODE_ENV=development
pnpm start:dev
# 生产环境
export NODE_ENV=production
pnpm start:prod
Q: 数据库迁移如何区分环境？
A: Prisma 会根据 DATABASE_URL 环境变量自动使用对应的数据库：
# 开发环境迁移
NODE_ENV=development pnpm prisma:migrate dev
# 生产环境迁移
NODE_ENV=production pnpm prisma:migrate deploy