11 · 精准清缓存与发布流程
用版本 URL、URL/Tag/Prefix/Hostname Purge 和可验证回滚，让新内容及时上线而不制造全站回源洪峰。
编辑与核验：橙宝书编辑团队 ·
发布原则
不可变静态资源通过新 URL 发布，通常无需清缓存；可变 HTML/API 只刷新受影响的 URL、Tag、Prefix 或 Hostname；Purge Everything 只用于无法界定范围的事故，而不是每次部署的固定步骤。
选择最小刷新范围
| 内容变化 | 首选动作 | 原因 |
|---|---|---|
| 指纹 JS/CSS/图片 | 发布新 URL | 旧版本可继续服务旧 HTML，回滚简单 |
| 单篇文章/产品 | Purge by URL | 官方推荐的最精确方式 |
| 一组相关内容 | Purge by Cache-Tag | 发布系统按内容实体刷新 |
| 一个目录 | Purge by Prefix | 适合路径边界明确的批量更新 |
| 一个主机名 | Purge by Hostname | 独立站点或租户整体变更 |
| 无法界定的错误对象 | Purge Everything | 范围最大，会增加回源与冷缓存成本 |
Cloudflare 当前在所有套餐提供 URL、Hostname、Tag、Prefix 与 Purge Everything，具体速率限制按套餐和账号共享。即使能力可用，也应把范围最小化并对 429 做退避，而不是并发重试放大问题。
把刷新放进发布事务
flowchart LR
A[构建带哈希资源] --> B[上传新资源]
B --> C[部署引用新 URL 的 HTML/API]
C --> D[只刷新可变 URL 或 Tag]
D --> E[验证版本、响应头与业务]
E --> F{通过?}
F -- 是 --> G[完成发布并监控]
F -- 否 --> H[回滚 HTML/API，再刷新相同范围]先上传新静态资源，再发布引用它的页面，避免 HTML 指向尚不存在的文件。刷新发生在内容已可从源站读取之后，否则 Cloudflare 会把旧内容清掉并缓存错误响应。
控制台与 API 两种方式
控制台适合低频人工修复；持续发布应使用最小权限 Token 和审计日志自动化。Purge API 当前入口为：
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/purge_cache" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{"files":["https://www.example.com/docs/changed-page"]}'Token 只授予目标 Zone 所需的 Cache Purge 权限，放在 CI Secret 中，不写入仓库、日志或 AI 对话。先对测试 Zone 调用，并保存请求范围、发布时间和 API 响应。
常用请求体：
{"tags":["post:42","category:guides"]}{"hosts":["www.example.com"]}{"prefixes":["www.example.com/docs/"]}不要把示例组合进一次请求；每次只使用与发布对象对应的刷新类型，并遵循当前官方操作数与速率限制。
自定义 Cache Key 的刷新陷阱
若键包含 Header、Cookie、设备、地区或语言，单纯发送 URL 可能只清掉一个变体。Cloudflare API 支持为文件 URL 同时提供形成缓存键的头；发布系统必须保留变体清单，或改用能覆盖该对象集合的 Tag/Prefix 设计。
浏览器缓存不会被 Purge
Cloudflare Purge 只影响 Cloudflare 缓存层。用户浏览器中仍然新鲜的对象不会被远程删除，因此可变资源必须使用短 Browser TTL；长 Browser TTL 只给内容哈希 URL。
发布前后的验证
发布前保存版本证据
记录构建 ID、资源哈希、目标 URL、预期 Cache-Tag、当前 ETag 与响应正文哈希。
上传并从源站路径确认
确认新资源存在、HTML/API 已引用正确版本，再执行刷新。不要通过临时关闭 TLS、WAF 或删除隐私头来让检查通过。
刷新最小集合
单页用 URL，实体集合用 Tag，明确目录用 Prefix。批量操作分块，并对速率限制使用带抖动的指数退避。
从两个位置检查
连续请求保存 CF-Cache-Status、Age、ETag、Cache-Control、正文哈希与 CF-Ray。再用真实浏览器确认没有本地缓存和 Service Worker 持有旧版本。
演练回滚
恢复上一版 HTML/API，使用与正向发布相同的精准刷新范围。指纹静态资源无需覆盖，可保留给仍引用旧版本的客户端。
下一篇介绍 Tiered Cache 与 Cache Reserve如何减少刷新后和多地区冷缓存带来的源站压力。
官方来源
这篇内容帮你完成目标了吗？
内测反馈只在当前浏览器生成，不会自动上传。