Cloudflare Worker Previews：按分支管理预览环境

原始资料：Cloudflare Workers Previews 官方文档

AI 参与说明（Agent：Codex）：本文由 Codex 根据 Cloudflare 官方文档与更新公告整理，并用 Context7 核对，资料日期为 2026-09-28。能力与限额以文中官方来源为准。运行记录：执行入口 Codex Desktop；完整模型标识与 reasoning effort 未取得运行记录。

结论：需要为每个开发分支提供可访问、可观察且可配置的测试环境时，优先考虑 Worker Previews。 它在同一个 Worker 下管理多个 Preview；生产部署仍走原来的生产命令。Cloudflare 于 2026-09-22 发布这套方案，本文核对的概览文档更新于 2026-09-24。

它解决了什么问题

A Preview runs under the same Worker with its own code, configuration, URL, and observability. Preview settings are explicit; production settings are not inherited. Previews 概览、Configuration

开发者在 feature/login 分支运行 npx wrangler preview，Wrangler 默认以当前 Git 分支命名，创建或更新对应的 Preview。重复部署后，Preview URL 仍指向最新版本；每次部署另有固定的 Deployment URL，适合在评审中复现某次结果。生产分支仍使用 npx wrangler deploy。可选 workers.dev 或自定义域名作为 Preview 地址。Get started、Custom domains

Cloudflare 现在推荐用 Worker Previews 做分支测试。旧的 aliased Version URLs（例如 wrangler versions upload --preview-alias staging）可以迁移为 wrangler preview --name staging；两者的资源边界并不等价。Compare workflows

最小使用流程

前提：项目依赖中的 Wrangler 至少为 4.135.0；有可部署的 Worker 与 Cloudflare 账号权限。无需先把 Worker 部署到生产。升级的是项目依赖，因为项目里的 npx wrangler 不会因全局 Wrangler 较新而自动换版本。Get started

下面是一个不接外部存储的最小 JavaScript 示例。将文件分别保存为 src/index.js 和 wrangler.jsonc；已有项目应把对应字段合入自己的配置，而不是覆盖现有设置。

// src/index.js
export default {
  fetch(_request, env) {
    return new Response(`mode=${env.MODE}`);
  },
};

// wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "hello-previews",
  "main": "src/index.js",
  "compatibility_date": "2026-09-28",
  "preview_urls": true,
  "vars": {
    "MODE": "production"
  },
  "previews": {
    "vars": {
      "MODE": "preview"
    }
  }
}

previews 块是必需的；没有单独设置时也可以写成 {}。示例把 Preview 的 MODE 显式设为 preview，因为顶层的生产变量不会自动继承。compatibility_date、compatibility_flags 和静态资源 assets 等字段保留在顶层；存储 binding 应在 previews 中指向测试资源。preview_urls: true 明确启用 workers.dev Preview 地址。Configuration、Custom domains

在该项目中安装依赖、完成登录后，可以按下面的顺序创建、检查并清理一个明确命名的 Preview。示例命令会修改 Cloudflare 远端状态，请在自己的测试 Worker 中执行；本文没有执行这些远端命令。

npm install --save-dev wrangler@latest
npx wrangler login
npx wrangler preview --name feature-login
# 打开命令返回的 Preview URL，预期响应为 mode=preview。
npx wrangler preview delete --name feature-login

实际分支开发时可省略 --name，直接用 Git 分支名。为 Pull Request 自动生成地址时，可连接 Workers Builds 并开启 Preview Builds；新接入的 Worker 默认使用 npx wrangler preview 作为 Preview command，Workers Builds 可将 URL 评论到 Pull Request。Get started、Build branches、Examples

配置与数据隔离要逐项检查

在基础分支配置 previews 块，新分支通过 Git 带走该配置，必要时可在分支内改写。密钥不写进配置文件：npx wrangler preview base-config secret put API_KEY 为之后创建的 Preview 设置基础密钥；npx wrangler preview secret put API_KEY --name feature-login 改某个现有 Preview。更新基础密钥不会追溯更新已创建的 Preview。 Configuration

这些限制决定了“独立 Preview”不等于“所有外部资源自动复制”。尤其是 D1，迁移应先应用到该分支实际绑定的数据库；两个 Preview 指向同一个测试库时也会共享表和记录。Durable Object 状态在同一 Preview 的多次部署间持续存在，删除 Preview 时才会删除。Containers 的 Preview 支持目前仍有部分限制，要确认进程实际启动并响应。Resources and isolation

访问、观测与生命周期

Preview URL 默认可公开访问。workers.dev Preview 地址自动带 X-Robots-Tag: noindex，但 noindex 不是访问控制；需要限制评审范围时配置 Cloudflare Access。自定义域名 Preview 地址不会自动获得这个 noindex 头，公开使用时应自行设置。Previews 概览、Custom domains

每个 Preview 可单独查看日志、trace 和指标；可以在 previews.observability 中设置与生产不同的采样。当前 wrangler tail 不支持 Preview，实时事件需要用 Tail Worker 或 Logpush 等方式处理。Test and debug

截至 2026-09-28，Cloudflare 文档列出的上限是：免费计划每个 Worker 100 个 Preview，付费计划 500 个，每个 Preview 100 次部署。达到上限时会删除最久未部署的 Preview，或删除该 Preview 中最旧的部署。仍建议在 Pull Request 关闭时用 wrangler preview delete 清理，避免无用 Preview 占用名额；删除前应确认不再需要其 Durable Object 状态。Previews 概览、Examples

使用 Containers 时还要检查清理结果：删除 Preview 后，自动生成的 container app 可能仍出现在 wrangler containers list 中。核对它确实属于已删除的 Preview，再按其 ID 单独删除；不能只按 Worker 名称批量删除，以免碰到生产 app。Container application cleanup

迁移已有 Workers Builds 项目时

先确认该 Worker 当前使用哪套预览模型。 新接入 Workers Builds 的 Worker 默认使用 Worker Previews；在这项能力推出前已连接 Builds 的 Worker 会保留旧模型，直到在控制台完成一次切换。Cloudflare 明确说明切换不可逆；切换前应补齐 previews 配置、密钥和测试 binding，并检查原 Preview command 是否有自定义逻辑，切换后必须调用 npx wrangler preview。Build branches

验收一条分支时，检查返回的 Preview URL 能正常访问、响应实际读取了 Preview 变量与测试资源、日志归属正确；如依赖 Service bindings、Workflows、Queue 或 Cron，再按上面的边界做专项检查。生产流量仍通过原生产地址与部署命令管理，不因创建 Preview 自动切换。Previews 概览、Resources and isolation

关联阅读

• Workers Builds：能承担哪些工作，与 GitHub Actions 如何分工
• Cloudflare 文档导航