workers-ci-cd

Cloudflare Workers CI/CD

状态：✅ 已可用于生产环境 | 上次验证时间：2025-01-27 GitHub Actions：v4 | GitLab CI：最新版本 | Wrangler：4.50.0

目录

• 什么是 Workers CI/CD？
• 2025 年新增内容
• 快速入门（10 分钟）
• 关键规则
• 核心概念
• 5 大使用场景
• 最佳实践
• 预防的 7 大错误
• 何时加载参考资料

---

什么是 Workers CI/CD？

使用 GitHub Actions 或 GitLab CI 自动测试和部署 Cloudflare Workers。支持在每次提交时运行测试，自动部署到预览／暂存／生产环境，安全管理机密信息，并实施部署门禁以确保安全发布。

主要功能：自动化测试、多环境部署、每个 PR 的预览 URL、机密信息管理、部署验证、自动回滚。

---

2025 年新增内容

GitHub Actions 更新（2025 年 1 月）：

• 新增：cloudflare/wrangler-action@v4（改进缓存，加快部署速度）
• 改进：通过 vars 和 secrets 参数支持机密信息
• 新增：内置预览环境清理功能
• 重大变更：apiToken 重命名为 api-token（kebab-case）

从 v3 迁移：

# ❌ OLD (v3)
- uses: cloudflare/wrangler-action@3
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

# ✅ NEW (v4)
- uses: cloudflare/wrangler-action@v4
  with:
    api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Wrangler 4.50.0（2025 年 1 月）：

• 新增：用于部署验证的 --dry-run 标志
• 改进：通过并行上传加快部署速度
• 新增：用于保留环境变量的 --keep-vars

---

快速入门（10 分钟）

GitHub Actions 设置

1. 创建 Cloudflare API Token

前往：https://dash.cloudflare.com/profile/api-tokens

创建具有以下权限的令牌：

• Account.Cloudflare Workers Scripts - 编辑
• Account.Cloudflare Pages - 编辑（如果使用 Pages）

2. 将机密信息添加到 GitHub

仓库 → Settings → Secrets → Actions → New repository secret：

• 名称：CLOUDFLARE_API_TOKEN
• 值：[粘贴令牌]

3. 创建 .github/workflows/deploy.yml

name: Deploy

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy to Cloudflare Workers

    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install

      - run: bun test

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy

4. 推送并验证

git add .github/workflows/deploy.yml
git commit -m "Add CI/CD pipeline"
git push

在 GitHub 的 Actions 选项卡中查看部署进度。

---

关键规则

1. 切勿将机密信息提交到 Git

✅ 正确：

# Use GitHub Secrets
api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

❌ 错误：

# ❌ NEVER hardcode tokens
api-token: "abc123def456..."

原因：令牌泄露后，任何人都可以向你的账户部署。

2. 部署前始终运行测试

✅ 正确：

- run: bun test  # ✅ Tests run first

- name: Deploy
  uses: cloudflare/wrangler-action@v4
  with:
    api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

❌ 错误：

# ❌ Skipping tests
- name: Deploy
  uses: cloudflare/wrangler-action@v4
  # No tests!

原因：有问题的代码不应进入生产环境。

3. 使用不同的环境

✅ 正确：

# Production (main branch)
- name: Deploy to Production
  if: github.ref == 'refs/heads/main'
  run: bunx wrangler deploy --env production

# Staging (other branches)
- name: Deploy to Staging
  if: github.ref != 'refs/heads/main'
  run: bunx wrangler deploy --env staging

❌ 错误：

# ❌ Always deploying to production
- run: bunx wrangler deploy

原因：先在暂存环境中测试变更，再部署到生产环境。

4. 验证部署是否成功

✅ 正确：

- name: Deploy
  id: deploy
  uses: cloudflare/wrangler-action@v4

- name: Verify Deployment
  run: |
    curl -f https://your-worker.workers.dev/health || exit 1

❌ 错误：

