Workers Cache：为 Cloudflare Workers 打造的边缘缓存层，让服务器端渲染如静态站点般快速

一句话概括

Workers Cache 为 Cloudflare Worker 添加前置缓存层，通过 Cache-Control 头控制，实现零 CPU 成本的缓存命中与即时响应。

引言：从代理到源站，Workers 角色的转变

当 Cloudflare 在 2017 年推出 Workers 时，其核心定位是“在请求到达源站之前运行代码”。Worker 位于缓存和源站之间，用于修改请求头、重写 URL、A/B 测试或过滤流量。这种架构对于“将 Worker 作为源站的增强层”的场景非常合适。

但生态已经改变。如今，Workers 本身成为了源站——框架如 Astro、TanStack Start、Next.js、Remix 和 SvelteKit 都提供了 Cloudflare 适配器，将整个应用构建为一个 Worker。没有背后的源服务器，Worker 就是服务器。

当 Worker 是源站时，原来的架构中就没有东西可以缓存了。每次请求都会执行你的代码，即使返回的响应与前一秒返回的响应字节完全一致。Workers 运行时足够快（每秒处理数千万请求），但“快得足以渲染每一次请求”仍然意味着：每次页面加载都有延迟，每次调用都消耗 CPU 时间。对于服务器端渲染应用，每次页面加载本质上都是一次渲染。

Workers Cache 的核心架构：翻转的缓存位置

Workers Cache 改变了架构：现在，Cloudflare 的缓存位于 Worker 之前。

• 缓存命中时：Worker 完全不运行。Cloudflare 直接返回缓存的响应，CPU 计费为零。
• 缓存未命中时：Worker 运行一次，生成响应并存入缓存。后续来自全球任何地方的请求，都直接从缓存服务，无需调用你的代码。

这解决了 Workers 上服务器端渲染的关键缺失。此前开发者只有两个不太满意的选择：

1. 构建时预渲染所有页面（静态站点生成）：页面加载快，但每次内容变更都需要完整构建和重新部署。对于一个几千页的文档站点，这需要 5–10 分钟；对于大型电商站点，每次改动都要跑一次构建，代价高昂。
2. 每次请求都渲染页面：内容始终最新，但每个页面加载都要付出渲染成本，每个访问者都要承受延迟。

Workers Cache 提供了第三种选择：按需服务器渲染，缓存渲染后的响应，按你选择的 TTL 刷新。新页面的首次请求仍然渲染；后续所有请求（直到缓存过期）都像静态页面一样服务。缓存过期后，下一次请求触发重新渲染——而且结合 stale-while-revalidate，连那一次请求也无需等待。

你获得的是：静态站点的速度，无需构建时间；服务器渲染的新鲜度，无需每次请求都付出成本。无需框架特定的“增量静态再生”机制，只需 HTTP 缓存按设计方式工作，在原本就是源站的代码之前。

配置方式：一行 Wrangler 配置 + 标准 HTTP 头

启用 Workers Cache 极其简单。在 wrangler.toml 中添加一个配置块：

{
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2026-05-01",
"cache": {
"enabled": true
}
}

之后，通过标准的 Cache-Control 响应头控制缓存行为：

javascript
return new Response(body, {
headers: {
"Cache-Control": "public, max-age=300, stale-while-revalidate=3600",
"Cache-Tag": "products,product:123",
},
});

当内容变更时，通过标签或路径前缀编程式清除缓存：

javascript
await ctx.cache.purge({ tags: ["product:123"] });

这就是完整的 API。无需配置区域、无需设置规则引擎、无需预置独立缓存、无需登录另一个产品。Workers 代码本身就是配置面，缓存跟随 Worker 运行的地方——自定义域名、workers.dev、服务绑定、预览环境、Workers for Platforms 租户。一个 Worker，一个缓存，一次配置。

底层能力：分层缓存、stale-while-revalidate、Vary 与多租户安全

分层缓存

Workers Cache 是跨整个 Cloudflare 网络的分层缓存。缓存内容在全球数据中心之间高效分布和共享。

stale-while-revalidate：让体验“瞬间”的关键

