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

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

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

Service bindings 修订（2026-10-08，Agent：Codex）：根据当前官方文档与 Context7，补充独立 staging Worker、production deployment 与具名 Preview 的调用边界、通用配置及验收方法。示例仅使用虚构的通用名称；未部署或调用远端 Worker。运行记录：模型 gpt-6.1-sol，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，CLI 版本 0.162.0-alpha.2（不代表桌面 App 版本）。

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

涉及多 Worker 联调时，还要区分两件事：Preview 支持使用 Service bindings，但目前不能通过 Service binding 选择另一个 Worker 的具名 Preview。 独立 staging Worker 可以作为绑定目标；名为 staging 的 Preview 与它有不同的部署边界。下文的调用专题核对日期为 2026-10-08。Service bindings 限制

它解决了什么问题

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

Service bindings 能调用哪些环境

A Preview can use Service bindings to call a target Worker’s production deployment. It cannot select a named Preview of that target Worker today. Service bindings 限制

这里的 production deployment 是目标 Worker 的部署槽位，不等于它在业务上一定承载生产环境。例如，api-service-staging 是用于测试的独立 Worker；绑定它会调用它自己的 production deployment，并不会转去调用 api-service。目标必须与调用方位于同一 Cloudflare 账户。Wrangler environments、Service bindings

以下名称均为通用示例：

不要用名称推断部署方式。wrangler deploy --env staging 默认创建 <name>-staging 这个独立 Worker；wrangler preview --name staging 创建的则是原 Worker 下的 Preview。若 production 使用顶层配置，目标名称就是 api-service；若显式配置 env.production，默认名称才是 api-service-production。配置中覆盖过 name 时，以最终部署的实际 Worker 名为准。Environments

当前 services 的公开配置使用 binding、service 和可选的 entrypoint。service 是实际 Worker 名，entrypoint 是代码导出的入口名；它们都不是 Preview 选择器。即使两个 Worker 都创建了 pr-123 Preview，Service binding 也不会自动把它们配成一组。Service bindings 配置、多 Worker Preview 示例

示例：开发与 Preview 调 staging，生产调 production

下面使用两个已有的测试 Worker 项目演示。沿用上文的 Wrangler 版本前提；先登录同一个 Cloudflare 账户。两个项目各自保存 src/index.js 和 wrangler.jsonc。部署命令会改变远端状态，名称应替换为自己的测试资源；本文只校验代码与配置，没有执行远端部署。

目标 API 的代码只返回环境标记，便于判断请求去了哪里：

// API 项目的 src/index.js
export default {
  fetch(_request, env) {
    return Response.json({ environment: env.ENVIRONMENT });
  },
};

// API 项目的 wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "api-service",
  "main": "src/index.js",
  "compatibility_date": "2026-10-08",
  "preview_urls": true,
  "vars": { "ENVIRONMENT": "production" },
  "env": {
    "staging": {
      "vars": { "ENVIRONMENT": "staging" }
    }
  },
  "previews": {
    "vars": { "ENVIRONMENT": "preview" }
  }
}

调用方通过 Service binding 转发 HTTP 请求；下游由 binding 指定：

// 调用方项目的 src/index.js
export default {
  async fetch(request, env) {
    return await env.API.fetch(request);
  },
};

// 调用方项目的 wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "client-worker",
  "main": "src/index.js",
  "compatibility_date": "2026-10-08",
  "preview_urls": true,
  "services": [
    { "binding": "API", "service": "api-service" }
  ],
  "env": {
    "dev": {
      "services": [
        { "binding": "API", "service": "api-service-staging" }
      ]
    }
  },
  "previews": {
    "services": [
      { "binding": "API", "service": "api-service-staging" }
    ]
  }
}

services 使用数组。Wrangler environment 中的 bindings 不继承顶层配置，Preview 也需要自己的配置，所以这里分别声明顶层 services、env.dev.services 与 previews.services。三个位置可以使用相同的 binding 名 API，但指向不同 Worker。Service bindings 配置、Non-inheritable keys、Preview Configuration

先在 API 项目执行：

npx wrangler deploy --env staging
# 部署 api-service-staging，environment=staging。
npx wrangler deploy
# 部署 api-service，environment=production。

