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

缓存键

最后更新 查看 MarkdownAgent 设置

Cache Key 是 Cloudflare 用于缓存中文件的标识符,Cache Key Template 定义给定 HTTP 请求的标识符。

默认缓存键包括:

  1. 完整 URL:
    • scheme(协议)- 可以是 HTTP 或 HTTPS。
    • host(主机)- 例如 www.cloudflare.com
    • 带查询字符串的 URI - 例如 /logo.jpg?utm_source=newsletter
  2. 客户端发送的 Origin 标头(用于 CORS 支持)。
  3. x-http-method-override、x-http-method 和 x-method-override 标头。
  4. x-forwarded-host、x-host、x-forwarded-scheme(除 http 或 https 外)、x-original-url、x-rewrite-url 和 forwarded 标头。

创建自定义缓存键

自定义缓存键让您能够精确设置任何资源的缓存性设置。虽然它们提供了更多控制,但可能会降低缓存命中率并导致缓存分片:

  1. 在 Cloudflare 仪表板中,转到 Cache Rules(缓存规则) 页面。

    前往 Cache Rules(缓存规则) ↗
  2. 选择 Create rule(创建规则)。

  3. 在 When incoming requests match(当传入请求匹配时) 下,定义规则表达式。

  4. 在 Then(则) 下,在 Cache eligibility(缓存资格) 部分,选择 Eligible for cache(符合缓存条件)。

  5. 将 Cache Key(缓存键) 设置添加到规则,并选择适当的 Query String(查询字符串) 设置。

  6. 您还可以选择 Headers(标头)、Cookie、Host(主机) 和 User(用户) 的设置。

  7. 要保存并部署规则,选择 Deploy(部署)。如果您尚未准备好部署,请选择 Save as Draft(另存为草稿)。

缓存键模板(Cache Key Template)

更改 Cache Key Template 有几个常见原因:

  • 拆分缓存,使一个 URL 存储在多个文件中。例如,可以根据 URL 中的特定查询字符串存储不同文件。
  • 合并缓存,使不同的 HTTP 请求存储在同一个文件中。例如,移除 Cloudflare 默认添加到缓存键的 Origin 标头。

SSL 设置对缓存行为的影响

Cloudflare 的 $scheme 变量在缓存行为中起着关键作用,但其含义因缓存键类型而异:

  • 默认缓存键:$scheme 指的是源站协议——Cloudflare 用于连接到源站服务器的协议(HTTP 或 HTTPS)。在此配置中,更改 SSL 设置(例如从 Flexible 切换到 Full)会改变源站协议。由于缓存键包含源站协议,此类更改会触发缓存清除,要求 Cloudflare 再次从源站获取内容。

  • 自定义缓存键:$scheme 指的是访问者协议——客户端向 Cloudflare 发出请求时使用的协议。在这种情况下,SSL 设置更改不会影响缓存键,除非在自定义配置中明确包含了源站协议。

例如,使用 Flexible SSL 时,Cloudflare 始终通过 HTTP 连接到源站,无论访问者使用 HTTP 还是 HTTPS。这在默认配置下导致两种协议使用相同的缓存键。

请注意,使用默认缓存键时,SSL 设置的更改可能导致缓存失效:

  • 从 Off(关闭) 切换到 Full(完全)、Full (strict)(完全(严格)) 或 Strict(严格) 会将源站协议从 HTTP 更新为 HTTPS,触发缓存清除。

  • 从 Flexible(灵活) 切换到 Full(完全)、Full (strict)(完全(严格)) 或 Strict(严格) 同样会将源站协议更改为 HTTPS 并导致缓存清除。

在修改 SSL 模式以避免意外缓存行为时,了解 $scheme 与缓存配置的交互方式至关重要。

缓存级别:忽略查询字符串

缓存级别设置为 Ignore Query String 时,创建的缓存键包含默认缓存键的所有元素,但不再包含 URI 中的查询字符串。例如,http://example.com/file.jpg?something=123 的请求和 http://example.com/file.jpg?something=789 的请求将具有相同的缓存键。

缓存键设置

以下字段控制 Cache Key Template。

查询字符串(Query String)

查询字符串控制哪些 URL 查询字符串参数进入缓存键。您可以使用相应字段 include(包含)或 exclude(排除)特定的查询字符串参数。当您包含一个查询字符串参数时,该查询字符串参数的 value(值)会用于缓存键。

