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

使缓存内容失效

最后更新 查看 MarkdownAgent 设置

失效会将缓存内容标记为过期 (stale)。在下一次请求时,Cloudflare 会向您的源站重新验证该内容。如果源站响应 304 Not Modified,Cloudflare 会重用缓存内容,而不是再次下载。

失效有时也称为软清除 (soft purge)。

在清除与失效之间选择

清除和失效接受相同的选择器:URL、缓存标签、主机名、URL 前缀或全部内容。它们的区别在于对匹配内容的处理:

行为 清除 失效
缓存内容 被移除 保留并标记为过期 (stale)
下一次请求 从源站获取完整响应 向源站重新验证
过期内容 不会被提供 可在重新验证期间或源站失败时提供
API 端点 purge_cache invalidate_cache

当缓存内容不得再次被提供时,请使用清除。清除前请先在源站更新或移除该内容。否则,下一次请求可能会再次缓存旧版本。

当内容可能尚未更改时(例如共享同一缓存标签的一组资源),请使用失效来刷新内容。

失效如何工作

失效不会提前获取新内容。相反,下一次针对已失效内容的请求会触发重新验证。

为了重新验证,Cloudflare 会向源站发送条件请求。该请求使用源站随内容一起发送的 ETag 或 Last-Modified 标头。源站的响应决定接下来会发生什么:

  • 如果源站响应 304 Not Modified,Cloudflare 会重用缓存内容并设置新的生存时间 (TTL)。
  • 如果源站返回新的可缓存内容,Cloudflare 会替换缓存内容。
  • 如果源站返回 5xx 错误或无法访问,Cloudflare 可以提供过期的缓存内容。详情请参阅重新验证期间的过期内容。

失效并不保证内容会被重用。如果内容已不在缓存中、源站未发送上述任一标头,或源站不支持条件请求,Cloudflare 会获取完整响应。

304 Not Modified 响应不会刷新由 Cache Response Rules 设置的缓存标签。仅当源站在 304 响应中包含 Cache-Tag 标头时,才会更新来自源站 Cache-Tag 标头的缓存标签。否则要刷新缓存标签,请清除该内容。

重新验证期间的过期内容

您的缓存设置以及源站的健康状况决定访客在 Cloudflare 重新验证时是否会收到过期内容:

  • 使用 stale-while-revalidate 时,Cloudflare 可以在后台重新验证的同时提供过期内容。
  • 没有 stale-while-revalidate 时,请求会等待重新验证完成。
  • 如果源站返回 5xx 错误或无法访问,只要内容仍在缓存中,Cloudflare 就可以提供过期内容。即使响应没有 stale-if-error 指令也会如此。要限制此行为,请在响应中设置 stale-if-error。要阻止此行为,请设置 stale-if-error=0。启用 Origin Cache Control 时,must-revalidate、proxy-revalidate 和 s-maxage 也会阻止此行为。

对于仍新鲜的内容,stale-while-revalidate 和 stale-if-error 窗口从您使其失效时开始,而不是从它原本会过期时开始。失效绝不会延长已经结束的过期窗口。

例如,假设您在过期前使具有以下标头的缓存响应失效:

Cache-Control: public, max-age=3600, stale-while-revalidate=30
ETag: "product-v1"

Cloudflare 可以在失效后最多 30 秒内提供此过期响应,同时进行重新验证。该响应没有 stale-if-error 指令。如果源站返回 5xx 错误或无法访问,Cloudflare 可以在这 30 秒之后继续提供该过期响应,直到响应离开缓存。

其他指令和 Cache Rules 设置可以阻止 Cloudflare 在重新验证时提供过期内容。详情请参阅重新验证。

Cache Reserve

失效会将匹配内容保留在 Cache Reserve 中,并继续产生存储费用。如果源站响应 304 Not Modified,Cloudflare 会重用已存储的内容,而不是再次从源站获取。即使设置了 stale-while-revalidate,从 Cache Reserve 提供的内容在重新验证时也不会以过期状态提供。

