Cache

Background

Cache API 在 Cloudflare 上实现细粒度缓存读写

The Cache API allows fine grained control of reading and writing from the Cloudflare global network cache.The Cache API allows fine grained control of reading and writing from the Cloudflare global network cache.Cache API 允许细粒度控制 Cloudflare 缓存 它提供对全球网络缓存的编程式读写访问Cache API 允许细粒度控制 Cloudflare 缓存Cache API

The Cache API is available globally but the contents of the cache do not replicate outside of the originating data center. A GET /users response can be cached in the originating data center, but will not exist in another data center unless it has been explicitly created.The Cache API is available globally but the contents of the cache do not replicate outside of the originating data center. A GET /users response can be cached in the originating data center, but will not exist in another data center unless it has been explicitly created.缓存内容不会跨数据中心复制 在一个数据中心缓存的响应不会出现在另一个数据中心，除非在那里显式创建缓存内容不会跨数据中心复制缓存内容

Workers deployed to custom domains have access to functional cache operations. So do Pages functions, whether attached to custom domains or *.pages.dev domains.Workers deployed to custom domains have access to functional cache operations. So do Pages functions, whether attached to custom domains or *.pages.dev domains.自定义域上的 Worker 和 Pages 函数可访问缓存 这包括绑定自定义域或 *.pages.dev 域的 Pages 函数自定义域上的 Worker 和 Pages 函数可访问缓存自定义域

However, any Cache API operations in the Cloudflare Workers dashboard editor and Playground previews will have no impact. For Workers fronted by Cloudflare Access, the Cache API is not currently available.However, any Cache API operations in the Cloudflare Workers dashboard editor and Playground previews will have no impact. For Workers fronted by Cloudflare Access, the Cache API is not currently available.仪表板编辑器和 Playground 预览中的缓存操作无效 此外，由 Cloudflare Access 保护的 Worker 目前无法使用 Cache API仪表板编辑器和 Playground 预览中的缓存操作无效缓存操作

Accessing Cache

通过 caches.default 或 caches.open 访问全局缓存

The caches.default API is strongly influenced by the web browsers’ Cache API, but there are some important differences. For instance, Cloudflare Workers runtime exposes a single global cache object.The caches.default API is strongly influenced by the web browsers’ Cache API, but there are some important differences. For instance, Cloudflare Workers runtime exposes a single global cache object.caches.default 在 Worker 中提供单一全局缓存对象 它类似浏览器 Cache API 但有差异，尤其是只暴露一个全局缓存caches.default 在 Worker 中提供单一全局缓存对象caches.default

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

You may create and manage additional Cache instances via the caches.open method.You may create and manage additional Cache instances via the caches.open method.通过 caches.open 创建额外的 Cache 实例 这样可以管理默认缓存之外的额外命名缓存通过 caches.open 创建额外的 Cache 实例caches.open

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

Headers

Cache API 遵循 Cache-Control、Cache-Tag、ETag、Expires、Last-Modified

Our implementation of the Cache API respects the following HTTP headers on the response passed to put():Our implementation of the Cache API respects the following HTTP headers on the response passed to put():Cache API 在 put 时遵循特定的 HTTP 响应头 所列头控制缓存指令和验证Cache API 在 put 时遵循特定的 HTTP 响应头HTTP 响应头

• Cache-Control
  • Controls caching directives. This is consistent with Cloudflare Cache-Control Directives. Refer to Edge TTL for a list of HTTP response codes and their TTL when Cache-Control directives are not present.
    Controls caching directives. … Refer to Edge TTL for a list of HTTP response codes and their TTL when Cache-Control directives are not present.
    Cache-Control 按 Cloudflare 规则控制缓存指令 当指令缺失时，Edge TTL 定义各响应代码的 TTL
    Cache-Control 按 Cloudflare 规则控制缓存指令
    Cache-Control
• Cache-Tag
  • Allows resource purging by tag(s) later.
    Allows resource purging by tag(s) later.
    Cache-Tag 允许日后按标签清除资源 带有标签的资源可以被有选择地清除
    Cache-Tag 允许日后按标签清除资源
    Cache-Tag
• ETag
  • Allows cache.match() to evaluate conditional requests with If-None-Match.
    Allows cache.match() to evaluate conditional requests with If-None-Match.
    ETag 使 cache.match 能处理条件请求 它用于评估 If-None-Match 头
    ETag 使 cache.match 能处理条件请求
    ETag
• Expires string
  • A string that specifies when the resource becomes invalid.
    A string that specifies when the resource becomes invalid.
    Expires 指定资源何时失效 它控制缓存资源的过期时间
    Expires 指定资源何时失效
    Expires
• Last-Modified
  • Allows cache.match() to evaluate conditional requests with If-Modified-Since.
    Allows cache.match() to evaluate conditional requests with If-Modified-Since.
    Last-Modified 使 cache.match 能处理条件请求 它用于评估 If-Modified-Since 头
    Last-Modified 使 cache.match 能处理条件请求
    Last-Modified

