失效会将缓存内容标记为过期 (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 中,并继续产生存储费用。如果源站响应 304 Not Modified,Cloudflare 会重用已存储的内容,而不是再次从源站获取。即使设置了 stale-while-revalidate,从 Cache Reserve 提供的内容在重新验证时也不会以过期状态提供。
与清除相比,失效会减少源站出站流量,但不会减少 Cache Reserve 操作。在 304 响应后更新已存储内容属于 Class A 操作。按 URL 失效也会在发送请求时更新已存储内容,这同样是 Class A 操作。详情请参阅 Cache Reserve 操作。
清除会强制匹配的 Cache Reserve 内容发生缓存未命中。详情请参阅 Cache Reserve 清除行为。
从仪表板或 invalidate_cache 端点进行的失效不会影响 Workers Cache。Workers Cache 属于您的 Worker,而不属于您的 zone。要从 Worker 的缓存中移除响应,请从该 Worker 调用 ctx.cache.purge()。
在使内容失效之前,请检查以下要求:
- 源站验证器:要重用缓存内容,源站必须返回
ETag或Last-Modified标头,并支持条件请求。 - 权限:对于 API 请求,请使用对该 zone 具有 Cache Purge 权限的令牌。要从仪表板进行失效,您的角色必须包含相同权限。
- 速率限制:失效请求会计入账户的清除限制。详情请参阅限制。
-
在 Cloudflare 仪表板中,前往 Configuration(配置) 页面。
前往 Configuration(配置) ↗ -
如果您的 zone 使用 Version Management,请选择 Global(全局) 选项卡。然后在 Invalidate Cache(使缓存失效) 中,在 Choose the environment(选择环境) 下选择环境。仪表板会预选一个环境,因此请在继续前检查所选内容。
-
在 Invalidate Cache(使缓存失效) 中,选择 Custom Invalidation(自定义失效)。如果您的 zone 使用 Version Management,此按钮的标签为 Select Content(选择内容)。
-
在 Select content by(按以下方式选择内容) 下,选择 URL、Hostname、Tag 或 Prefix,并输入要失效的值。
-
选择 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。
要使内容失效,请向 invalidate_cache 端点发送 POST 请求:
https://api.cloudflare.com/client/v4/zones/{zone_id}/invalidate_cache请求体使用与相应清除请求相同的格式。端点决定 Cloudflare 是清除还是使内容失效。
在以下示例中,将 $ZONE_ID 替换为您的 zone ID,将 $CLOUDFLARE_API_TOKEN 替换为您的 API 令牌。
要使特定 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。
-
请求该测试 URL,直到
CF-Cache-Status标头返回HIT。 -
使该 URL 失效。
-
再次请求该 URL 并检查其响应标头:
curl --silent --show-error --dump-header - --output /dev/null \ "https://www.example.com/images/product.jpg" -
在源站日志中确认 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 也会阻止此行为。
要停止提供缓存内容,请改为清除它。