Cache API ↗ 可精细控制从 Cloudflare 全球网络 ↗ 缓存中读取和写入。
Cache API 在全球范围内可用,但缓存内容不会在源数据中心之外复制。GET /users 响应可以在源数据中心缓存,但除非显式创建,否则不会存在于其他数据中心。
部署到自定义域名的 Worker 可使用完整的 cache 操作。Pages functions 同样如此,无论绑定到自定义域名还是 *.pages.dev 域名。
不过,在 Cloudflare Workers 控制面板编辑器和 Playground 预览中执行的任何 Cache API 操作都不会产生影响。对于受 Cloudflare Access 保护的 Workers,目前无法使用 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 列表。
- 控制缓存指令。这与 Cloudflare Cache-Control 指令 一致。当不存在
Cache-Tag- 支持之后按标记清除资源。
cache.match()返回的响应不包含此标头。
- 支持之后按标记清除资源。
ETag- 允许
cache.match()使用If-None-Match评估条件请求。
- 允许
Expires字符串- 指定资源何时失效的字符串。
Last-Modified- 允许
cache.match()使用If-Modified-Since评估条件请求。
- 允许
这与 Web 浏览器 Cache API 不同,后者不会尊重请求或响应上的任何标头。
cache.put(request, response);-
put(request, response): Promise- 尝试将响应添加到缓存,使用给定请求作为键。返回一个 promise,无论缓存是否成功存储响应,都会 resolve 为
undefined。
- 尝试将响应添加到缓存,使用给定请求作为键。返回一个 promise,无论缓存是否成功存储响应,都会 resolve 为
否则,如果按标记清除操作发生在 match() 和 put() 调用之间,新条目就不会带有标记。之后按标记清除时不会移除该条目,但按 URL 清除可以。
如需确保每次写入都保留标记,请在首次存储响应时将标记复制到自定义标头中。然后在每次调用 put() 之前,从该标头恢复 Cache-Tag。
:::
-
request字符串 | Request- 用作键的字符串或
Request对象。如果传入字符串,则将其解释为新建 Request 对象的 URL。
- 用作键的字符串或
-
responseResponse- 要在给定键下存储的
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字符串 | 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标头。
- 如果找到带有 Content-Length 标头的匹配响应,则返回
-
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字符串 | Request- 用作查找键的字符串或
Request对象。字符串会被解释为新建Request对象的 URL。
- 用作查找键的字符串或
-
options对象- 可包含一个属性:
ignoreMethod(Boolean)。无论实际值如何,都将请求方法视为 GET。
- 可包含一个属性: