构建和发布

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 构建, 发布, 编译, 打包, build, deploy
---

# 构建和发布流程规范

本文档定义了企业管理数字化中台的构建和发布流程，确保每次发布都经过严格的质量检查。

---

## &#127919; 核心原则

1. **质量第一**: 任何代码都必须通过所有检查才能发布
2. **自动化优先**: 尽可能自动化，减少人为错误
3. **可追溯**: 每次发布都有完整的记录
4. **可回滚**: 快速回滚机制，降低风险

---

## &#128230; 开发环境构建

### 构建流程

```bash
# 1. 代码检查（自动）
pnpm lint

# 2. 类型检查（自动）
pnpm type-check

# 3. 运行测试（自动）
pnpm test:unit

# 4. 启动开发服务器（带热更新）
pnpm dev
```

**特点**:
- ✅ 启用热更新（HMR）
- ✅ 详细的错误信息
- ✅ Source Map 调试
- ✅ 快速反馈

**注意事项**:
- 开发环境不启用代码压缩
- 包含调试信息
- 性能可能不如生产环境

---

## &#127981; 生产环境构建

### 构建流程

```bash
# 步骤 1: 清理缓存
rm -rf .next node_modules/.cache

# 步骤 2: 安装依赖（使用锁定文件）
pnpm install --frozen-lockfile

# 步骤 3: 代码检查
pnpm lint

# 步骤 4: 类型检查（严格模式）
pnpm type-check

# 步骤 5: 运行所有测试
pnpm test

# 步骤 6: 生成测试覆盖率报告
pnpm test:coverage

# 步骤 7: 检查覆盖率是否达标
pnpm test:coverage:check

# 步骤 8: 构建生产版本
pnpm build

# 步骤 9: 验证构建产物
pnpm build:verify

# 步骤 10: 运行 E2E 测试（可选）
pnpm test:e2e
```

### 构建脚本

**创建脚本**: `scripts/build-production.sh`

```bash
#!/bin/bash
set -e

echo "&#127981; 开始生产环境构建..."

# 颜色输出
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# 步骤 1: 清理缓存
echo -e "${YELLOW}&#129529; 清理构建缓存...${NC}"
rm -rf .next node_modules/.cache

# 步骤 2: 代码检查
echo -e "${YELLOW}&#128269; 运行 ESLint 检查...${NC}"
if ! pnpm lint; then
  echo -e "${RED}❌ ESLint 检查失败${NC}"
  exit 1
fi
echo -e "${GREEN}✅ ESLint 检查通过${NC}"

# 步骤 3: 类型检查
echo -e "${YELLOW}&#128269; 运行 TypeScript 类型检查...${NC}"
if ! pnpm type-check; then
  echo -e "${RED}❌ 类型检查失败${NC}"
  exit 1
fi
echo -e "${GREEN}✅ 类型检查通过${NC}"

# 步骤 4: 运行测试
echo -e "${YELLOW}&#129514; 运行单元测试...${NC}"
if ! pnpm test:unit --bail; then
  echo -e "${RED}❌ 单元测试失败${NC}"
  exit 1
fi
echo -e "${GREEN}✅ 单元测试通过${NC}"

# 步骤 5: 生成覆盖率报告
echo -e "${YELLOW}&#128202; 生成测试覆盖率报告...${NC}"
pnpm test:coverage

# 步骤 6: 检查覆盖率
echo -e "${YELLOW}&#128200; 检查测试覆盖率...${NC}"
if ! pnpm test:coverage:check; then
  echo -e "${RED}❌ 测试覆盖率不达标${NC}"
  exit 1
fi
echo -e "${GREEN}✅ 测试覆盖率达标${NC}"

# 步骤 7: 构建项目
echo -e "${YELLOW}&#127959;️ 构建生产版本...${NC}"
if ! pnpm build; then
  echo -e "${RED}❌ 构建失败${NC}"
  exit 1
fi
echo -e "${GREEN}✅ 构建成功${NC}"

# 步骤 8: 验证构建产物
echo -e "${YELLOW}✅ 验证构建产物...${NC}"
if ! pnpm build:verify; then
  echo -e "${RED}❌ 构建产物验证失败${NC}"
  exit 1
fi
echo -e "${GREEN}✅ 构建产物验证通过${NC}"

echo -e "${GREEN}&#127881; 生产环境构建完成！${NC}"
echo ""
echo "&#128230; 构建产物位置: .next/"
echo "&#128640; 启动命令: pnpm start"
```

