GitHub Actions 矩阵构建 + Cloudflare Pages 部署：打造全自动多环境 CI/CD 流水线实战

创建 Cloudflare Pages 项目与 API Token

登录 Cloudflare Dashboard，进入 Pages 创建新项目（或直接使用现有项目）。然后创建 API Token：

• 导航至「我的个人资料」→「API Tokens」→「创建 Token」
• 选择模板「编辑 Cloudflare Pages」，或手动勾选权限：Account.Cloudflare Pages#edit
• 限制到特定 Account 和 Project，点击「继续摘要」并生成 Token

配置 GitHub Secrets 存储敏感信息

进入 GitHub 仓库的 Settings → Secrets and variables → Actions，添加以下 Secrets：

# Cloudflare API Token（必需）
CLOUDFLARE_API_TOKEN=你的 API Token

# Cloudflare Account ID（可选，用于多项目管理）
CLOUDFLARE_ACCOUNT_ID=你的账户 ID

# 部署环境分支映射（可选）
STAGING_BRANCH=staging
PRODUCTION_BRANCH=main

这些 Secrets 将在 workflow 中通过 ${{ secrets.SECRET_NAME }} 语法引用。

初始化 Wrangler 配置

在项目根目录安装 Wrangler CLI 并初始化 Pages 配置：

# 安装 Wrangler（推荐全局安装）
npm install -g wrangler

# 或使用 pnpm/bun
pnpm add -g wrangler
bun add -g wrangler

# 初始化 Pages 项目（交互式）
wrangler pages project create your-project-name

# 本地测试构建（验证配置）
wrangler pages dev ./dist --port 8788

初始化完成后，项目根目录将生成 wrangler.toml 配置文件，包含项目名称、兼容性标志等设置。

编写 GitHub Actions 矩阵构建 Workflow

创建 .github/workflows/ci-cd.yml，定义完整的 CI/CD 流水线：

name: CI/CD Pipeline

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

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20]
        include:
          - node-version: 18
            test-flags: '--coverage'
          - node-version: 20
            test-flags: '--coverage --experimental-vm-modules'

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test ${{ matrix.test-flags }}

      - name: Build
        run: npm run build
        if: matrix.node-version == 20

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: dist-node${{ matrix.node-version }}
          path: ./dist
          retention-days: 1
        if: matrix.node-version == 20

这个配置会并行运行两个 Node.js 版本的测试，仅在 Node 20 上执行构建并上传产物。

添加 Cloudflare Pages 部署 Job

在同一 workflow 文件中追加部署 job，根据分支自动判断目标环境：

  deploy:
    needs: build-and-test
    runs-on: ubuntu-latest
    if: github.event_name == 'push'
    environment:
      name: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}
      url: ${{ steps.deploy.outputs.deployment-url }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: dist-node20
          path: ./dist

      - name: Setup Wrangler
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

      - name: Deploy to Cloudflare Pages
        id: deploy
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: your-project-name
          directory: ./dist
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.ref == 'refs/heads/main' && 'main' || 'staging' }}

配置 Wrangler 多环境支持

修改 wrangler.toml 添加多环境配置，实现 Staging/Production 差异化管理：

name = "your-project-name"
compatibility_date = "2025-12-01"
pages_build_output_dir = "./dist"

# 生产环境配置
[vars]
ENVIRONMENT = "production"
API_BASE_URL = "https://api.example.com"
LOG_LEVEL = "error"

# 预发环境覆盖配置
[env.staging]
name = "your-project-name-staging"
routes = []
[env.staging.vars]
ENVIRONMENT = "staging"
API_BASE_URL = "https://staging-api.example.com"
LOG_LEVEL = "debug"

部署时通过 --env staging 或 --env production 指定环境，Wrangler 会自动加载对应配置。

优化构建缓存与部署速度

2026 年 GitHub Actions 与 Cloudflare Pages 均支持构建缓存，配置后可提升 50% 速度：

      - name: Cache npm dependencies
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-npm-

      - name: Cache Wrangler build
        uses: actions/cache@v4
        with:
          path: .wrangler/state
          key: ${{ runner.os }}-wrangler-${{ hashFiles('wrangler.toml') }}
          restore-keys: |
            ${{ runner.os }}-wrangler-

对于大型项目，还可启用 Cloudflare Pages 的远程缓存：

# wrangler.toml 添加
[pages_build]
output_dir = "./dist"
enable_cache = true
cache_key = "${{ github.sha }}"

添加部署通知与回滚机制

生产级 CI/CD 必须包含失败通知与快速回滚能力。在 workflow 末尾添加：

  notify:
    needs: deploy
    runs-on: ubuntu-latest
    if: failure() && github.ref == 'refs/heads/main'
    steps:
      - name: Send Slack notification
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "🚨 生产环境部署失败！",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "*生产部署失败*\n仓库：${{ github.repository }}\n分支：${{ github.ref }}\n提交：${{ github.sha }}\n运行：${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
                  }
                }
              ]
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

  rollback:
    needs: deploy
    runs-on: ubuntu-latest
    if: failure() && github.ref == 'refs/heads/main'
    steps:
      - name: Rollback to previous deployment
        run: |
          wrangler pages deployment rollback --env production