# ❌ No verification
- name: Deploy
  uses: cloudflare/wrangler-action@v4
  # Assuming it worked...

原因：部署可能会静默失败（DNS 问题、绑定错误）。

5. 为生产环境设置部署门禁

✅ 正确：

deploy-production:
  environment:
    name: production
    url: https://your-worker.workers.dev
  # Requires manual approval

❌ 错误：

# ❌ Auto-deploy to production without review
deploy-production:
  runs-on: ubuntu-latest

原因：人工审核能发现自动化流程遗漏的问题。

---

核心概念

多环境策略

推荐设置：

• 生产环境：main 分支 → 生产环境
• 暂存环境：拉取请求 → 暂存环境
• 预览环境：每个 PR → 唯一的预览 URL

wrangler.jsonc：

{
  "name": "my-worker",
  "main": "src/index.ts",

  "env": {
    "production": {
      "name": "my-worker-production",
      "vars": {
        "ENVIRONMENT": "production"
      }
    },
    "staging": {
      "name": "my-worker-staging",
      "vars": {
        "ENVIRONMENT": "staging"
      }
    }
  }
}

机密信息管理

配置类型：

1. 公开变量（wrangler.jsonc）- 非敏感配置
2. 机密信息（wrangler secret）- API 密钥、令牌
3. CI 变量（GitHub Secrets）- 部署凭据

设置机密信息：

# Local development
wrangler secret put DATABASE_URL

# CI/CD (via GitHub Actions)
bunx wrangler secret put DATABASE_URL --env production <<< "${{ secrets.DATABASE_URL }}"

预览部署

自动将每个 PR 部署到唯一的 URL，以便测试：

- name: Deploy Preview
  uses: cloudflare/wrangler-action@v4
  with:
    api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    command: deploy --env preview-${{ github.event.number }}

每个 PR 都会获得类似这样的 URL：my-worker-preview-42.workers.dev

---

5 大使用场景

1. 推送到 Main 时部署

name: Deploy Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test
      - run: bun run build

      - name: Deploy to Production
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env production

2. 为 PR 创建预览部署

name: Preview

on:
  pull_request:
    branches: [main]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test

      - name: Deploy Preview
        id: deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env preview-${{ github.event.number }}

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '✅ Preview deployed to: https://my-worker-preview-${{ github.event.number }}.workers.dev'
            })

3. 在每次提交时运行测试

name: Test

on:
  push:
    branches: ['**']
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test --coverage

      - name: Upload Coverage
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info

4. 通过审批门禁部署

name: Deploy Production (Manual Approval)

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://my-worker.workers.dev
    # Requires manual approval in GitHub Settings

    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env production

5. 分阶段发布（金丝雀发布）

name: Canary Deployment

on:
  workflow_dispatch:
    inputs:
      percentage:
        description: 'Traffic percentage to new version'
        required: true
        default: '10'

jobs:
  canary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install

      # Deploy to canary environment
      - name: Deploy Canary
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env canary

      # Configure traffic split via Cloudflare API
      # (See references/deployment-strategies.md for full example)

---

最佳实践

✅ 应该做

1. 使用语义化提交消息：

   feat: add user authentication
   fix: resolve rate limiting issue
   chore: update dependencies
   

2. 运行 lint 和类型检查：

   - run: bun run lint
   - run: bun run type-check
   - run: bun test
   

3. 缓存依赖项：

   - uses: oven-sh/setup-bun@v2
     with:
       bun-version: latest
   # Bun automatically caches dependencies
   

4. 将不同分支部署到不同环境：

   - name: Deploy
     run: |
       if [ "${{ github.ref }}" == "refs/heads/main" ]; then
         bunx wrangler deploy --env production
       else
         bunx wrangler deploy --env staging
       fi
   

5. 监控部署：

   - name: Notify Slack
     if: failure()
     uses: slackapi/slack-github-action@v1
     with:
       payload: |
         {"text": "Deployment failed: ${{ github.sha }}"}
   

❌ 不应该做