与清除相比,失效会减少源站出站流量,但不会减少 Cache Reserve 操作。在 304 响应后更新已存储内容属于 Class A 操作。按 URL 失效也会在发送请求时更新已存储内容,这同样是 Class A 操作。详情请参阅 Cache Reserve 操作。

清除会强制匹配的 Cache Reserve 内容发生缓存未命中。详情请参阅 Cache Reserve 清除行为。

Workers Cache

从仪表板或 invalidate_cache 端点进行的失效不会影响 Workers Cache。Workers Cache 属于您的 Worker,而不属于您的 zone。要从 Worker 的缓存中移除响应,请从该 Worker 调用 ctx.cache.purge()。

开始之前

在使内容失效之前,请检查以下要求:

  • 源站验证器:要重用缓存内容,源站必须返回 ETag 或 Last-Modified 标头,并支持条件请求。
  • 权限:对于 API 请求,请使用对该 zone 具有 Cache Purge 权限的令牌。要从仪表板进行失效,您的角色必须包含相同权限。
  • 速率限制:失效请求会计入账户的清除限制。详情请参阅限制。

使用仪表板进行失效

  1. 在 Cloudflare 仪表板中,前往 Configuration(配置) 页面。

    前往 Configuration(配置) ↗
  2. 如果您的 zone 使用 Version Management,请选择 Global(全局) 选项卡。然后在 Invalidate Cache(使缓存失效) 中,在 Choose the environment(选择环境) 下选择环境。仪表板会预选一个环境,因此请在继续前检查所选内容。

  3. 在 Invalidate Cache(使缓存失效) 中,选择 Custom Invalidation(自定义失效)。如果您的 zone 使用 Version Management,此按钮的标签为 Select Content(选择内容)。

  4. 在 Select content by(按以下方式选择内容) 下,选择 URL、Hostname、Tag 或 Prefix,并输入要失效的值。

  5. 选择 Invalidate(失效)。

要使所有缓存内容失效,请选择 Invalidate Everything(使全部失效),然后确认。

如果您的 zone 使用 Version Management,则无法使用 Invalidate Everything(使全部失效)。请改为在 Select content by(按以下方式选择内容) 下选择 Everything: All cached content(全部:所有缓存内容),然后选择 Invalidate(失效)。仪表板不会要求您确认此选项。在 Production 环境中使全部内容失效会应用于所有环境。

如果您的缓存键包含访客的设备类型或国家/地区,Enterprise zone 可以从仪表板使这些 URL 变体失效。选择 URL,然后在 Advanced (custom cache keys)(高级(自定义缓存键)) 下设置设备类型或国家/地区。对于其他缓存键标头,请使用 API。

使用 API 进行失效

要使内容失效,请向 invalidate_cache 端点发送 POST 请求:

https://api.cloudflare.com/client/v4/zones/{zone_id}/invalidate_cache

请求体使用与相应清除请求相同的格式。端点决定 Cloudflare 是清除还是使内容失效。

在以下示例中,将 $ZONE_ID 替换为您的 zone ID,将 $CLOUDFLARE_API_TOKEN 替换为您的 API 令牌。

按 URL 失效

要使特定 URL 失效,请在 files 中列出它们:

curl --request POST \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/invalidate_cache" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "files": ["https://www.example.com/images/product.jpg"]
  }'

如果您的缓存键包含请求标头,请包含用于标识缓存变体的标头值:

{
	"files": [
		{
			"url": "https://www.example.com/images/product.jpg",
			"headers": {
				"CF-Device-Type": "desktop",
				"CF-IPCountry": "US"
			}
		}
	]
}

有关 URL 匹配要求,请参阅按单文件清除。

按标签、主机名、前缀或全部内容失效

使用与要失效的内容匹配的请求体:

选择器 请求体
缓存标签 {"tags":["product-images"]}
主机名 {"hosts":["images.example.com"]}
URL 前缀 {"prefixes":["www.example.com/images"]}
全部内容 {"purge_everything":true}

前缀包含主机名和路径,不含 URL scheme。

例如,要使所有标记为 product-images 的内容失效,请发送此请求:

curl --request POST \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/invalidate_cache" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"tags":["product-images"]}'

