Workers Cache 可以在 Worker 前直接命中缓存，但认证网关、租户数据和错误响应不能一起缓存。上线前要先拆入口，再核对 cache key、TTL、清除和回滚。
- 01先读摘要，判断是否与你的场景相关。
- 02再看来源，保留继续查证的路径。
- 03最后看步骤、风险和可复用动作。
Workers Cache 放在 Worker 入口前，命中时连 Worker 代码都不运行。它能省掉计算和回源，也会放大配置错误：把认证入口缓存、把租户响应混在一起、把 500 缓存太久，都会比普通 Cache API 更难察觉。上线前要先拆入口，不能只加一行配置。
更新依据与能力边界
更新日期：2026-07-15。Cloudflare 7 月 6 日发布 Workers Cache，说明所有计划可用，可通过 Wrangler 配置开启，并用标准 Cache-Control 控制响应。它覆盖默认 export、命名 WorkerEntrypoint、service binding 调用和 ctx.exports 调用。服务绑定里的 ctx.props 会进入缓存键，用于区分租户或用户上下文。
适用场景
- 公开 API、渲染结果、配置查询或计算昂贵但短期稳定的响应。
- 一个 Worker 内有多个 entrypoint，希望只缓存其中的读取层。
- service binding 之间重复调用同一个只读结果。
- 已有清晰 Cache-Control、清除和监控策略。
不适用场景
- 登录、鉴权、支付、写入、一次性 token、用户私密数据入口。
- 响应依赖 Cookie、Authorization 或其他未进入缓存键的上下文。
- 无法接受短时间旧数据，也没有 purge 或版本化 key。
- 团队还分不清 Workers Cache、fetch 缓存和 Cache API 的作用位置。
上线前准备
- 画出入口图：default export、命名 entrypoint、service binding、ctx.exports 和源站。
- 标记每个入口是否认证、是否写数据、是否包含租户或用户内容。
- 为可缓存响应确定 TTL、stale 策略、错误状态和 purge 方式。
- 准备命中与未命中测试、两个租户测试、回滚配置和基线延迟。
上线步骤
- 只选择纯读取 entrypoint。认证、路由和规范化网关保持不缓存，让它每次都运行。
- 在 wrangler.jsonc 或对应配置中为目标 export 开启 cache。不要一次打开所有入口。
- 在响应上设置 Cache-Control。公开稳定数据可给短 TTL 起步；用户或租户数据需要明确 private/no-store 或可靠隔离。
- 构造两次相同请求验证 MISS 到 HIT，再改变路径、query 和租户 ctx.props，确认不该共用的响应不会命中同一对象。
- 测试 200、404、429、500。错误状态不要继承过长 TTL，尤其是后端短暂故障。
- 上线 5% 流量，监控 Worker invocation、回源、P50/P95、错误率和数据新鲜度，再逐步扩大。
{
"exports": {
"default": { "cache": { "enabled": false } },
"publicCatalog": { "cache": { "enabled": true } }
}
}
Cache-Control: public, max-age=60配置形状应以当前 Cloudflare 文档和 Wrangler schema 为准。示例表达的是“网关不缓存、公开读取入口缓存”的分层思路，不应盲贴到生产。
可复用示例：多租户内容摘要
一个网关先验证租户 token，再通过 service binding 调用 summary entrypoint。网关每次运行，summary 结果按路径、query 和 ctx.props 中的 tenantId 隔离。测试时用 tenant-a 与 tenant-b 请求相同文档 ID，响应必须各自命中，不能串数据。若业务代码没有把租户信息放进受支持的上下文，先不要缓存。
验收清单
- 认证网关始终执行，没有被缓存跳过。
- 相同公开请求能从 MISS 变为 HIT。
- 不同租户、用户、语言和权限不会误用同一响应。
- 404、429、500 的 TTL 已单独验证。
- 内容更新后能 purge、变更 key 或等待可接受 TTL。
- 回滚只需关闭对应 export 的 cache 并重新部署。
- 监控能看到命中率、回源量、错误和新鲜度投诉。
常见坑与排错
- 把 Cache API 的经验直接套到 Workers Cache。二者所在位置不同，命中后是否执行 Worker 也不同。
- 只测同一租户。隔离问题往往要用两个账户、两种权限才能发现。
- 用很长 TTL 掩盖源站慢。先从 30 至 60 秒起步，确认清除和新鲜度再放大。
- 缓存突然不命中：检查方法、状态码、Cache-Control、query、ctx.props 和 entrypoint 名称。
- 数据串租户：立即关闭该入口缓存，清除缓存，再审计上下文和缓存键。
判断规则
- 如果响应包含用户、组织或权限差异，而这些差异没有可靠进入缓存键，设置 no-store，不上线缓存。
- 如果源站 P95 明显下降但新鲜度投诉增加，先缩短 TTL，不用继续提高命中率。
- 如果 404 和 500 会快速恢复，错误 TTL 设得比成功响应短；无法确认时不缓存错误。
- 如果发现租户串数据，立即关闭对应 export、清除缓存并按数据事件审计，不能只改 key 后继续运行。
发布后复查
上线 1 小时看错误和串租户迹象，24 小时看命中与回源，7 天看内容新鲜度。每次增加 Cookie、权限、租户字段或新的 service binding，都重新跑隔离测试。缓存收益可以慢慢调，数据边界错了就必须先停。