1. 不要跳过测试
2. 不要未经验证就部署
3. 不要将密钥硬编码
4. 不要从功能分支部署到生产环境
5. 不要忽略部署失败

---

可避免的 7 大错误

1. ❌ Error: A valid Cloudflare API token is required

原因：缺少或无效的 CLOUDFLARE_API_TOKEN 密钥。

解决方法：

1. 创建 API 令牌：https://dash.cloudflare.com/profile/api-tokens
2. 添加到 GitHub Secrets：Settings → Secrets → Actions
3. 在工作流中使用：api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}

---

2. ❌ Error: Not enough permissions to deploy

原因：API 令牌缺少所需权限。

解决方法：重新创建令牌，并授予以下权限：

• Account.Cloudflare Workers Scripts - Edit
• Account settings - Read

---

3. ❌ Error: wrangler.toml not found

原因：缺少 wrangler 配置。

解决方法：确保仓库根目录中存在 wrangler.jsonc。

---

4. ❌ 部署成功，但 worker 无法运行

原因：缺少密钥或环境变量。

解决方法：在 CI 中设置密钥：

- name: Set Secrets
  run: |
    echo "${{ secrets.DATABASE_URL }}" | bunx wrangler secret put DATABASE_URL --env production

---

5. ❌ 本地测试通过，但 CI 中失败

原因：环境差异（Node 版本、缺少依赖项）。

解决方法：

- uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest # Lock version

- run: bun install --frozen-lockfile # Use exact versions

---

6. ❌ 预览部署冲突

原因：多个 PR 部署到同一个预览环境。

解决方法：在环境名称中使用 PR 编号：

command: deploy --env preview-${{ github.event.number }}

---

7. ❌ 密钥暴露在日志中

原因：在工作流中回显密钥。

解决方法：

# ❌ WRONG
- run: echo "Token: ${{ secrets.API_TOKEN }}"

# ✅ CORRECT
- run: echo "Deploying..." # No secrets in output

---

何时加载参考文件

需要详细、专业的内容时，请加载参考文件：

在以下情况下加载 references/github-actions.md：

• 从头开始设置 GitHub Actions
• 配置矩阵构建（多个 Node 版本）
• 使用 GitHub 环境和部署保护
• 实施部署门禁和审批

在以下情况下加载 references/gitlab-ci.md：

• 设置 GitLab CI 流水线
• 配置 GitLab 环境
• 使用 GitLab 密钥变量
• 实施 Review Apps

在以下情况下加载 references/deployment-strategies.md：

• 实施蓝绿部署
• 设置金丝雀发布
• 配置流量拆分
• 规划回滚流程

在以下情况下加载 references/secrets-management.md：

• 管理不同环境中的密钥
• 轮换 API 令牌
• 使用外部密钥提供方（Vault、1Password）
• 实施最小权限访问

在以下情况下加载 templates/github-actions-full.yml：

• 完整的、可用于生产环境的 GitHub Actions 工作流
• 多环境部署示例
• 配置了所有部署门禁

在以下情况下加载 templates/gitlab-ci-full.yml：

• 完整的 GitLab CI 流水线
• 多阶段部署
• Review App 配置

在以下情况下加载 templates/preview-deployment.yml：

• PR 预览部署设置
• PR 关闭时自动清理
• 附带预览 URL 的评论

在以下情况下加载 templates/rollback-workflow.yml：

• 手动回滚工作流
• 部署历史跟踪
• 健康检查失败时自动回滚

在以下情况下加载 scripts/verify-deployment.sh：

• 自动验证部署
• 健康检查实现
• 部署后的冒烟测试

---

相关 Cloudflare 插件

如需进行部署测试，请加载：

• cloudflare-workers-testing - 在部署前测试 Workers
• cloudflare-manager - 通过 Cloudflare API 管理部署

此技能专注于 CI/CD 自动化，适用于所有 Workers 部署，无论使用何种绑定。

---

有疑问？ 加载 references/secrets-management.md，或使用 /workers-deploy 命令获取部署指导。