Cache and purge
Configure edge cache, browser cache, cache keys and negative caching, and purge by URL, wildcard or the whole site.
Cache settings are on the 缓存 (Cache) tab of a site's detail page (/cdn/domains/<domain>/cache). They apply to every hostname on the site. Click 保存设置 (Save settings) at the bottom after you make changes. To make new content take effect immediately, use 清除缓存 (Purge cache) in the top-right corner.
Edge cache
| Setting | Description |
|---|---|
| 边缘缓存 (Edge cache) | 自动 (Auto): cache based on the origin's response headers. 启用 (On): caching enabled. 禁用 (Off): nothing is cached at the edge. |
| 源站故障时返回过期缓存 (Serve stale content when the origin fails) | If the origin times out or returns 500/502/503/504, the edge serves the expired cached copy instead of an error page. On by default. |
| 缓存时间模式 (Cache TTL mode) | How the cache lifetime is worked out. See the next table. |
| 缓存时间（秒） (Cache TTL, seconds) | The configured value the TTL mode works with. Shortcut buttons fill in 1 hour, 1 day or 7 days. |
Cache TTL modes:
| Mode | Behavior |
|---|---|
| 跟随源站或默认 (Origin, else default) | Use the lifetime from the origin's Cache-Control / Expires headers. If the origin gives none, use the configured value. |
| 固定 (Fixed) | Ignore the origin and always use the configured value. |
| 跟随源站 (Origin only) | Follow the origin strictly. If the origin does not mark the response as cacheable, it is not cached. |
| 取最小值 / 取最大值 (Minimum / Maximum) | Use the smaller or larger of the origin's lifetime and the configured value. If the origin gives none, use the configured value. |
Cache by file type
Under 按文件类型缓存 (Cache by file type) you can set a lifetime per file extension, for example 7 days for jpg,png,gif. The edge applies it when the origin response has no explicit lifetime (no max-age, s-maxage or Expires). If the origin does set one, the origin's value wins.
Responses that are never cached
These responses never enter the edge cache, whatever your settings:
- Responses with
Cache-Control: no-storeorprivatefrom the origin - Responses that set a cookie (
Set-Cookie) 206 Partial Contentresponses to Range requests- Requests with methods other than GET and HEAD
Browser cache
浏览器缓存 (Browser cache) controls whether the edge adds a Cache-Control header for browsers:
- 启用 (On): for responses the edge has actually cached, the edge adds
Cache-Control: public, max-age=<edge TTL>if the origin sent noCache-Control. The edge TTL is how long the edge itself keeps the response, so the browser's lifetime matches the edge's. - 自动 (Auto) or 禁用 (Off): the edge does not add browser-cache headers.
The origin's own Cache-Control is always passed to the browser unchanged. The edge never adds a browser-cache header to any of these:
- Responses it did not cache, such as dynamic APIs
- Requests with methods other than GET and HEAD
- Responses with status 400 or higher
- Responses that set a cookie
This stops dynamic content from getting stuck in browser caches.
The most reliable way to give static assets a long browser lifetime is to have your origin send an explicit Cache-Control: max-age=... for them.
Cache key
The cache key decides which requests share a cached copy. The preview at the bottom of the section shows what the key is made of with your current settings.
Query String处理模式 (Query string handling):
| Mode | Behavior | Example |
|---|---|---|
| 标准 (Standard) | Keep every query parameter as-is | ?a=3 and ?a=4 are cached separately |
| 忽略 (Ignore) | Ignore all query parameters | ?a=3 and ?a=4 share one copy |
| 排序 (Sorted) | Keep every parameter, sorted by name | ?b=2&a=1 and ?a=1&b=2 share one copy |
| 白名单 (Allowlist) | Keep only the listed parameters | id,page |
| 黑名单 (Denylist) | Drop the listed parameters | utm_source,utm_medium,ref |
Separate parameter names with commas.
You can also split the cache by these dimensions:
- 按设备类型区分 (By device type): separate copies for mobile and desktop.
- 按国家区分 (By country): separate copies per visitor country or region.
- 按语言区分 (By language): separate copies per
Accept-Language. - 缓存主机模式 (Cache host mode): which hostname goes into the key:
- 原始请求 (Original request): the Host the visitor requested. This is the default.
- 解析后 (Resolved): the hostname the site matched.
- Host头 (Host header): the Host used for the origin request.
Each extra dimension can split one URL into several cached copies, which lowers your hit ratio. Only turn on the dimensions you need.
Advanced caching and negative caching
| Setting | Description |
|---|---|
| 按状态码缓存（负缓存） (Cache by status code) | A cache lifetime in seconds for specific status codes such as 404 or 301. This takes priority over all other TTL settings and stops error responses from hitting the origin again and again. |
| 最小缓存时间 (min_ttl) / 最大缓存时间 (max_ttl) | A lower and upper bound on the final cache lifetime. 0 means no bound. |
| 故障宽限 (stale_if_error) | When the origin fails, keep serving expired content for this many seconds. |
| 带 Authorization 不缓存 (Bypass when Authorization is present) | Requests with an Authorization header skip the cache and go to the origin. |
| 尊重客户端 no-cache (Honor client no-cache) | Requests with Cache-Control: no-cache skip the cache. |
| 绕过缓存的会话 Cookie (Bypass cookies) | Requests that carry any listed cookie, such as session or token, skip the cache. |
Origin protection (Origin Shield)
回源最大并发 (Max origin concurrency) limits how many requests one site can have in flight to the origin at the same time. 0 means no limit.
Above the limit, the actions in 超限动作(阶梯) (overflow action ladder) apply in order:
- cache_first: serve from cache.
- queue: wait in a queue. You set the queue length and the maximum wait in milliseconds.
- challenge: show a human-verification challenge.
- block: block the request and return the Retry-After time you set.
Use it to protect origins with limited capacity.
Purging the cache
Changing cache settings does not expire content that is already cached. To make the edge fetch fresh content from your origin:
- On the Cache tab, click 清除缓存 (Purge cache) in the top-right corner. The Domains list and the Overview tab also have a one-click full-site purge.
- Choose a purge type:
- 清除全站缓存 (Purge everything): remove all cached content for the site.
- 按 URL 清除 (Purge by URL): enter one URL per line. Use either a full URL (
https://example.com/css/app.css) or a path (/css/app.css).
- Click 确认清除 (Confirm).
How purge by URL matches:
- With a query string (for example
/list?page=2): only that parameter combination's copy is purged. The query is normalized with the site's query-string mode before matching. - Without a query string (for example
/list): every query-string variant of that path is purged. - Wildcards: put a single line containing
*to purge by pattern, for examplehttps://example.com/static/*for everything under that directory. If more than one line contains*, the request becomes a full-site purge.
A purge is delivered to all edge nodes in the background and usually completes within seconds. Afterwards, check the X-Cache-Status response header with curl -I. The first request should show MISS.
Right after a full-site purge, every request goes to your origin, so origin load rises noticeably. If you only changed a few files, purge those URLs instead.
Related
- Set cache or browser lifetimes for specific paths: Page rules
- Check your cache hit ratio: Logs and analytics