This differs from the web browser Cache API as they do not honor any headers on the request or response.This differs from the web browser Cache API as they do not honor any headers on the request or response.Cache API 遵循头，与浏览器 Cache API 不同 浏览器 Cache API 不遵循请求或响应头Cache API 遵循头，与浏览器 Cache API 不同浏览器 Cache API

Methods

Put

cache.put 以请求为键存储响应，返回 undefined

cache.put(request, response);

• put(request, response) : Promise

  • Attempts to add a response to the cache, using the given request as the key. Returns a promise that resolves to undefined regardless of whether the cache successfully stored the response.
    Attempts to add a response to the cache, using the given request as the key. Returns a promise that resolves to undefined regardless of whether the cache successfully stored the response.
    put 将响应加入缓存并解析为 undefined 它以请求为键，无论存储是否成功都返回 undefined
    put 将响应加入缓存并解析为 undefined
    put

Parameters

put 接收请求键和要存储的响应

• request string | Request

  • Either a string or a Request object to serve as the key. If a string is passed, it is interpreted as the URL for a new Request object.
    Either a string or a Request object to serve as the key. If a string is passed, it is interpreted as the URL for a new Request object.
    put 的 request 参数接受字符串或 Request 对象 字符串会被解释为新 Request 对象的 URL
    put 的 request 参数接受字符串或 Request 对象
    request

• response Response

  • A Response object to store under the given key.
    A Response object to store under the given key.
    put 的 response 参数是要存储的 Response 对象 它被存储在提供的请求键下
    put 的 response 参数是要存储的 Response 对象
    Response

Invalid parameters

put 拒绝非 GET 请求、206 响应和 Vary: *

cache.put will throw an error if:cache.put will throw an error if:cache.put 在特定条件下抛出错误 后续列表详细说明了抛出错误的情况cache.put 在特定条件下抛出错误cache.put

• The request passed is a method other than GET.
  The request passed is a method other than GET.
  若请求方法不是 GET，cache.put 抛出错误 只有 GET 请求可作为缓存键
  若请求方法不是 GET，cache.put 抛出错误
  cache.put
• The response passed has a status of 206 Partial Content.
  The response passed has a status of 206 Partial Content.
  cache.put 对 206 Partial Content 响应抛出错误 状态为 206 的响应不能被缓存
  cache.put 对 206 Partial Content 响应抛出错误
  cache.put
• The response passed contains the header Vary: *. The value of the Vary header is an asterisk (*). Refer to the Cache API specification for more information.
  The response passed contains the header Vary: *. The value of the Vary header is an asterisk (*).
  若响应含有 Vary: *，cache.put 抛出错误 Vary 头值为星号（*）是不允许的
  若响应含有 Vary: *，cache.put 抛出错误
  Vary: *

Errors

put 对不可缓存或过大的响应返回 413

cache.put returns a 413 error if Cache-Control instructs not to cache or if the response is too large.cache.put returns a 413 error if Cache-Control instructs not to cache or if the response is too large.若不可缓存或过大，cache.put 返回 413 当 Cache-Control 禁止缓存或响应超过大小限制时会发生若不可缓存或过大，cache.put 返回 413cache.put

Match

cache.match 返回与请求键匹配的缓存响应

cache.match(request, options);

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

  • Returns a promise wrapping the response object keyed to that request.
    Returns a promise wrapping the response object keyed to that request.
    match 返回包裹缓存响应的 promise 该响应以给定请求为键
    match 返回包裹缓存响应的 promise
    match

Parameters

match 接收请求键和 ignoreMethod 选项

• request string | Request

  • The string or Request object used as the lookup key. Strings are interpreted as the URL for a new Request object.
    The string or Request object used as the lookup key. Strings are interpreted as the URL for a new Request object.
    match 的 request 参数接受字符串或 Request 对象 字符串会被解释为新 Request 对象的 URL
    match 的 request 参数接受字符串或 Request 对象
    request

• options

  • Can contain one possible property: ignoreMethod (Boolean). When true, the request is considered to be a GET request regardless of its actual value.
    Can contain one possible property: ignoreMethod (Boolean). When true, the request is considered to be a GET request regardless of its actual value.
    match 选项包含 ignoreMethod 布尔值 为 true 时，请求无论实际方法如何都被视为 GET
    match 选项包含 ignoreMethod 布尔值
    ignoreMethod

Unlike the browser Cache API, Cloudflare Workers do not support the ignoreSearch or ignoreVary options on match(). You can accomplish this behavior by removing query strings or HTTP headers at put() time.Unlike the browser Cache API, Cloudflare Workers do not support the ignoreSearch or ignoreVary options on match(). You can accomplish this behavior by removing query strings or HTTP headers at put() time.match 不支持 ignoreSearch 和 ignoreVary 选项 要达到等效行为，需在 put 时移除查询字符串或 HTTP 头match 不支持 ignoreSearch 和 ignoreVary 选项ignoreSearch

