边缘安全加速平台 EO Cache

Cache 基于 Web APIs 标准 Cache API 进行设计。边缘函数运行时会在全局注入 caches 对象，该对象提供了一组缓存操作接口。
说明：
缓存的内容仅在当前数据节点有效，不会自动复制到其他数据节点。
缓存空间
Cache API 涉及两类相互隔离的缓存空间：EdgeOne 站点缓存与边缘函数独立缓存，通过是否使用 default 命名空间与 Request 是否携带 eo.cacheKey 区分。
缓存空间
判断条件
写入方
函数内可用操作
EdgeOne 站点缓存
使用 default 命名空间，且 Request 未携带 eo.cacheKey
EdgeOne 按站点缓存规则写入
仅 cache.match
边缘函数独立缓存
使用非 default 命名空间，或 Request 携带 eo.cacheKey
函数内 cache.put 写入
cache.match / cache.put / cache.delete
两类缓存相互隔离：边缘函数独立缓存的缓存操作不会命中 EdgeOne 站点缓存；
写入与删除仅支持边缘函数独立缓存：使用 default 命名空间且未携带 eo.cacheKey 时，会被拒绝并抛出 forbidden cdn cache 错误；
使用 string 类型参数时，边缘函数运行时将其作为 URL 构造 GET 类型的 Request，该 Request 不携带 eo.cacheKey：在 default 命名空间下，读、写、删均属于 EdgeOne 站点缓存空间，即只能读取站点缓存，写入、删除同样会被拒绝；如需在函数内读写缓存，请改为使用 Request 对象指定 eo.cacheKey，或使用非 default 命名空间；
建议：如需在边缘函数中读写缓存，统一使用边缘函数独立缓存（指定 eo.cacheKey 或使用非 default 命名空间均可）：读取、写入、删除使用同一个 Request 对象，形成读写闭环；站点资源的缓存仍由站点缓存规则控制。
eo.cacheKey 通过 cache.match、cache.put、cache.delete 的第一个参数（request）携带：使用 Request 对象构造，例如 new Request(url, { eo: { cacheKey: 'xxx' } })（详见 RequestInitEoProperties）；
边缘函数独立缓存的缓存键由命名空间、Request 的 URL 与 eo.cacheKey 共同组成：三者均相同时对应同一份缓存，任一不同即相互隔离。
示例
addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event));
});
﻿
async function fetchOrigin(event, cache, cacheKey) {
  const response = await fetch(event.request);
  response.headers.set('Cache-Control', 's-maxage=60');
  event.waitUntil(cache.put(cacheKey, response.clone()));
  return response;
}
﻿
async function handleRequest(event) {
  const cache = caches.default;
﻿
  // 读、写、删使用同一个指定了 eo.cacheKey 的 Request 对象
  const cacheKey = new Request(event.request.url, {
    eo: { cacheKey: 'page-home-v1' },
  });
﻿
  try {
    let response = await cache.match(cacheKey);
    if (!response) {
      response = await fetchOrigin(event, cache, cacheKey);
    }
    return response;
  } catch (error) {
    // 缓存过期（504）等异常：删除旧缓存后重新回源并写入
    try {
      await cache.delete(cacheKey);
    } catch (e) {}
    return fetchOrigin(event, cache, cacheKey);
  }
}
构造函数
使用 caches.default 可以获取默认的 cache 实例。
// 获取默认 cache 实例
const cache = caches.default;
﻿
// 效果等同于 caches.default
await caches.open('default');
使用 caches.open 创建指定命名空间的 cache 实例。
// 创建指定命名空间的 cache 实例
const cache = await caches.open(namespace); 
参数
caches.open(namespace) 方法参数说明如下。
参数名称
类型
必填
说明
namespace
string
是
缓存命名空间。        
如果该值为 "default" 则表示默认实例，也可直接使用 caches.default 获取默认实例。
使用非 default 命名空间创建的实例，其缓存操作均在边缘函数独立缓存中进行，不会命中 EdgeOne 站点缓存，区别详见 缓存空间。
实例方法
match
cache.match(request: Request | string, options?: MatchOptions): Promise<Response | undefined>
获取 request 关联的缓存 Response 对象。返回一个 Promise 对象。如果缓存存在，则包含 Response 对象，反之包含 undefined。
注意
cache.match 内部不会主动回源，缓存过期则会抛出 504 错误。
如需匹配 EdgeOne 站点缓存（例如在函数中判断某资源是否已被缓存），建议使用以目标资源 URL 新建的 Request 对象进行匹配，例如 cache.match(new Request('https://example.com/a.html'))；直接传入客户端请求对象（如 event.request）可能因携带额外的请求头而无法命中。
参数
参数名称
类型
必填
说明
request
﻿Request | string
是
缓存请求对象。
request 只支持 GET 方法，当类型为 string 时，将被作为 URL 构造 Request 对象。
读取的缓存空间：使用 default 命名空间，且 request 未携带 eo.cacheKey 时，读取的是 EdgeOne 站点缓存；使用非 default 命名空间，或 request 携带 eo.cacheKey 时，读取的是边缘函数独立缓存，区别详见缓存空间。建议：读取边缘函数独立缓存时，与 cache.put、cache.delete 使用同一个 Request 对象。
request 包含 Range 头部时，如果缓存的 Response 能够支持 Range 范围处理，返回 206 响应。
request 包含 If-Modified-Since 头部时，如果缓存的 Response 存在 Last-Modified 头部，且 Last-Modified 与 If-Modified-Since 相等，返回 304 响应。
request 包含 If-None-Match 头部时，如果缓存的 Response 存在 ETag 头部，且 ETag 与 If-None-Match 相等, 返回 304 响应。
options
﻿MatchOptions﻿
否
配置选项。
MatchOptions
属性名
类型
示例值
说明
ignoreMethod
boolean
true
是否忽略 Request 的 method。为 true 时，会忽略 Request 原来的 method，作为 GET 处理。
put
cache.put(request: Request | string, response: Response): Promise<void>
尝试使用给定的 request 作为缓存 key，将 response 写入边缘函数独立缓存。写入成功时返回 Promise<undefined> 对象；使用 default 命名空间且未携带 eo.cacheKey 时，写入会被拒绝，详见下方参数。
注意：
 当参数 response 对象的 Cache-Control 头部表示不缓存时，抛出 413 错误。 
