缓存键

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（缓存规则） 页面。

   Go to 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 有几个常见原因：

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

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。

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

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

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

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

当您包含标头时，标头值会包含在 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 标头。

• 如果 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 feature 字段将关于终端用户（客户端）的特征添加到缓存键中。

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

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

您可以使用 Cloudflare Trace 查找应用于请求的缓存键设置。通过 Trace 工具发送请求时，如果请求从缓存提供，**Cache Parameters（缓存参数）**部分会显示 cache hit。然后选择 **View parameter detail（查看参数详情）**查看使用了哪些缓存键属性。

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