### 构建验证脚本

**创建脚本**: `scripts/build-verify.sh`

```bash
#!/bin/bash
set -e

echo "&#128269; 验证构建产物..."

# 检查构建目录
if [ ! -d ".next" ]; then
  echo "❌ 构建目录 .next 不存在"
  exit 1
fi

# 检查关键文件
if [ ! -f ".next/BUILD_ID" ]; then
  echo "❌ BUILD_ID 不存在"
  exit 1
fi

# 检查静态资源
if [ ! -d ".next/static" ]; then
  echo "❌ 静态资源目录不存在"
  exit 1
fi

# 检查服务器端代码
if [ ! -d ".next/server" ]; then
  echo "❌ 服务器端代码不存在"
  exit 1
fi

# 检查构建大小
BUILD_SIZE=$(du -sh .next | cut -f1)
echo "&#128230; 构建大小: $BUILD_SIZE"

echo "✅ 构建产物验证通过"
```

---

## &#128640; 发布流程

### 发布前检查清单

```yaml
代码质量:
  - [ ] 所有测试通过
  - [ ] 测试覆盖率达标 (≥ 70%)
  - [ ] ESLint 检查通过
  - [ ] TypeScript 类型检查通过
  - [ ] 代码已格式化
  - [ ] 无 console.log 调试代码

功能验证:
  - [ ] 在开发环境验证通过
  - [ ] 在测试环境验证通过
  - [ ] 在预发布环境验证通过
  - [ ] 关键用户流程测试通过
  - [ ] E2E 测试通过

文档更新:
  - [ ] CHANGELOG 已更新
  - [ ] API 文档已更新（如需要）
  - [ ] 用户文档已更新（如需要）

安全检查:
  - [ ] 无安全漏洞
  - [ ] 敏感信息已移除
  - [ ] 环境变量已配置
  - [ ] 权限配置正确

备份准备:
  - [ ] 数据库已备份
  - [ ] 当前版本已标记
  - [ ] 回滚方案已准备
  - [ ] 监控已配置
```

### 发布流程

#### 1. 准备阶段

```bash
# 切换到 develop 分支
git checkout develop
git pull origin develop

# 创建发布分支
git checkout -b release/v2.1.0

# 更新版本号
# 修改 package.json 中的 version
pnpm version patch  # 或 minor / major

# 运行完整构建测试
bash scripts/build-production.sh

# 运行 E2E 测试
pnpm test:e2e
```

#### 2. 测试阶段

```bash
# 部署到测试环境
pnpm deploy:test

# 在测试环境验证
# - 手动测试关键功能
# - 查看错误日志
# - 性能测试

# 部署到预发布环境
pnpm deploy:staging

# 在预发布环境验证
# - 完整功能测试
# - 性能测试
# - 安全测试
```

#### 3. 发布阶段

```bash
# 合并到 main 分支
git checkout main
git merge release/v2.1.0

# 打标签
git tag -a v2.1.0 -m "Release v2.1.0"

# 推送到远程
git push origin main
git push origin v2.1.0

# 部署到生产环境
pnpm deploy:production

# 验证生产环境
curl -I https://yourdomain.com
curl https://yourdomain.com/api/health

# 回到 develop 分支，合并发布内容
git checkout develop
git merge main
git push origin develop
```

### 发布脚本

**创建脚本**: `scripts/release.sh`