参数
参数名称
类型
必填
说明
request
﻿Request | string
是
缓存请求对象。                
request 只支持 GET 方法，当类型为 string 时，将被作为 URL 构造 Request 对象。
使用 default 命名空间且未携带 eo.cacheKey 时，写入目标为 EdgeOne 站点缓存，会被拒绝并抛出 forbidden cdn cache 错误；否则写入对象为边缘函数独立缓存，其它区别详见缓存空间。
response
﻿Response﻿
是
缓存内容，说明如下。
Cache-Control
支持 s-maxage、max-age、no-store、no-cache、private；其中 no-store、no-cache、private 均表示不缓存，cache.put 将返回 413 错误。          
Pragma
当 Cache-Control 未设置，并且 Pragma 为 no-cache。此时表示不缓存。          
ETag
当 cache.match 参数 request 包含 If-None-Match 头部时，可关联 ETag 使用。          
Last-Modified
当 cache.match 参数 request 包含 If-Modified-Since 头部时，可关联 Last-Modified 使用。          
416 Range Not Satisfiable
当参数 response 对象为 416 Range Not Satisfiable 时，暂不缓存。      
参数限制
cache.put 使用以下的参数值，将抛出参数错误：
参数 request 为 GET 方法之外的其他方法.
参数 response 状态码为 206 Partial Content。 
参数 response 包含 Vary: *头部。
delete
cache.delete(request: Request | string, options?: DeleteOptions): Promise<boolean>
删除 request 关联的缓存 response。未发生网络错误时, 总返回 Promise，并包含 true，反之包含 false。
参数
参数名称
类型
必填
说明
request
﻿Request | string
是
缓存请求对象。                
request 只支持 GET 方法，当类型为 string 时，将被作为 URL 构造 Request 对象。
使用 default 命名空间且未携带 eo.cacheKey 时，删除目标为 EdgeOne 站点缓存，会被拒绝并抛出 forbidden cdn cache 错误；否则删除对象为边缘函数独立缓存，其它区别详见缓存空间。            
options
﻿DeleteOptions﻿
否
配置选项。
DeleteOptions
属性名
类型
示例值
说明
ignoreMethod
boolean
true
是否忽略 request 的方法名。为 true 时，会忽略 Request 原来的方法，作为 GET 处理。
相关参考
﻿MDN 官方文档：Cache﻿
﻿示例函数：缓存 POST 请求﻿
﻿示例函数：Cache API 使用﻿
﻿

缓存空间	判断条件	写入方	函数内可用操作
EdgeOne 站点缓存	使用 `default` 命名空间，且 Request 未携带 `eo.cacheKey`	EdgeOne 按站点缓存规则写入	仅 `cache.match`
边缘函数独立缓存	使用非 `default` 命名空间，或 Request 携带 `eo.cacheKey`	函数内 `cache.put` 写入	`cache.match` / `cache.put` / `cache.delete`

参数名称	类型	必填	说明
namespace	string	是	缓存命名空间。如果该值为 `"default"` 则表示默认实例，也可直接使用 `caches.default` 获取默认实例。使用非 default 命名空间创建的实例，其缓存操作均在边缘函数独立缓存中进行，不会命中 EdgeOne 站点缓存，区别详见缓存空间。

属性名	类型	示例值	说明
ignoreMethod	boolean	true	是否忽略 Request 的 method。为 true 时，会忽略 Request 原来的 method，作为 GET 处理。

Cache

本页目录：

缓存空间

示例

构造函数

参数

实例方法

match

参数

MatchOptions

put

参数

参数限制

delete

参数

DeleteOptions

相关参考