# Cache-Control 参考

URL: https://caijiao.org/reference/http/cache-control
Source: docs/reference/http/cache-control.md
Description: Cache-Control Reference，整理 max-age、no-cache、no-store、public、private、immutable、静态资源缓存、HTML 缓存和常见错误。

`Cache-Control` 用于控制浏览器、代理、CDN 等缓存如何存储和复用响应。静态资源性能、HTML 更新延迟、接口缓存异常，都经常和这个响应头有关。

## 语法

```http
Cache-Control: <directive>, <directive>
```

## 常见指令

| 指令 | 说明 | 常见场景 |
| --- | --- | --- |
| `max-age=31536000` | 响应在指定秒数内新鲜 | 带 hash 的静态资源 |
| `no-cache` | 可存储，但每次使用前要重新验证 | HTML 页面 |
| `no-store` | 不存储响应 | 登录、支付、隐私数据 |
| `public` | 可被共享缓存保存 | 公共静态资源 |
| `private` | 只允许浏览器私有缓存 | 用户相关页面 |
| `immutable` | 资源在新鲜期内不会变化 | 文件名带内容 hash 的资源 |

## 静态资源示例

```http
Cache-Control: public, max-age=31536000, immutable
```

适合文件名带 hash 的 CSS、JS、图片资源。

## HTML 示例

```http
Cache-Control: no-cache
```

适合需要及时看到新版内容的 HTML 页面。

## 敏感接口示例

```http
Cache-Control: no-store
```

适合登录态、支付、用户私密信息接口。

## 常见错误

- HTML 设置了很长 `max-age`，上线后用户迟迟看不到新版。
- 文件名不带 hash，却设置长期缓存，覆盖发布会导致旧资源难以失效。
- 用户私有接口被 CDN 或共享缓存保存，产生数据泄露风险。
- 误以为没有 `Cache-Control` 就不会缓存；浏览器和代理仍可能按启发式缓存处理。

## 相关内容

- [HTTP Reference](/reference/http/)
- [HTTP Headers 总览](/reference/http/headers)
- [Nginx 配置 Reference](/reference/nginx/)
- [网站上线前我会检查哪些项目](/posts/138)
- [MDN Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control)
- [MDN HTTP caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching)