如何在 Vercel 上实现多环境部署（开发、测试、生产）？

如何在 Vercel 上实现多环境部署（开发、测试、生产）？

在 Vercel 上实现多环境部署是现代软件开发的重要实践，它允许开发者在不同的环境中测试和部署代码，确保代码质量和稳定性。以下是详细的实现指南。

Vercel 环境概念

1. 三种主要环境

Production（生产环境）：

• 部署到主域名
• 使用生产数据库和 API
• URL: https://your-project.vercel.app 或自定义域名
• 触发条件：合并到主分支

Preview（预览环境）：

• 为每个分支或 PR 生成唯一 URL
• 使用测试数据库和 API
• URL: https://your-project-branch.vercel.app
• 触发条件：创建或更新 Pull Request

Development（开发环境）：

• 本地开发使用
• 使用开发数据库和 API
• 通过 Vercel CLI 访问
• 用于本地测试和调试

环境配置

1. 环境变量管理

在 Dashboard 中配置：

1. 进入项目设置
2. 选择 "Environment Variables"
3. 添加环境变量
4. 选择适用的环境（Production、Preview、Development）

配置示例：

变量名	Production	Preview	Development
DATABASE_URL	postgres://prod-db...	postgres://test-db...	postgres://dev-db...
API_URL	https://api.example.com	https://api-test.example.com	http://localhost:3001
NODE_ENV	production	preview	development
SENTRY_DSN	prod-dsn	test-dsn	dev-dsn

通过 CLI 配置：

bash
# 添加生产环境变量
vercel env add DATABASE_URL production
# 输入生产数据库 URL

# 添加预览环境变量
vercel env add DATABASE_URL preview
# 输入测试数据库 URL

# 添加开发环境变量
vercel env add DATABASE_URL development
# 输入开发数据库 URL

2. 环境特定配置

使用 vercel.json：

json
{
  "version": 2,
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "env": {
    "BUILD_TIME": "${NOW}"
  },
  "build": {
    "env": {
      "BUILD_ENV": "production"
    }
  }
}

在代码中使用环境变量：

javascript
// 获取环境
const environment = process.env.NODE_ENV || 'development';

// 根据环境配置
const config = {
  production: {
    apiUrl: 'https://api.example.com',
    databaseUrl: process.env.DATABASE_URL,
    enableAnalytics: true,
  },
  preview: {
    apiUrl: 'https://api-test.example.com',
    databaseUrl: process.env.DATABASE_URL,
    enableAnalytics: false,
  },
  development: {
    apiUrl: 'http://localhost:3001',
    databaseUrl: 'postgres://localhost:5432/dev',
    enableAnalytics: false,
  },
};

const currentConfig = config[environment] || config.development;

分支策略

1. Git Flow 分支模型

分支结构：

shell
main (生产环境)
  └── develop (开发环境)
       ├── feature/user-authentication
       ├── feature/payment-gateway
       └── bugfix/login-error

配置部署规则：

javascript
// vercel.json
{
  "git": {
    "deploymentEnabled": {
      "main": true,
      "develop": true,
      "feature/*": true,
      "hotfix/*": true
    }
  }
}

2. Trunk-Based Development

分支结构：

shell
main (主分支)
  ├── feature-branch-1
  ├── feature-branch-2
  └── hotfix-branch

配置：

javascript
{
  "git": {
    "deploymentEnabled": {
      "main": true,
      "feature-*": true,
      "hotfix-*": true
    }
  }
}

部署流程

1. 开发环境部署

本地开发：

bash
# 安装 Vercel CLI
npm install -g vercel

# 登录
vercel login

# 拉取环境变量
vercel env pull .env.local

# 启动本地开发服务器
vercel dev

# 或使用 npm scripts
npm run dev

开发环境配置：

javascript
// .env.local
DATABASE_URL=postgres://localhost:5432/dev
API_URL=http://localhost:3001
NODE_ENV=development

2. 预览环境部署

创建 Pull Request：

1. 创建功能分支
2. 推送代码到远程仓库
3. 创建 Pull Request
4. Vercel 自动创建预览部署
5. 获取预览 URL 进行测试

预览部署 URL：

• 格式：https://your-project-branch-name.vercel.app
• 示例：https://myapp-feature-auth.vercel.app

配置预览环境：

javascript
// vercel.json
{
  "preview": {
    "env": {
      "PREVIEW_MODE": "true"
    }
  }
}

3. 生产环境部署

合并到主分支：

1. 代码审查通过
2. 合并 Pull Request 到主分支
3. Vercel 自动触发生产部署
4. 部署到生产域名

手动触发生产部署：

bash
# 部署到生产环境
vercel --prod

# 或使用特定分支
vercel --prod --scope your-team

生产环境配置：

javascript
// vercel.json
{
  "production": {
    "env": {
      "PRODUCTION_MODE": "true"
    }
  }
}

数据库管理

1. 多环境数据库

使用不同的数据库：

javascript
// lib/database.js
const { PrismaClient } = require('@prisma/client');

let prisma;

if (process.env.NODE_ENV === 'production') {
  prisma = new PrismaClient({
    datasources: {
      db: {
        url: process.env.DATABASE_URL,
      },
    },
  });
} else if (process.env.NODE_ENV === 'preview') {
  prisma = new PrismaClient({
    datasources: {
      db: {
        url: process.env.DATABASE_URL,
      },
    },
  });
} else {
  prisma = new PrismaClient({
    datasources: {
      db: {
        url: 'postgres://localhost:5432/dev',
      },
    },
  });
}

module.exports = prisma;

2. 数据库迁移

环境特定的迁移：

bash
# 开发环境迁移
npm run migrate:dev

# 预览环境迁移
npm run migrate:preview

# 生产环境迁移
npm run migrate:prod

配置迁移脚本：

json
{
  "scripts": {
    "migrate:dev": "prisma migrate dev",
    "migrate:preview": "prisma migrate deploy",
    "migrate:prod": "prisma migrate deploy"
  }
}

测试策略

1. 环境特定测试

开发环境测试：

javascript
// tests/setup.js
const { execSync } = require('child_process');

if (process.env.NODE_ENV === 'development') {
  // 设置测试数据库
  execSync('npm run db:setup:test');
  
  // 运行单元测试
  execSync('npm run test:unit');
}

预览环境测试：

javascript
// tests/integration.js
describe('Integration Tests', () => {
  beforeAll(() => {
    // 跳过预览环境的某些测试
    if (process.env.NODE_ENV === 'preview') {
      console.log('Skipping expensive integration tests in preview');
    }
  });
  
  test('API integration', async () => {
    // 集成测试
  });
});

生产环境测试：

javascript
// tests/smoke.js
describe('Smoke Tests', () => {
  test('Production health check', async () => {
    if (process.env.NODE_ENV === 'production') {
      const response = await fetch('https://your-project.vercel.app/health');
      expect(response.status).toBe(200);
    }
  });
});

2. 自动化测试

配置 CI/CD：

yaml
# .github/workflows/test.yml
name: Test

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run test
      - run: npm run lint

监控和日志

1. 环境特定监控

配置监控：

javascript
// lib/monitoring.js
const Sentry = require('@sentry/node');

if (process.env.NODE_ENV === 'production') {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: 'production',
    tracesSampleRate: 1.0,
  });
} else if (process.env.NODE_ENV === 'preview') {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    environment: 'preview',
    tracesSampleRate: 0.5,
  });
} else {
  // 开发环境不启用 Sentry
  console.log('Monitoring disabled in development');
}

2. 日志管理

环境特定日志：

javascript
// lib/logger.js
const winston = require('winston');

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.Console({
      format: winston.format.simple(),
    }),
  ],
});

if (process.env.NODE_ENV === 'production') {
  logger.add(new winston.transports.File({ filename: 'error.log', level: 'error' }));
  logger.add(new winston.transports.File({ filename: 'combined.log' }));
}

module.exports = logger;

最佳实践

1. 环境隔离

严格的环境隔离：

• 每个环境使用独立的数据库
• 每个环境使用独立的 API 端点
• 每个环境使用独立的存储
• 避免环境间数据混淆

环境命名规范：

• 使用清晰的环境名称
• 在代码中明确标识环境
• 在日志中记录环境信息

2. 配置管理

使用配置文件：

javascript
// config/index.js
const config = {
  production: {
    apiUrl: process.env.API_URL,
    databaseUrl: process.env.DATABASE_URL,
    enableAnalytics: true,
    logLevel: 'error',
  },
  preview: {
    apiUrl: process.env.API_URL,
    databaseUrl: process.env.DATABASE_URL,
    enableAnalytics: false,
    logLevel: 'warn',
  },
  development: {
    apiUrl: 'http://localhost:3001',
    databaseUrl: 'postgres://localhost:5432/dev',
    enableAnalytics: false,
    logLevel: 'debug',
  },
};

const environment = process.env.NODE_ENV || 'development';
module.exports = config[environment];

3. 安全性

环境变量安全：

• 不要在代码中硬编码敏感信息
• 使用环境变量存储密钥
• 定期轮换密钥
• 限制环境变量访问权限

生产环境保护：

• 限制生产环境访问
• 使用强密码和密钥
• 启用双因素认证
• 定期审计访问日志

4. 部署策略

渐进式部署：

1. 先部署到预览环境
2. 进行充分测试
3. 部署到生产环境
4. 监控生产环境
5. 如有问题，快速回滚

回滚策略：

• 保留所有历史部署
• 快速回滚到稳定版本
• 记录回滚原因
• 分析问题根源

故障排除

1. 环境变量问题

问题：环境变量未生效

解决方案：

1. 检查环境变量是否正确配置
2. 确认环境变量名称拼写正确
3. 重新部署项目
4. 检查环境变量适用的环境

2. 部署失败

问题：特定环境部署失败

解决方案：

1. 查看部署日志
2. 检查环境变量配置
3. 验证依赖安装
4. 检查构建命令

3. 数据库连接问题

问题：无法连接到数据库

解决方案：

1. 验证数据库 URL 配置
2. 检查数据库访问权限
3. 确认数据库服务运行状态
4. 测试数据库连接

总结

在 Vercel 上实现多环境部署的关键点：

1. 环境隔离：每个环境使用独立的资源和配置
2. 环境变量：正确配置和管理环境变量
3. 分支策略：选择合适的 Git 分支模型
4. 自动化：利用 CI/CD 自动化部署流程
5. 监控：实施全面的监控和日志记录
6. 安全性：保护生产环境和敏感信息
7. 测试：在每个环境中进行充分测试

通过遵循这些最佳实践，可以在 Vercel 上建立可靠、高效的多环境部署流程，提高代码质量和部署效率。