Our implementation of the Cache API respects the following HTTP headers on the request passed to match():Our implementation of the Cache API respects the following HTTP headers on the request passed to match():Cache API 在 match 时遵循特定的 HTTP 请求头 所列头影响范围请求和条件请求Cache API 在 match 时遵循特定的 HTTP 请求头HTTP 请求头

• Range

  • Results in a 206 response if a matching response with a Content-Length header is found. Your Cloudflare cache always respects range requests, even if an Accept-Ranges header is on the response.
    Results in a 206 response if a matching response with a Content-Length header is found. Your Cloudflare cache always respects range requests, even if an Accept-Ranges header is on the response.
    若匹配响应有 Content-Length，Range 头产生 206 Cloudflare 缓存始终遵循范围请求，即使存在 Accept-Ranges 头
    若匹配响应有 Content-Length，Range 头产生 206
    Range

• If-Modified-Since

  • Results in a 304 response if a matching response is found with a Last-Modified header with a value before the time specified in If-Modified-Since.
    Results in a 304 response if a matching response is found with a Last-Modified header with a value before the time specified in If-Modified-Since.
    若 Last-Modified 早于指定时间，If-Modified-Since 产生 304 这启用了基于修改时间的条件请求
    若 Last-Modified 早于指定时间，If-Modified-Since 产生 304
    If-Modified-Since

• If-None-Match

  • Results in a 304 response if a matching response is found with an ETag header with a value that matches a value in If-None-Match.
    Results in a 304 response if a matching response is found with an ETag header with a value that matches a value in If-None-Match.
    若 ETag 匹配，If-None-Match 产生 304 这启用了基于实体标签的条件请求
    若 ETag 匹配，If-None-Match 产生 304
    If-None-Match

Errors

match 在内容缺失时返回 undefined；日志显示 504

cache.match generates a 504 error response when the requested content is missing or expired. The Cache API does not expose this 504 directly to the Worker script, instead returning undefined. Nevertheless, the underlying 504 is still visible in Cloudflare Logs.cache.match generates a 504 error response when the requested content is missing or expired. The Cache API does not expose this 504 directly to the Worker script, instead returning undefined. Nevertheless, the underlying 504 is still visible in Cloudflare Logs.cache.match 在内容缺失或过期时返回 undefined，日志显示 504 底层 504 不暴露给 Worker，但仍可在 Cloudflare Logs 中看到cache.match 在内容缺失或过期时返回 undefined，日志显示 504cache.match

If you use Cloudflare Logs, you may see these 504 responses with the RequestSource of edgeWorkerCacheAPI. Again, these are expected if the cached asset was missing or expired. Note that edgeWorkerCacheAPI requests are already filtered out in other views, such as Cache Analytics. To filter out these requests or to filter requests by end users of your website only, refer to Filter end users.If you use Cloudflare Logs, you may see these 504 responses with the RequestSource of edgeWorkerCacheAPI. Again, these are expected if the cached asset was missing or expired. Note that edgeWorkerCacheAPI requests are already filtered out in other views, such as Cache Analytics.日志中 RequestSource 为 edgeWorkerCacheAPI 的 504 响应是预期的 这些表示缓存资产缺失或过期，在 Cache Analytics 中已被过滤掉日志中 RequestSource 为 edgeWorkerCacheAPI 的 504 响应是预期的edgeWorkerCacheAPI

Delete

cache.delete 删除缓存响应并返回布尔值

cache.delete(request, options);

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

Deletes the Response object from the cache and returns a Promise for a Boolean response:Deletes the Response object from the cache and returns a Promise for a Boolean response:delete 从缓存删除响应，返回布尔 promise 删除时解析为 true，不存在时解析为 falsedelete 从缓存删除响应，返回布尔 promisedelete

• true: The response was cached but is now deleted
  true: The response was cached but is now deleted
  缓存响应被删除时 delete 返回 true 这表示响应存在并已被移除
  缓存响应被删除时 delete 返回 true
  delete
• false: The response was not in the cache at the time of deletion.
  false: The response was not in the cache at the time of deletion.
  响应未缓存时 delete 返回 false 这表示删除时响应不存在
  响应未缓存时 delete 返回 false
  delete

Parameters

delete 接收请求键和 ignoreMethod 选项

• request string | Request

  • The string or Request object used as the lookup key. Strings are interpreted as the URL for a new Request object.
    The string or Request object used as the lookup key. Strings are interpreted as the URL for a new Request object.
    delete 的 request 参数接受字符串或 Request 对象 字符串会被解释为新 Request 对象的 URL
    delete 的 request 参数接受字符串或 Request 对象
    request

• options object

  • Can contain one possible property: ignoreMethod (Boolean). Consider the request method a GET regardless of its actual value.
    Can contain one possible property: ignoreMethod (Boolean). Consider the request method a GET regardless of its actual value.
    delete 选项包含 ignoreMethod 布尔值 为 true 时，请求无论实际方法如何都被视为 GET
    delete 选项包含 ignoreMethod 布尔值
    ignoreMethod

Related resources

链接到缓存内部机制和使用示例

• How the cache works
• Example: Cache using fetch()
• Example: using the Cache API
• Example: caching POST requests