示例

如果您在类似 https://www.example.com/?foo=bar 的 URL 中包含查询字符串 foo,则 bar 会出现在 Cache Key 中。应提供 include 或 exclude 之一。

使用说明

  • 若要包含所有查询字符串参数(默认行为),请使用 include: "\*"
  • 若要忽略查询字符串,请使用 exclude: "\*"
  • 要包含大多数查询字符串参数但排除少数几个,请使用 exclude 字段,该字段假定其他查询字符串参数已包含在内。

标头(Headers)

标头控制哪些标头进入缓存键。与查询字符串类似,您可以包含特定标头或排除默认标头。

当您包含标头时,标头值会包含在 Cache Key 中。例如,如果 HTTP 请求包含 X-Auth-API-key: 12345 这样的 HTTP 标头,且您在 Cache Key Template 中包含 X-Auth-API-Key header,则 12345 会出现在 Cache Key 中。

在 Include headers and selected values(包含标头和所选值) 部分,您可以将标头名称及其值添加到缓存键中。对于自定义标头,值是可选的,但对于以下受限标头,您必须包含一到 10 个特定值:

  • accept
  • accept-charset
  • accept-encoding
  • accept-datetime
  • accept-language
  • referer
  • user-agent

要检查标头的存在而不包含其实际值,请使用 Check presence of(检查存在性) 选项。

目前,您只能排除 Origin 标头。除非明确排除,否则 Origin 标头始终包含在内。在缓存键中包含 Origin 标头 ↗ 对于强制执行 CORS ↗ 很重要。

此外,您不能包含以下标头:

  • 重新实现缓存或代理功能的标头
    • connection
    • content-length
    • cache-control
    • if-match
    • if-modified-since
    • if-none-match
    • if-unmodified-since
    • range
    • upgrade
  • 其他缓存键功能已涵盖的标头
    • cookie
    • host
  • 特定于 Cloudflare 且以 cf- 为前缀的标头,例如 cf-ray
  • 自定义缓存键模板中已包含的标头,例如 origin

主机(Host)

Host 决定在缓存键中包含哪个 host 标头。

  • 如果 Use original host(API 中为 resolved: false),Cloudflare 在发送给源站的 HTTP 请求中包含 Host 标头。
  • 如果 Resolved host(API 中为 resolved: true),Cloudflare 包含为请求解析得到 origin IP 所使用的 Host 标头。如果已通过 Origin Rule 更改了标头,该 Host 标头可能与实际发送的标头不同。

与 query_string 或 header 类似,cookie 控制哪些 Cookie 出现在缓存键中。您可以包含 Cookie 值或检查特定 Cookie 的存在性。

使用说明

您不能包含特定于 Cloudflare 的 Cookie。Cloudflare Cookie 以 __cf 为前缀,例如 __cflb。

用户特征(User features)

User feature 字段将关于终端用户(客户端)的特征添加到缓存键中。

  • device_type 根据 User Agent 将请求分类为 mobile(移动设备)、desktop(桌面设备)或 tablet(平板电脑)
  • geo 包含客户端的国家/地区,由 IP 地址推导
  • lang 包含客户端发送的 Accept-Language 标头中的第一个语言代码

可用性

缓存键选项的可用性因方案而异。

免费版 专业版 (Pro) 商业版 (Business) Enterprise
缓存欺骗防护 是 是 是 是
按设备类型缓存 是 是 是 是
忽略查询字符串 是 是 是 是
查询字符串排序 是 是 是 是
查询字符串 否 否 否 是
标头 否 否 否 是
Cookie 否 否 否 是
主机 否 否 否 是
用户功能 否 否 否 是

故障排除

你可以使用 Rules simulator 查找应用于请求的 Cache Key 设置。通过 Rules simulator 发送请求时,如果请求由缓存提供服务,Cache Parameters 部分会显示缓存命中。然后选择 View parameter detail,查看实际使用的 Cache Key 属性。

限制

Prefetch 功能与自定义缓存键不兼容。使用 Cache Rules 时,自定义缓存键用于缓存所有资源。但是,Prefetch 始终使用默认缓存键,这导致键不匹配。

这篇文档对您有帮助吗?