如何结合 GitHub Actions 和 Wrangler CLI 实现 Cloudflare Pages 的自动化 CI/CD 部署？

结合 GitHub Actions 和 Wrangler CLI 可以实现：当代码 Push 到 GitHub 仓库时，自动运行打包构建，并通过 Wrangler 部署到 Cloudflare Pages（支持主分支自动发布生产环境、非主分支自动生成预览链接）。

一、 准备工作：获取 Cloudflare 凭证

在配置 GitHub 密钥前，需要先从 Cloudflare 控制台获取 API Token 和 Account ID。

    获取 API Token

        登录 Cloudflare 控制台，点击右上角头像 ➔ My Profile ➔ API Tokens。

        点击 Create Token，选择 Edit Cloudflare Workers 模板（该模板默认包含 Cloudflare Pages 的编辑权限）。

        创建后保存生成的 Token（注意：页面刷新后无法再次查看）。

    获取 Account ID

        进入 Cloudflare 控制台首页，点击任意域名或左侧的 Workers & Pages 菜单。

        在页面右侧栏中找到并复制 Account ID。

二、 在 GitHub 仓库设置 Secrets

将获取到的凭证安全地添加到 GitHub 仓库中：

    打开 GitHub 仓库，选择 Settings ➔ Secrets and variables ➔ Actions。

    点击 New repository secret，添加以下两个密钥：

        CLOUDFLARE_API_TOKEN：填入步骤一获取的 API Token。

        CLOUDFLARE_ACCOUNT_ID：填入步骤一获取的 Account ID。

三、 配置 GitHub Actions 工作流

在项目的 .github/workflows/ 目录下创建部署配置文件 deploy.yml：

name: Deploy Cloudflare Pages

on:
  push:
    branches:
      - main     # 触发生产环境部署的分支
      - staging  # 触发测试/预览环境部署的分支
  pull_request:  # PR 提交时自动生成 Preview 预览链接

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm' # 根据使用的包管理器调整（npm/pnpm/yarn）

      - name: Install Dependencies
        run: npm ci

      - name: Build Project
        run: npm run build # 确保该命令在 dist/ 或 build/ 目录生成产物

      - name: Publish to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy ./dist --project-name=my-cloudflare-pages-app

四、 关键配置细节解析
1. 自动分支环境隔离（Production vs Preview）

cloudflare/wrangler-action 结合 pages deploy 会自动识别触发构建的 Git 分支：

    main 分支推拉：默认部署至生产环境地址（如 [https://my-app.pages.dev](https://my-app.pages.dev)）。

    非 main 分支/PR：自动生成带有分支名的预览环境地址（如 https://<commit-hash>.my-app.pages.dev）。

如果需要显式定义环境，可在 command 中补充 --branch 参数：

command: pages deploy ./dist --project-name=my-app --branch=${{ github.ref_name }}

2. 如果包含 Pages Functions (后端 API)

由于全栈项目的后端代码存放在 ./functions 目录，Wrangler 会在部署打包文件（如 ./dist）时自动将 ./functions 一并同步上传。无需改变 Action 的配置命令，保持 pages deploy ./dist 即可。
五、 部署验证

    提交并 Push 变更到仓库：

    git add .
    git commit -m "ci: add cloudflare pages deployment workflow"
    git push origin main

    打开 GitHub 仓库的 Actions 标签页，查看工作流运行进度。

    构建完成后，展开 Publish to Cloudflare Pages 步骤日志，可以查看到部署成功的线上访问 URL 和部署 ID。