stale-while-revalidate 指令告诉 Cloudflare：当缓存响应过期后，允许立即返回过期的副本，同时在后台异步刷新缓存。Cloudflare 在今年早些时候已全面支持该指令。

没有它：缓存条目过期后的第一个请求必须等待 Worker 从头渲染页面，用户会看到延迟。
有它：过期后的第一个请求立即获得过期页面（响应头中会包含 Cf-Cache-Status: UPDATING），Worker 在后台运行以重新填充缓存。每个用户——包括触发刷新的那个——都获得缓存速度的响应。

实践中的心智模型：

• 新鲜窗口（max-age）：Cloudflare 服务缓存响应，Worker 不运行。
• 陈旧窗口（stale-while-revalidate）：Cloudflare 服务缓存响应，Worker 在后台运行刷新，用户无需等待。
• 两个窗口之外：Cloudflare 运行 Worker 生成新鲜响应，用户等待这一次渲染。

你选择窗口大小。对于每几分钟更新的产品目录，max-age=300, stale-while-revalidate=3600 意味着访问者几乎从不等待，同时 Worker 运行频率足够保持内容新鲜。对于几乎不变的博客归档，max-age=86400, stale-while-revalidate=2592000 意味着每个页面每天只运行一次 Worker。全新页面的首次请求是唯一付出完整渲染成本的请求。之后，页面对于访问者就像静态输出，而 Worker 仍然控制着页面生成方式。

Vary：一个 URL，多种表示

真实应用很少给所有客户端返回相同的字节。同一产品页面可能对浏览器返回 HTML，对爬虫返回 JSON，对移动应用返回不同的结构化数据。Vary 头让缓存基于请求属性（如 Accept、Accept-Encoding、Accept-Language）存储和返回不同的响应版本。

Workers Cache 完全支持 Vary。你可以在 Worker 中根据请求特征返回不同内容，缓存会为每种变体单独存储。

多租户安全的缓存键

通过 ctx.props，Workers Cache 支持多租户安全的缓存键。每个租户的缓存条目自动隔离，不会互相污染。这对于 Workers for Platforms 等场景至关重要。

编程式清除：按标签或路径前缀

通过 ctx.cache.purge() 方法，可以按标签或路径前缀精确清除缓存。例如，当某个产品更新时，用标签 product:123 清除该产品的所有缓存页面（包括产品详情页、列表页等）。

javascript
await ctx.cache.purge({ tags: ["product:123"] });

或按路径前缀清除：

javascript
await ctx.cache.purge({ prefixes: ["/products/"] });

这使得缓存失效精确且高效，无需全局清除。

最大亮点：每个入口点独立的缓存控制

Workers Cache 最强大的特性是：缓存位于每个 Worker 入口点之前，而不仅仅是公开入口点。你可以对每个入口点独立控制是否启用缓存。

这意味着你可以将缓存直接组合到应用结构中：一条入口点链，中间插入缓存阶段，由两侧的代码配置。例如：

1. 一个 Worker 处理认证和请求路由，不缓存。
2. 路由到第二个 Worker，该 Worker 生成页面内容，启用缓存。
3. 第三个 Worker 处理 API 请求，根据端点决定是否缓存。

每个入口点都可以独立配置缓存行为，无需全局规则。

实际代码示例

以下是一个完整的 Workers Cache 使用示例：

javascript
export default {
async fetch(request, env, ctx) {
// 假设 renderPage 是一个耗时的服务器端渲染函数
const html = await renderPage(request);

return new Response(html, {
  headers: {
    "Content-Type": "text/html; charset=utf-8",
    // 新鲜 5 分钟；陈旧窗口 1 小时（后台刷新）
    "Cache-Control": "public, max-age=300, stale-while-revalidate=3600",
    // 按标签组织，方便精确清除
    "Cache-Tag": "pages,page:home",
  },
});

},
};

当首页内容更新时，你可以精确清除：

javascript
await ctx.cache.purge({ tags: ["page:home"] });

可用性与未来

Workers Cache 即日起对所有 Workers 计划（包括免费计划）开放，通过 Wrangler 启用。这是 Cloudflare 一直希望 Workers 拥有的缓存 API。

原文链接：https://blog.cloudflare.com/workers-cache/