再在调用方项目执行：

npx wrangler deploy --env dev
# client-worker-dev → api-service-staging。
npx wrangler deploy
# client-worker → api-service。
npx wrangler preview --name pr-123
# client-worker 的 pr-123 Preview → api-service-staging。

验收时访问调用方部署命令返回的 URL：开发 Worker 与 Caller Preview 应返回 {"environment":"staging"}，生产 Worker 应返回 {"environment":"production"}。同时检查目标 Worker 的日志归属；URL 能打开不代表 binding 目标正确。这个标记接口仅用于验证部署选择，不承载实际业务数据。

需要调用另一个 Preview 时

有两个选择，取决于是否必须保留 Service binding / RPC：

1. 保留 Service binding / RPC：把测试 API 部署为独立 Worker，再用实际 Worker 名绑定。按分支部署独立 Worker 是本文的方案建议，会增加资源与清理工作，不能视为 Worker Previews 自动提供的隔离。
2. 保留目标 Preview：调用该 Preview 的 HTTP URL。目标必须暴露 HTTP fetch handler；调用方使用全局 fetch()，通过公共入口访问它。Preview URL、Worker-to-Worker Fetch

采用第二种方式时，可在调用方已有 wrangler.jsonc 中合入以下字段。API_PREVIEW_URL 的值应复制自目标 Worker 的部署输出；示意域名不可直接使用。为让 Worker-to-Worker 请求经过公共入口，示例显式启用顶层 global_fetch_strictly_public；合并到已有的 compatibility_flags 数组，不要覆盖其他所需 flag。Global fetch() strictly public

// 调用方配置片段：目标保留为 Preview，改走 HTTP URL。
{
  "compatibility_flags": ["global_fetch_strictly_public"],
  "vars": {
    "API_PREVIEW_URL": "https://replace-with-actual-preview-url.example.com"
  },
  "previews": {
    "vars": {
      "API_PREVIEW_URL": "https://replace-with-actual-preview-url.example.com"
    }
  }
}

普通调用方读顶层 vars，Caller Preview 读 previews.vars；若使用 --env dev 部署独立调用方，还需在 env.dev.vars 显式声明。对不同分支填写不同的目标 Preview URL，可以联调任意已存在且允许访问的目标 Preview，无须同名。

调用方代码替换为以下最小 HTTP 示例。它只发出不带凭据的 GET 请求读取上述环境标记，预期获得 {"environment":"preview"}：

// 调用方项目的 src/index.js：HTTP URL 方案。
export default {
  async fetch(_request, env) {
    return await fetch(env.API_PREVIEW_URL);
  },
};

具体顺序是：先在 API 项目运行 npx wrangler preview --name pr-456，将输出的 Preview URL 填入调用方配置；再在调用方项目运行 npx wrangler preview --name pr-123，访问 Caller Preview 的 URL。两端名称故意不同，用于验证按显式 URL 选择目标，而不是自动匹配分支。

不能把 env.API.fetch(previewUrl) 当作切换目标的方法。 Service binding 的 fetch() 仍调用绑定的 Worker，URL 只是交给该 Worker 的请求信息；只有全局 fetch(previewUrl) 才按公共地址路由。Fetcher URL 语义

HTTP URL 方案也不能直接替代 env.API.someRpcMethod()：RPC 方法需要 Service binding，走 URL 时应提供相应 HTTP 接口。若 Preview 由 Cloudflare Access 保护，机器调用还需获得相应授权；需要发送认证信息时，应使用受控目标地址与 secrets，不能把 token 写入 vars 或直接向任意传入 URL 转发凭据。HTTP Service bindings、RPC、Access service tokens

针对跨 Preview 联调，验收至少覆盖：目标返回 Preview 环境标记、日志落到所选 Preview、目标再次部署后 Preview URL 指向最新部署、调用方没有退回 production。需要固定某一次结果时，改用 Deployment URL；目标被删除或鉴权失败时，应明确失败，不自动回退到生产环境。这些是本文建议的验收标准，非平台自动保证。

同一 Worker 内的调用若需要留在当前 Preview，可用官方建议的 ctx.exports；它不提供跨 Worker 的 Preview 选择能力。Service bindings 限制

访问、观测与生命周期

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 文档导航