示例 · Cloudflare Workers 文档

在自动化中直接使用 npx wrangler preview。开始之前，请先阅读资源与隔离。

Workers Builds

若 Worker 已连接到 Cloudflare，请启用 Preview Builds，并确认 Preview 命令为 npx wrangler preview。Workers Builds 会创建 Preview。对于 GitHub 和 GitLab 仓库，它还会在拉取请求上评论 Preview URL。

GitHub Actions

添加仓库密钥

将 Cloudflare 凭据添加到仓库：

gh auth login
gh secret set CLOUDFLARE_API_TOKEN
gh secret set CLOUDFLARE_ACCOUNT_ID

API token 需要有权限编辑 Workers Scripts 以及 Preview 使用的资源。GitHub 会自动提供 ${{ secrets.GITHUB_TOKEN }}。

仓库密钥默认对来自 fork 的拉取请求不可用。在暴露 Cloudflare 凭据之前，请验证 github.event.pull_request.head.repo.full_name == github.repository。

创建 Preview 并评论

此工作流为每个拉取请求创建一个 Preview，并评论其 URL：

.github/workflows/preview.ymlyaml

name: Preview

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]

permissions:
  contents: read
  pull-requests: write

jobs:
  preview:
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: preview
        name: Create or update Preview
        run: |
          set -o pipefail
          output="$(npx wrangler preview --name "pr-${{ github.event.pull_request.number }}" --json)"
          printf '%s\n' "$output"
          preview_url="$(printf '%s' "$output" | jq -er '.preview.urls[0]')"
          echo "preview_url=$preview_url" >> "$GITHUB_OUTPUT"
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
      - name: Comment Preview URL
        run: gh pr comment "${{ github.event.pull_request.number }}" --body "Preview: ${{ steps.preview.outputs.preview_url }}"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

在 Preview 步骤之前添加所需的安装或构建步骤。GitHub 托管的 Ubuntu runner 包含 jq，工作流用它读取 Preview URL。

若要更新同一条评论而不是每次运行都新建评论，请向 gh pr comment 添加 --edit-last --create-if-none。

探测 Preview

添加请求以验证已部署的 Preview：

.github/workflows/preview.ymlyaml

- name: Probe Preview
  run: curl --fail --show-error --silent "$PREVIEW_URL/api/health"
  env:
    PREVIEW_URL: ${{ steps.preview.outputs.preview_url }}

将 /api/health 替换为能验证 Worker 的路由。若探测失败，请使用 Workers Observability 或测试与调试。

捕获截图

将渲染后的 Preview 捕获为工作流产物：

.github/workflows/preview.ymlyaml

- name: Capture Preview screenshot
  run: |
    npx --yes playwright install --with-deps chromium
    npx --yes playwright screenshot "$PREVIEW_URL" preview.png
  env:
    PREVIEW_URL: ${{ steps.preview.outputs.preview_url }}

- uses: actions/upload-artifact@v4
  with:
    name: preview-screenshot
    path: preview.png

对于托管浏览器检查，请使用 Browser Run 的截图端点。

删除已关闭拉取请求的 Preview

上面的工作流触发器包含 closed 事件。在 jobs 下添加此清理作业：

.github/workflows/preview.ymlyaml

cleanup:
  if: github.event.action == 'closed'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Delete Preview
      run: npx wrangler preview delete --name "pr-${{ github.event.pull_request.number }}" --skip-confirmation
      env:
        CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

改用 wrangler-action

若你更喜欢封装层，请使用 cloudflare/wrangler-action ↗。它会将 Preview URL 作为输出暴露，并可创建 GitHub Deployment。

含多个 Worker 的 monorepo

Preview 名称的作用域是单个 Worker。在 monorepo 中，每个 Worker 都可以有同名的拉取请求 Preview：

cd workers/api && npx wrangler preview --name "pr-123"
cd ../web && npx wrangler preview --name "pr-123"

这些 Preview 之间的 service binding 会解析到被绑定 Worker 的生产部署。请参阅限制。

其他 CI 系统

对于其他 CI 系统，运行：

npx wrangler preview --name "$BRANCH_NAME" --json

使用 JSON 输出将 Preview URL 发布到你的审查工具。