```bash
#!/bin/bash
set -e

# 颜色输出
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
NC='\033[0m'

# 获取版本号
VERSION=$1

if [ -z "$VERSION" ]; then
  echo -e "${RED}❌ 请提供版本号${NC}"
  echo "用法: ./scripts/release.sh <version>"
  echo "示例: ./scripts/release.sh v2.1.0"
  exit 1
fi

echo -e "${YELLOW}&#128640; 开始发布 v${VERSION}...${NC}"

# 1. 检查当前分支
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" != "develop" ]; then
  echo -e "${RED}❌ 请在 develop 分支上执行发布${NC}"
  exit 1
fi

# 2. 拉取最新代码
echo -e "${YELLOW}&#128229; 拉取最新代码...${NC}"
git pull origin develop

# 3. 创建发布分支
echo -e "${YELLOW}&#127807; 创建发布分支 release/${VERSION}...${NC}"
git checkout -b release/${VERSION}

# 4. 更新版本号
echo -e "${YELLOW}&#128221; 更新版本号...${NC}"
echo "${VERSION#v}" > .version
npm version ${VERSION#v} --no-git-tag-version

# 5. 运行构建测试
echo -e "${YELLOW}&#127959;️ 运行构建测试...${NC}"
bash scripts/build-production.sh

# 6. 运行 E2E 测试
echo -e "${YELLOW}&#129514; 运行 E2E 测试...${NC}"
pnpm test:e2e

# 7. 提交变更
echo -e "${YELLOW}&#128190; 提交变更...${NC}"
git add .
git commit -m "chore: release ${VERSION}"

# 8. 合并到 main
echo -e "${YELLOW}&#128256; 合并到 main 分支...${NC}"
git checkout main
git merge release/${VERSION} --no-ff -m "chore: merge release ${VERSION}"

# 9. 打标签
echo -e "${YELLOW}&#127991;️ 创建标签 ${VERSION}...${NC}"
git tag -a ${VERSION} -m "Release ${VERSION}"

# 10. 推送到远程
echo -e "${YELLOW}&#128228; 推送到远程仓库...${NC}"
git push origin main
git push origin ${VERSION}

# 11. 合并回 develop
echo -e "${YELLOW}&#128256; 合并回 develop 分支...${NC}"
git checkout develop
git merge main --no-ff -m "chore: merge ${VERSION} back to develop"
git push origin develop

# 12. 清理发布分支
echo -e "${YELLOW}&#129529; 清理发布分支...${NC}"
git branch -d release/${VERSION}

echo -e "${GREEN}✅ 发布 ${VERSION} 完成！${NC}"
echo ""
echo "&#128221; 接下来请执行："
echo "   1. 部署到生产环境"
echo "   2. 验证生产环境"
echo "   3. 更新 CHANGELOG"
```

---

## &#128260; 回滚流程

### 快速回滚

```bash
# 方法 1: Git 回滚（代码层面）
git revert HEAD
git push origin main

# 方法 2: Git 回滚到指定版本
git revert <commit-hash>
git push origin main

# 方法 3: 切换到上一个标签
git checkout v2.0.0
pnpm build
pnpm deploy:production
```

### Docker 回滚

```bash
# 回滚到上一个镜像
kubectl rollout undo deployment payroll

# 回滚到指定版本
kubectl rollout undo deployment payroll --to-revision=3

# 查看回滚历史
kubectl rollout history deployment payroll
```

### 数据库回滚

```bash
# 回滚最后一个迁移
pnpm db:migrate:rollback

# 回滚到指定版本
pnpm db:migrate:rollback --to=<migration-name>

# 恢复数据库备份
psql -U postgres -d payroll < backup/payroll_20240101.sql
```

### 回滚脚本

**创建脚本**: `scripts/rollback.sh`

