跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

缓存

最后更新 查看 MarkdownAgent 设置

背景

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

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

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

不过,在 Cloudflare Workers 控制面板编辑器和 Playground 预览中执行的任何 Cache API 操作都不会产生影响。对于受 Cloudflare Access 保护的 Workers,目前无法使用 Cache API。


访问 Cache

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
  • Cache-Tag
    • 支持之后按标记清除资源。cache.match() 返回的响应不包含此标头。
  • ETag
    • 允许 cache.match() 使用 If-None-Match 评估条件请求。
  • Expires 字符串
    • 指定资源何时失效的字符串。
  • Last-Modified
    • 允许 cache.match() 使用 If-Modified-Since 评估条件请求。

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


方法

Put

cache.put(request, response);
  • put(request, response) : Promise

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

否则,如果按标记清除操作发生在 match() 和 put() 调用之间,新条目就不会带有标记。之后按标记清除时不会移除该条目,但按 URL 清除可以。

如需确保每次写入都保留标记,请在首次存储响应时将标记复制到自定义标头中。然后在每次调用 put() 之前,从该标头恢复 Cache-Tag。

:::

参数

  • request 字符串 | 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 错误。

Match

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

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

参数

  • request 字符串 | 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)中过滤。要过滤这些请求,或仅过滤您网站最终用户的请求,请参阅 过滤最终用户。

Delete

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

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

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

参数

  • request 字符串 | Request

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

    • 可包含一个属性:ignoreMethod(Boolean)。无论实际值如何,都将请求方法视为 GET。

相关资源

这篇文档对您有帮助吗?