> For the complete documentation index, see [llms.txt](https://www.axisnow.io/zh/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.axisnow.io/zh/docs/edge/policies/cache/use-cases.md).

# 配置场景

缓存控制的典型配置场景与规则参数

各表里的域名、路径都是示例值。规则的先后见页末的[分层](#layering)。

## 动态接口和页面绕过 <a href="#bypass-dynamic" id="bypass-dynamic"></a>

API、登录、账户、购物车、结账、后台等不能缓存的路径，以及所有非 GET/HEAD 请求。为动态站点开启 HTML 缓存之前先加这条规则。

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>两个条件组，任一成立即命中：请求 Host 在以下各项之中 <code>www.example.com</code>，并且 请求 URI 路径 开头为 <code>/api/</code>、<code>/login</code>、<code>/account/</code>、<code>/cart</code>、<code>/checkout</code>、<code>/admin/</code>；请求 Host 在以下各项之中 <code>www.example.com</code>，并且 HTTP 请求方法 不在以下各项之中 <code>GET</code>、<code>HEAD</code></td></tr><tr><td>边缘缓存</td><td>绕过缓存</td></tr><tr><td>浏览器缓存</td><td>遵循源站</td></tr></tbody></table>

## 静态资源长缓存 <a href="#static" id="static"></a>

文件名带指纹（如 `app.3f2a9c.js`）的构建产物，内容变了文件名就变，可以缓存很久且忽略查询参数。

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>请求 Host 在以下各项之中 <code>www.example.com</code>，并且 请求 URI 路径 通配符匹配 <code>/assets/*</code></td></tr><tr><td>缓存时长</td><td>忽略源站，默认时长 30 天</td></tr><tr><td>缓存 Key</td><td>预设：静态资源</td></tr><tr><td>浏览器缓存</td><td>自定义，30 天</td></tr></tbody></table>

没有指纹、以 `?v=2` 这类参数区分版本的，缓存 Key 改用预设**带版本参数**。

## 缓存 HTML 页面 <a href="#html" id="html"></a>

内容对所有访客相同的页面（首页、文章、商品详情），缓存几分钟即可省去大部分回源；内容更新通过[清理](/zh/docs/edge/policies/cache/purge-and-warming.md)生效。源站优先模式下源站仍可用 `Cache-Control: private` 或 `no-store` 拒绝某个页面被缓存，动态与静态混杂的站点用这种方式由源站逐页决定。

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>请求 Host 在以下各项之中 <code>www.example.com</code>，并且 HTTP 请求方法 在以下各项之中 <code>GET</code>、<code>HEAD</code></td></tr><tr><td>缓存时长</td><td>源站优先，默认时长 300 秒</td></tr><tr><td>缓存 Key</td><td>预设：默认</td></tr><tr><td>浏览器缓存</td><td>遵循源站</td></tr></tbody></table>

这条规则接管该站点其余所有 GET/HEAD 请求，默认规则对它不再生效，静态资源和大文件的规则必须排在它前面。页面响应带 `Set-Cookie` 时不会缓存，先在源站把会话 Cookie 限定到需要它的路径。登录后页面不同的站点，把登录态页面交给前面的绕过规则，或用下一个场景。

## 按登录态或语言区分副本 <a href="#variants" id="variants"></a>

同一 URL 对不同用户群返回不同内容时，在上一场景的规则上把差异所在的 Cookie 或请求头加入 Key，其余访客仍共用副本。同类做法：A/B 测试把分组 Cookie 加入 Key；同一 URL 按 `Accept` 返回 JSON 或 HTML 的接口，请求头只包含 `Accept`；源站按请求 `Origin` 返回 CORS 头的，请求头只包含 `Origin`。

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>请求 Host 在以下各项之中 <code>www.example.com</code></td></tr><tr><td>缓存时长</td><td>源站优先，默认时长 300 秒</td></tr><tr><td>缓存 Key</td><td>按登录态区分：Cookie 只包含 <code>session_role</code> 这类取值有限的 Cookie，不要选全部。按语言区分：源站按语言下发 Cookie 的，Cookie 只包含该 Cookie；预设的多语言按 <code>Accept-Language</code> 原值区分，浏览器写法各异，副本过于分散</td></tr></tbody></table>

## 大文件分发 <a href="#large-files" id="large-files"></a>

视频、安装包、镜像等大文件，客户端常以 Range 分段下载。

<table data-search="false"><thead><tr><th width="140">配置项</th><th>取值</th></tr></thead><tbody><tr><td>条件</td><td>请求 Host 在以下各项之中 <code>dl.example.com</code></td></tr><tr><td>缓存时长</td><td>忽略源站，默认时长 7 天</td></tr><tr><td>缓存 Key</td><td>预设：静态资源</td></tr><tr><td>缓存分片</td><td>开启，10 MB</td></tr></tbody></table>

## 分层 <a href="#layering" id="layering"></a>

规则取第一条命中，同一站点按下面的顺序排，条件越具体越靠前：

1. 绕过缓存：动态接口、非 GET/HEAD 请求、后台。
2. 长缓存：带指纹或版本参数的静态资源、大文件。
3. 短缓存：HTML 页面、需要区分副本的内容。这类规则条件宽，排在它后面的规则对该站点不再有机会命中。
4. 默认规则：没有自定义规则的站点的静态后缀。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.axisnow.io/zh/docs/edge/policies/cache/use-cases.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.