缓存

Cache API ↗ 可精细控制从 Cloudflare 全球网络 ↗ 缓存中读取和写入。

Cache API 在全球范围内可用，但缓存内容不会在源数据中心之外复制。GET /users 响应可以在源数据中心缓存，但除非显式创建，否则不会存在于其他数据中心。

部署到自定义域名的 Worker 可使用完整的 cache 操作。Pages functions 同样如此，无论绑定到自定义域名还是 *.pages.dev 域名。

但在 Cloudflare Workers 仪表板编辑器和 Playground 预览中，任何 Cache API 操作都不会生效。对于由 Cloudflare Access ↗ 前置的 Worker，Cache API 目前不可用。

caches.default API 深受 Web 浏览器 Cache API 的影响，但存在一些重要差异。例如，Cloudflare Workers 运行时公开单个全局 cache 对象。

let cache = caches.default;
await cache.match(request);

您可以通过 caches.open ↗ 方法创建和管理其他 Cache 实例。

let myCache = await caches.open('custom:cache');
await myCache.match(request);

我们的 Cache API 实现会尊重传递给 put() 的响应上的以下 HTTP 标头：

• Cache-Control
  • 控制缓存指令。这与 Cloudflare Cache-Control 指令 一致。当不存在 Cache-Control 指令时，请参阅 Edge TTL 了解 HTTP 响应码及其 TTL 列表。
• Cache-Tag
  • 允许后续按标签清除资源。
• ETag
  • 允许 cache.match() 使用 If-None-Match 评估条件请求。
• Expires string
  • 指定资源何时失效的字符串。
• Last-Modified
  • 允许 cache.match() 使用 If-Modified-Since 评估条件请求。

这与 Web 浏览器 Cache API 不同，后者不会尊重请求或响应上的任何标头。

cache.put(request, response);

• put(request, response) : Promise

  • 尝试将响应添加到缓存，使用给定请求作为键。返回一个 promise，无论缓存是否成功存储响应，都会 resolve 为 undefined。

• request string | Request

  • 用作键的字符串或 Request 对象。如果传入字符串，则将其解释为新建 Request 对象的 URL。

• response Response

  • 要在给定键下存储的 Response 对象。

在以下情况下，cache.put 会抛出错误：

• 传入的 request 使用的不是 GET 方法。
• 传入的 response 的 status 为 206 Partial Content ↗。
• 传入的 response 包含标头 Vary: *。Vary 标头的值为星号（*）。更多信息请参阅 Cache API 规范 ↗。

如果 Cache-Control 指示不缓存，或响应过大，cache.put 会返回 413 错误。

cache.match(request, options);

• match(request, options) : Promise<Response | undefined>

  • 返回一个 promise，包装与该请求关联的响应对象。

• request string | Request

  • 用作查找键的字符串或 Request 对象。字符串会被解释为新建 Request 对象的 URL。

• options

  • 可包含一个属性：ignoreMethod（Boolean）。当为 true 时，无论实际值如何，请求都被视为 GET 请求。

与浏览器 Cache API 不同，Cloudflare Workers 不支持 match() 上的 ignoreSearch 或 ignoreVary 选项。您可以在 put() 时移除查询字符串或 HTTP 标头来实现此行为。

我们的 Cache API 实现会尊重传递给 match() 的请求上的以下 HTTP 标头：

• Range

  • 如果找到带有 Content-Length 标头的匹配响应，则返回 206 响应。您的 Cloudflare 缓存始终尊重范围请求，即使响应上有 Accept-Ranges 标头。

• If-Modified-Since

  • 如果找到匹配响应，且 Last-Modified 标头的值早于 If-Modified-Since 指定的时间，则返回 304 响应。

• If-None-Match

  • 如果找到匹配响应，且 ETag 标头的值与 If-None-Match 中的值匹配，则返回 304 响应。

当请求的内容缺失或过期时，cache.match 会生成 504 错误响应。Cache API 不会直接向 Worker 脚本暴露此 504，而是返回 undefined。不过，底层 504 仍可在 Cloudflare Logs 中看到。

如果您使用 Cloudflare Logs，可能会看到 RequestSource 为 edgeWorkerCacheAPI 的 504 响应。同样，如果缓存资源缺失或过期，这些响应是预期的。请注意，edgeWorkerCacheAPI 请求已在其他视图（如 Cache Analytics）中过滤。要过滤这些请求，或仅过滤您网站最终用户的请求，请参阅 过滤最终用户。

cache.delete(request, options);

• delete(request, options) : Promise<boolean>

从缓存中删除 Response 对象，并返回 Boolean 响应的 Promise：

• true：响应已缓存但现已删除
• false：删除时响应不在缓存中。

• request string | Request

  • 用作查找键的字符串或 Request 对象。字符串会被解释为新建 Request 对象的 URL。

• options object

  • 可包含一个属性：ignoreMethod（Boolean）。无论实际值如何，都将请求方法视为 GET。

• 缓存工作原理
• 示例：使用 fetch() 缓存
• 示例：使用 Cache API
• 示例：缓存 POST 请求