```bash
#!/bin/bash
set -e

# 颜色输出
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
NC='\033[0m'

# 获取版本号
VERSION=$1

if [ -z "$VERSION" ]; then
  echo -e "${RED}❌ 请提供要回滚的版本号${NC}"
  echo "用法: ./scripts/rollback.sh <version>"
  echo "示例: ./scripts/rollback.sh v2.0.0"
  exit 1
fi

echo -e "${YELLOW}&#128260; 开始回滚到 ${VERSION}...${NC}"

# 1. 检查当前分支
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" != "main" ]; then
  echo -e "${RED}❌ 请在 main 分支上执行回滚${NC}"
  exit 1
fi

# 2. 备份当前状态
echo -e "${YELLOW}&#128190; 备份当前状态...${NC}"
git branch backup-$(date +%Y%m%d-%H%M%S)

# 3. 回滚到指定版本
echo -e "${YELLOW}&#128281; 回滚代码...${NC}"
git checkout $VERSION

# 4. 重新构建
echo -e "${YELLOW}&#127959;️ 重新构建...${NC}"
pnpm build

# 5. 部署
echo -e "${YELLOW}&#128640; 部署到生产环境...${NC}"
pnpm deploy:production

echo -e "${GREEN}✅ 回滚到 ${VERSION} 完成！${NC}"
echo ""
echo "&#128221; 接下来请执行："
echo "   1. 验证生产环境"
echo "   2. 查看日志确认问题已解决"
echo "   3. 如果问题仍存在，继续调查原因"
```

---

## &#128202; 发布检查清单

### 代码质量

- [ ] 代码已通过 ESLint 检查
- [ ] 代码已通过 TypeScript 类型检查
- [ ] 单元测试覆盖率 ≥ 70%
- [ ] 集成测试通过
- [ ] E2E 测试通过
- [ ] 无 console.log 调试代码
- [ ] 无 TODO 或 FIXME（除非有必要）

### 功能验证

- [ ] 开发环境验证通过
- [ ] 测试环境验证通过
- [ ] 预发布环境验证通过
- [ ] 关键用户流程测试通过
- [ ] 性能测试通过
- [ ] 安全测试通过

### 文档更新

- [ ] CHANGELOG 已更新
- [ ] API 文档已更新（如需要）
- [ ] 用户文档已更新（如需要）
- [ ] 部署文档已更新（如需要）

### 安全检查

- [ ] 无已知安全漏洞
- [ ] 依赖已更新到最新版本
- [ ] 敏感信息已移除
- [ ] 环境变量已正确配置
- [ ] 权限配置正确

### 备份准备

- [ ] 数据库已备份
- [ ] 当前版本已标记
- [ ] 回滚方案已准备
- [ ] 监控已配置
- [ ] 告警已设置

---

## &#127919; 发布最佳实践

### 1. 小步快跑
- 每次发布包含少量改动
- 避免大规模重构
- 降低回滚风险

### 2. 频繁发布
- 建议每周发布 1-2 次
- 避免长时间不发布
- 减少发布压力

### 3. 灰度发布
- 先发布给 5% 用户
- 观察日志和反馈
- 逐步扩大发布范围

### 4. 监控告警
- 实时监控关键指标
- 及时发现问题
- 快速响应

### 5. 回滚准备
- 每次发布前准备回滚方案
- 回滚脚本已测试
- 回滚时间 < 5 分钟

---

## &#128218; 参考资源

- [Next.js 部署文档](https://nextjs.org/docs/deployment)
- [CI/CD 最佳实践](https://docs.github.com/en/actions)
- [Git 分支管理](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)
- [发布管理最佳实践](https://martinfowler.com/bliki/ReleaseTrain.html)

---

## &#127881; 总结

通过这套构建和发布流程，你可以：

1. **保证代码质量**: 自动化测试 + 代码检查
2. **降低发布风险**: 多环境验证 + 灰度发布
3. **快速回滚**: 完整的回滚机制
4. **可追溯**: 完整的发布记录

记住：**发布不是终点，而是新的开始**。