使全部内容失效可能在请求到达时触发大量内容的重新验证。请选择能满足需求的最小内容集。

在环境中使内容失效

对于非生产的 Version Management 环境,请在路径中包含环境 ID:

curl --request POST \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/environments/$ENVIRONMENT_ID/invalidate_cache" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"tags":["product-images"]}'

要查找环境 ID,请参阅通过 API 清除 zone 版本。对于生产环境,请使用 zone 级别端点。

向非生产环境发出的使全部内容失效请求仅应用于该环境。向 zone 级别端点发出的相同请求会应用于所有环境。

限制

失效请求计入与清除请求相同的账户级清除限制。适用的限制取决于您如何选择内容:

选择器 适用的限制
URL 单文件清除限制
缓存标签、主机名、URL 前缀或全部内容 主机名、标签、前缀 URL 和清除所有内容的限制

清除和失效请求使用相同的限额。大量使用其中一种会减少另一种可用的容量。与清除限制一样,这些限制按账户应用,并由同一计划的 zone 共享。

每个失效请求可包含的最大项目数与清除请求相同。

验证失效

要验证失效,请使用源站会返回 ETag 或 Last-Modified 标头的可缓存测试 URL。测试期间请保持源站内容不变。要直接观察重新验证,请从测试响应中省略 stale-while-revalidate,并设置正数 TTL。

  1. 请求该测试 URL,直到 CF-Cache-Status 标头返回 HIT。

  2. 使该 URL 失效。

  3. 再次请求该 URL 并检查其响应标头:

    curl --silent --show-error --dump-header - --output /dev/null \
      "https://www.example.com/images/product.jpg"
  4. 在源站日志中确认 Cloudflare 发送了条件请求,并且源站返回了 304。

对于缓存内容,预期结果如下:

结果 CF-Cache-Status
源站确认内容未更改 REVALIDATED,然后是 HIT
源站返回新内容 EXPIRED,然后是 HIT
源站未发送 ETag 或 Last-Modified 标头 EXPIRED,然后是 HIT
Cloudflare 在重新验证时提供过期内容 UPDATING,然后是 HIT
源站返回 5xx 错误或无法访问 STALE
内容已不在缓存中 MISS

如果源站没有 ETag 或 Last-Modified 标头,Cloudflare 没有可用来重新验证的依据,因此会获取完整响应。当源站返回 304 时,Cloudflare 仍可以向访客返回带有缓存内容的 200 OK。

使用分层缓存时,下层数据中心会向上层数据中心重新验证。即使源站返回了 304,访客仍可能看到 EXPIRED 或 MISS。并发请求也会影响您观察到的状态。请使用源站日志确认重新验证。有关状态定义,请参阅 Cloudflare 缓存响应。

排查失效问题

源站返回完整响应

确认内容曾被缓存,并且您的选择器与之匹配。同时确认源站返回 ETag 或 Last-Modified 标头,并对条件请求以 304 Not Modified 响应。

请在直接发往源站(不经过 Cloudflare)的请求中检查这些标头。当源站未发送上述任一标头时,来自 Cloudflare 的响应仍可能包含 Last-Modified 标头,这是因为面向用户的智能重新验证。Cloudflare 在向源站重新验证时不会使用该标头。

如果内容在缓存后还被清除,清除优先,下一次请求会获取完整响应。

访客收到过期内容

在 Cloudflare 重新验证期间,仅当缓存响应包含 stale-while-revalidate 时才会提供过期内容。您可以使用 Cache Rules 中的在重新验证时提供过期内容设置关闭此行为。

如果源站返回 5xx 错误或无法访问,Cloudflare 默认会在内容仍在缓存中时提供已失效的过期内容。Cache Rules 设置不会改变此行为。要限制源站失败时 Cloudflare 提供过期内容的时长,请在源站响应中设置 stale-if-error。要阻止此行为,请设置 stale-if-error=0。启用 Origin Cache Control 时,must-revalidate、proxy-revalidate 和 s-maxage 也会阻止此行为。

要停止提供缓存内容,请改为清除它。

这篇文档对您有帮助吗?