cloudflare-workers-ci-cd

用途

本项目是 Cloudflare Workers 的 CI/CD 自动化指南，用于通过 GitHub Actions 或 GitLab CI 对 Workers 进行自动化测试与部署。目标是让每次提交都运行测试、自动部署到预览/预发/生产环境、安全地管理密钥，并通过部署门禁实现安全发布。

2025 年更新

GitHub Actions 方面：新增 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 方面：新增 --dry-run 用于部署校验；通过并行上传加快部署；新增 --keep-vars 以保留环境变量。

快速开始（10 分钟）

创建 Cloudflare API Token，访问 https://dash.cloudflare.com/profile/api-tokens ，权限为 Account.Cloudflare Workers Scripts - Edit，若使用 Pages 还需 Account.Cloudflare Pages - Edit。
在 GitHub 仓库 Settings → Secrets → Actions 添加密钥，名称为 CLOUDFLARE_API_TOKEN。
创建 .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

提交并推送后，在 GitHub Actions 标签页查看部署进度。

关键规则

不要在 Git 中提交密钥，应使用 GitHub Secrets；部署前始终运行测试；使用不同环境（如 main 分支部署 production，其他分支部署 staging）；部署后校验成功（例如对 /health 发起 curl，失败则退出）；为生产环境设置部署门禁（手动审批）。

核心概念

多环境策略推荐：production 对应 main 分支，staging 对应 Pull Request，preview 为每个 PR 生成唯一 URL。wrangler.jsonc 中可定义 env.production 与 env.staging，各自设置 name 与 vars（如 ENVIRONMENT）。

密钥管理分为三类：公共变量（wrangler.jsonc，非敏感配置）、密钥（wrangler secret，API key 与 token）、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 生成唯一地址（如 my-worker-preview-42.workers.dev）：

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

典型用例

包括：推送到 main 时部署生产；为 PR 部署预览并在 PR 中评论预览地址；每次提交运行测试并上传覆盖率到 Codecov；带审批门禁的生产部署；通过 workflow_dispatch 输入流量百分比的灰度（金丝雀）部署。

最佳实践

建议使用语义化提交信息（feat/fix/chore 等）；运行 lint、类型检查与测试；缓存依赖（Bun 自动缓存）；按分支部署到不同环境；监控部署并在失败时通知 Slack。不建议：跳过测试、未校验就部署、硬编码密钥、从功能分支部署生产、忽略部署失败。

常见错误与排查

文档列出七大错误：缺少或无效的 CLOUDFLARE_API_TOKEN；API token 权限不足；找不到 wrangler.toml（需确保仓库根目录存在 wrangler.jsonc）；部署成功但 worker 不工作（缺少密钥或环境变量，需在 CI 中设置）；本地测试通过但 CI 失败（环境差异，需锁定 Bun 版本并使用 --frozen-lockfile）；预览部署冲突（在环境名中加入 PR 编号）；日志泄露密钥（避免 echo 密钥）。

参考文件与模板加载时机

设置 GitHub Actions、配置矩阵构建、使用 GitHub environments 与部署保护、实现部署门禁时加载 references/github-actions.md；设置 GitLab CI 流水线、环境、密钥变量、review apps 时加载 references/gitlab-ci.md；实现蓝绿部署、金丝雀发布、流量拆分、回滚流程时加载 references/deployment-strategies.md；跨环境管理密钥、轮换 API token、使用外部密钥提供商（Vault、1Password）、实现最小权限时加载 references/secrets-management.md。可直接加载 templates/github-actions-full.yml、templates/gitlab-ci-full.yml、templates/preview-deployment.yml、templates/rollback-workflow.yml，以及 scripts/verify-deployment.sh 用于部署校验、健康检查与冒烟测试。

安装与供应链安全

安装 CI/CD 依赖时建议：阻止安装后脚本（npm config set ignore-scripts true，Bun 默认禁用）；CI 中使用冻结锁文件（npm ci 或 bun install --frozen-lockfile）；在 CI 中加入安全门禁（如 socket ci）阻断违反安全策略的 PR。需要完整安全配置（含 Socket CLI 集成、冷却设置、锁文件校验与 CI 强制执行）时，加载 dependency-upgrade 技能。

技能介绍

用途