Cloudflare Access for Workers 怎么接入：策略绑定、预览域与回归验收

同一个 Worker 往往同时挂着路由、Custom Domain、workers.dev 和版本预览地址。以前每增加一个入口，就要回到 Access 应用里补一条域名；2026 年 8 月 Cloudflare 把保护范围下沉到 Worker 本身后，策略可以跟着 Worker 覆盖这些关联入口，接入重点也从“填多少域名”变成“选对流量范围并验收每种请求”。

如果目标是先锁住测试环境，优先选择单个 Worker 的“仅预览”范围；如果生产也要登录，再切换到“预览和生产”，并把 WebSocket 单独改用基于主机名的 Access 应用。

先把入口和策略目标对齐

这次变化最有价值的地方，是策略对象从某个 URL 变成了 Worker。一个内部文档预览 Worker 可能有 preview-abc-docs.example.workers.dev、正式的 docs.example.com，还挂着一条 route；如果只保护其中一个 hostname，下一次改路由时很容易漏掉入口。

单 Worker 配置有两个流量选择：只保护预览，或者同时保护生产和预览。官方 API 分别用 preview_worker 和 worker 表达这两个目标；账户级默认保护则对应 all_preview_workers 与 all_workers。这四个名字不要混成“全站开关”，它们决定了策略未来是否自动覆盖新建 Worker。

从控制台绑定单个 Worker

打开 Cloudflare 控制台，进入 Workers & Pages 板块，找到目标 Worker 的 Access 标签页，选择 Protect this Worker behind Access。接着选 Previews only 或 All traffic，绑定你已经创建好的认证策略，最后点 Apply Access 即可。

这里先别急着选 All traffic。如果你的需求只是让产品、测试和安全同事查看还没发布的版本，用 Previews only 更容易验证，也不会不小心把生产接口跳成登录页。正式环境确实需要登录校验时，先确认所有调用方都能正常处理 302 跳转、登录流程和会话过期逻辑，再扩大保护范围。

把配置映射到 API 和 Worker 代码

自动化团队可以直接调用 Access Applications API 创建自托管应用。如果只需要保护单个 Worker 的预览环境，目标参数和下面的示例类似，示例里的 Worker ID 是占位值，不能直接当成真实资源提交使用。

{
  "type": "self_hosted",
  "name": "Access for docs-worker previews",
  "destinations": [
    {"type": "preview_worker", "worker_id": "YOUR_WORKER_ID"}
  ],
  "policies": [
    {
      "decision": "allow",
      "include": [{"email_domain": {"domain": "example.com"}}]
    }
  ]
}

通过认证的请求进入 Worker 后，可以用 ctx.access 读取身份，不必在业务代码里重复解析 Access JWT：

export default {
  async fetch(request, env, ctx) {
    if (!ctx.access) {
      return new Response("Access did not run", { status: 401 });
    }
    const identity = await ctx.access.getIdentity();
    return Response.json({
      email: identity?.email,
      aud: ctx.access.aud
    });
  }
};

业务接口本身还是要自行判断哪些字段可以返回。登录成功只代表请求经过了 Access 校验，不等于所有通过身份校验的请求都能拿到全部业务权限，管理员后台、普通预览页和写入类接口，后续还是要继续做角色级别的权限判断。

预览 URL、Custom Domain 与 WebSocket 的边界

版本预览 URL 通常由版本前缀或别名组成，别名需要以小写字母开头，只能使用小写字母、数字和连字符。上传版本时可以用 wrangler versions upload --preview-alias staging 创建一个可读别名。它适合接入 CI，但不要把别名当成长期生产域名。

Custom Domain 是另一类入口。若策略绑定在 Worker 级别，它会随 Worker 覆盖 routes、Custom Domains、workers.dev 和预览；若只想保护一个特殊主机名，则使用 hostname-based Access 更直观。两种方式不要叠加到无法解释的状态，验收时要能说清“请求命中了哪条策略”。

最容易漏掉的是 WebSocket。官方文档明确指出 Worker 级 Access 策略目前不支持 WebSocket 连接，升级请求会得到 403。实时协作、Durable Objects 或 RDP-over-WebSocket 场景，应改用基于主机名的 Access 应用，并把升级请求作为单独回归项。

用四组请求完成回归验收

配置全部完成之后，别只在浏览器里登录一次就完事。分别给预览地址、生产地址各加一条健康检查，再补一条未登录的请求和一条 WebSocket 升级请求，最终结果要符合明确的校验矩阵：

• 策略允许的邮箱访问预览地址：正常走完登录流程后返回业务内容，Worker 日志里能读到对应的访问身份。
• 不在策略范围内的邮箱访问预览地址：直接被 Access 拦截，无法进入 Worker 的正常业务分支。
• 如果生产也加了保护：同一个身份访问生产地址时，要和访问预览地址的认证逻辑完全一致；如果选的是仅预览保护，生产应该保持原本的公开/内部网络访问策略。
• WebSocket：Worker 级策略下预期为 403，若业务依赖实时连接，应切换 hostname-based Access 后重新验证。

本地开发也可以在 wrangler.jsonc 的 dev.access 中注入测试身份，让业务代码看到与线上相同的 ctx.access 形状。测试块只用于本地模拟，提交前要检查不会把测试邮箱或 audience 当成线上凭据。

相关问题：常见误区与回滚边界

开启后仍能访问，是策略失效了吗？

先确认你访问的确实是配置保护的流量范围。选 Previews only 的时候，不能用生产入口的访问结果来判断预览侧的策略是否生效；选 All traffic 的时候，再排查是不是用了其他基于 hostname 的 Access 应用或者缓存响应覆盖了逻辑。

为什么 WebSocket 只有 403？

这是 Worker 级 Access 的已知限制，不是多复制几条 allow 规则就能解决的。把长连接类服务拆到单独的主机名下，再用基于主机名的 Access 保护，才是可稳定验证的处理方案。

账户级保护适合所有团队吗？

这个功能适合希望所有新建、存量 Worker 默认私有部署的团队，但对外公开的 Worker 还要额外配置 Worker 级 bypass 规则。启用之前先梳理好所有公共资源和自动化探针地址，不然健康检查接口可能比业务先报 401 或者触发登录跳转。

把发布门禁写成可重复检查

Cloudflare 这次更新减少了域名清单维护，却没有替团队完成权限设计。比较稳妥的门禁顺序是：先确认 Worker 与策略范围，再确认预览别名和关联域名，随后检查 ctx.access 身份，最后跑一遍未登录、越权、生产范围和 WebSocket 回归。只有每一项结果都能解释，才适合把 Access 设置推广到账户级。