⚡

CloudflareWorkers持续集成与持续部署CI/CD指南 workers-ci-cd

这是一个关于使用GitHub Actions和GitLab CI实现Cloudflare Workers自动化测试、部署和管理的完整技能指南。提供快速入门、关键规则、核心概念、最佳实践、错误预防等内容，适用于自动化测试、多环境部署、预览环境、秘密管理、部署验证等场景。关键词：Cloudflare Workers, CI/CD, 自动化测试, GitHub Actions, GitLab CI, 部署管道, 秘密管理, DevOps。

DevOps 0 次安装 0 次浏览 更新于 3/8/2026

name: workers-ci-cd description: 使用GitHub Actions和GitLab CI的Cloudflare Workers完整CI/CD指南。用于自动化测试、部署管道、预览环境、秘密管理，或遇到部署失败、工作流错误、环境配置问题。 keywords:

  • cloudflare-workers
  • workers-ci-cd
  • github-actions
  • gitlab-ci
  • continuous-integration
  • continuous-deployment
  • automated-testing
  • deployment-pipeline
  • preview-deployments
  • staging-deployment
  • production-deployment
  • secrets-management
  • wrangler-deploy
  • environment-variables
  • github-secrets
  • deployment-verification
  • rollback-strategy
  • blue-green-deployment
  • canary-deployment
  • deployment-gates
  • ci-cd-best-practices
  • workflow-automation
  • pull-request-previews
  • branch-deployments license: MIT metadata: version: “1.0.0” last_verified: “2025-01-27” production_tested: true token_savings: “~75%” errors_prevented: 7 templates_included: 4 references_included: 4 scripts_included: 1 github_actions_version: “v4” wrangler_version: “4.50.0”

Cloudflare Workers CI/CD

状态: ✅ 生产就绪 | 最后验证: 2025-01-27 GitHub Actions: v4 | GitLab CI: 最新 | Wrangler: 4.50.0

目录

什么是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（短横线格式）

从v3迁移:

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

# ✅ 新版本 (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令牌

访问: https://dash.cloudflare.com/profile/api-tokens

创建具有权限的令牌:

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

2. 添加秘密到GitHub

仓库 → 设置 → 秘密 → Actions → 新建仓库秘密:

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

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

name: 部署

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: 部署到Cloudflare Workers

    steps:
      - uses: actions/checkout@v4

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

      - run: bun install

      - run: bun test

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

4. 推送并验证

git add .github/workflows/deploy.yml
git commit -m "添加CI/CD管道"
git push

在GitHub的Actions标签页检查部署进度。

关键规则

1. 切勿将秘密提交到Git

✅ 正确:

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

❌ 错误:

# ❌ 切勿硬编码令牌
api-token: "abc123def456..."

原因: 暴露的令牌允许任何人部署到您的账户。

2. 部署前始终运行测试

✅ 正确:

- run: bun test  # ✅ 先运行测试

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

❌ 错误:

# ❌ 跳过测试
- name: 部署
  uses: cloudflare/wrangler-action@v4
  # 没有测试！

原因: 损坏的代码不应进入生产环境。

3. 使用不同环境

✅ 正确:

# 生产环境（main分支）
- name: 部署到生产
  if: github.ref == 'refs/heads/main'
  run: bunx wrangler deploy --env production

# 暂存环境（其他分支）
- name: 部署到暂存
  if: github.ref != 'refs/heads/main'
  run: bunx wrangler deploy --env staging

❌ 错误:

# ❌ 始终部署到生产环境
- run: bunx wrangler deploy

原因: 在生产前测试暂存环境中的更改。

4. 验证部署成功

✅ 正确:

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

- name: 验证部署
  run: |
    curl -f https://your-worker.workers.dev/health || exit 1

❌ 错误:

# ❌ 没有验证
- name: 部署
  uses: cloudflare/wrangler-action@v4
  # 假设它工作了...

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

5. 为生产环境使用部署门控

✅ 正确:

deploy-production:
  environment:
    name: production
    url: https://your-worker.workers.dev
  # 需要手动批准

❌ 错误:

# ❌ 没有审核自动部署到生产环境
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) - 部署凭据

设置秘密:

# 本地开发
wrangler secret put DATABASE_URL

# CI/CD（通过GitHub Actions）
bunx wrangler secret put DATABASE_URL --env production <<< "${{ secrets.DATABASE_URL }}"

预览部署

自动将每个PR部署到唯一URL进行测试:

- name: 部署预览
  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: 部署生产

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: 部署到生产
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env production

2. PR的预览部署

name: 预览

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: 部署预览
        id: deploy
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env preview-${{ github.event.number }}

      - name: 评论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: '✅ 预览部署到: https://my-worker-preview-${{ github.event.number }}.workers.dev'
            })

3. 每次提交运行测试

name: 测试

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: 上传覆盖率
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info

4. 使用批准门控部署

name: 部署生产（手动批准）

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://my-worker.workers.dev
    # 需要在GitHub设置中手动批准

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

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

5. 分阶段推出（金丝雀）

name: 金丝雀部署

on:
  workflow_dispatch:
    inputs:
      percentage:
        description: '新版本流量百分比'
        required: true
        default: '10'

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

      # 部署到金丝雀环境
      - name: 部署金丝雀
        uses: cloudflare/wrangler-action@v4
        with:
          api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          command: deploy --env canary

      # 通过Cloudflare API配置流量分割
      # （完整示例见参考文献/deployment-strategies.md）

最佳实践

✅ 做

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

    功能: 添加用户认证
修复: 解决速率限制问题
杂务: 更新依赖项

  2. 运行代码检查和类型检查:

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

  3. 缓存依赖项:

    - uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest
# Bun自动缓存依赖项

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

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

  5. 监控部署:

    - name: 通知Slack
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {"text": "部署失败: ${{ github.sha }}"}

❌ 不做

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

前7大预防错误

1. ❌ 错误: 需要有效的Cloudflare API令牌

原因: 缺少或无效的CLOUDFLARE_API_TOKEN秘密。

修复:

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

2. ❌ 错误: 权限不足无法部署

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

修复: 重新创建令牌，包含:

  • Account.Cloudflare Workers Scripts - 编辑
  • Account settings - 读取

3. ❌ 错误: 未找到wrangler.toml

原因: 缺少wrangler配置。

修复: 确保wrangler.jsonc存在于仓库根目录。

4. ❌ 部署成功但worker不工作

原因: 缺少秘密或环境变量。

修复: 在CI中设置秘密:

- name: 设置秘密
  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 # 锁定版本

- run: bun install --frozen-lockfile # 使用确切版本

6. ❌ 预览部署冲突

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

修复: 在环境名称中使用PR编号:

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

7. ❌ 日志中暴露秘密

原因: 在工作流中回显秘密。

修复:

# ❌ 错误
- run: echo "令牌: ${{ secrets.API_TOKEN }}"

# ✅ 正确
- run: echo "部署中..." # 输出中没有秘密

何时加载参考文献

加载参考文献文件以获取详细、专门内容:

加载references/github-actions.md当:

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

加载references/gitlab-ci.md当:

  • 设置GitLab CI管道
  • 配置GitLab环境
  • 使用GitLab秘密变量
  • 实施审核应用

加载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管道
  • 多阶段部署
  • 审核应用配置

加载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命令获取引导部署。