CI/CD 流程

GitHub Actions 自动化流程和 Dependabot 依赖管理

概述

项目使用 GitHub Actions 实现持续集成和持续部署（CI/CD），包括代码质量检查、自动化测试、Docker 镜像构建和依赖更新管理。

CI/CD 工作流

1. PR 验证流程 (validate-prs.yml)

当创建或更新 Pull Request 到 main 分支时自动触发，确保代码质量。

触发条件:

on:
  pull_request:
    branches: [main]

执行任务:

Lint 检查

使用 Biome 进行代码格式和质量检查
检查代码风格、潜在错误和最佳实践
失败时会阻止 PR 合并

# 本地运行相同检查
pnpm lint:fix

E2E 测试

使用 Playwright 运行端到端测试
测试超时时间：60 分钟
测试失败时会上传测试报告（保留 30 天）

# 本地运行 E2E 测试
cd apps/mono-web
pnpm e2e

配置文件: .github/workflows/validate-prs.yml

2. Docker 镜像构建 (docker-image.yml)

自动构建和推送 Docker 镜像到 GitHub Container Registry (ghcr.io)。

触发条件:

推送到 main 分支
创建版本标签（如 v1.0.0）
手动触发（workflow_dispatch）

构建流程:

1. 加载构建环境

从 .env.build 文件加载环境变量，包括：

NEXT_PUBLIC_SITE_URL: 网站 URL
NEXT_PUBLIC_BUCKET_NAME: S3 存储桶名称
NEXT_PUBLIC_S3_ENDPOINT: S3 端点地址

如果文件不存在，使用默认值。

2. 计算构建元数据

BUILD_VERSION: v1.0.0 或 main-abc1234
BUILD_TIME: 2026-03-09T10:30:00Z
GIT_COMMIT: abc1234

3. 构建和推送镜像

使用 Docker Buildx 进行多平台构建
推送到 ghcr.io/your-org/your-repo
自动生成多个标签：
- latest (仅 main 分支)
- main (分支名)
- v1.0.0 (版本标签)
- sha-abc1234 (commit SHA)

4. 缓存优化

使用 GitHub Actions 缓存加速构建：

cache-from: type=gha
cache-to: type=gha,mode=max

配置文件: .github/workflows/docker-image.yml

本地测试构建:

# 构建镜像
docker build -t mono-web .

# 运行容器
docker run -p 3000:3000 mono-web

Dependabot 依赖管理

什么是 Dependabot？

Dependabot 是 GitHub 提供的自动化依赖更新工具，它会：

每天检查项目依赖是否有新版本
自动创建 PR 更新依赖
将依赖分组，避免 PR 过多

配置说明

配置文件: .github/dependabot.yml

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    open-pull-requests-limit: 2  # 最多同时打开 2 个 PR
    schedule:
      interval: "daily"           # 每天检查一次
    ignore:
      - dependency-name: "cropperjs"
        versions: [">1.6.2"]      # 忽略特定版本
    groups:
      production-dependencies:    # 生产依赖分组
        dependency-type: "production"
      development-dependencies:   # 开发依赖分组
        dependency-type: "development"

依赖分组策略

Dependabot 将依赖更新分为两组：

1. 生产依赖 (production-dependencies)

包含 dependencies 中的所有包
影响生产环境运行
PR 标题示例：chore(deps): bump the production-dependencies group with 42 updates

2. 开发依赖 (development-dependencies)

包含 devDependencies 中的所有包
仅影响开发和构建过程
PR 标题示例：chore(deps-dev): bump the development-dependencies group with 15 updates

为什么要分组？

不分组的问题:

每个依赖更新都会创建一个 PR
可能同时有几十个 PR 需要处理
难以管理和审查

分组的好处:

将相关依赖合并到一个 PR
减少 PR 数量（从几十个减少到 2 个）
更容易审查和测试
可以一次性合并所有更新

处理 Dependabot PR

1. 审查 PR

# 查看更新的依赖列表
git fetch origin
git checkout dependabot/npm_and_yarn/production-dependencies-xxx

# 查看变更
git diff main package.json pnpm-lock.yaml

2. 本地测试

# 安装依赖
pnpm install

# 运行测试
pnpm verify:packages

# 启动开发服务器
pnpm dev

3. 合并 PR

如果 CI 检查通过且本地测试正常：

点击 "Merge pull request"
选择 "Squash and merge"（推荐）
删除分支

4. 处理冲突

如果 PR 有冲突：

# 方法 1: 让 Dependabot 重新创建 PR
# 在 PR 中评论：@dependabot rebase

# 方法 2: 手动解决冲突
git checkout dependabot/npm_and_yarn/production-dependencies-xxx
git merge main
# 解决冲突
git push

忽略特定依赖

如果某个依赖更新导致问题，可以在配置中忽略：

ignore:
  - dependency-name: "package-name"
    versions: [">1.0.0"]  # 忽略 1.0.0 以上版本

或在 PR 中评论：

@dependabot ignore this major version
@dependabot ignore this minor version
@dependabot ignore this dependency

常见问题

Q: 为什么会有 42 个依赖更新？

A: 这是正常的。npm 生态系统更新频繁，一天内可能有几十个包发布新版本。Dependabot 会将它们合并到一个 PR 中。

Q: 是否需要每次都合并？

A: 不一定。可以根据项目需求决定：

安全更新：立即合并
功能更新：定期合并（如每周一次）
主版本更新：谨慎测试后合并

Q: 如何暂停 Dependabot？

A: 在 PR 中评论：

@dependabot pause

恢复：

@dependabot unpause

最佳实践

1. 提交前检查

# 运行完整检查
pnpm lint:fix
pnpm verify:packages
pnpm build

2. 使用 Husky 钩子

项目已配置 Husky，会在提交前自动运行检查：

{
  "scripts": {
    "prepare": "husky"
  }
}

3. 监控 CI 状态

在 GitHub PR 页面查看 CI 状态
失败时查看详细日志
修复问题后重新推送

4. 定期更新依赖

每周检查并合并 Dependabot PR
关注安全更新通知
测试主版本更新

5. Docker 镜像管理

# 查看已发布的镜像
gh api /user/packages/container/mono/versions

# 拉取最新镜像
docker pull ghcr.io/your-org/mono:latest

# 清理旧镜像
# 在 GitHub Packages 页面手动删除