Cache-Control MDN https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Reference/Headers/Cache-Control

一、语法

指令格式具有以下有效规则：

不区分大小写，但建议使用小写。

多个指令以逗号分隔。

具有可选参数，可以用令牌或者带引号的字符串语法。

二、指令列表

缓存请求指令

客户端可以在 HTTP 请求中使用的标准 Cache-Control 指令。

• max-age=<seconds>: 设置缓存存储的最大周期，超过这个时间缓存被认为过期 (单位秒)。时间是相对于请求的时间。

• max-stale[=<seconds>]: 覆盖max-age或者Expires头，但是仅适用于共享缓存 (比如各个代理)，私有缓存会忽略它。

• min-fresh=<seconds>: 表示客户端希望获取一个能在指定的秒数内保持其最新状态的响应。

• no-cache: 在发布缓存副本之前，强制要求缓存把请求提交给原始服务器进行验证 (协商缓存验证)。

• no-store: 缓存不应存储有关客户端请求或服务器响应的任何内容，即不使用任何缓存。

• no-transform: 不得对资源进行转换或转变。Content-Encoding、Content-Range、Content-Type等 HTTP 头不能由代理修改。例如，非透明代理或者如Google's Light Mode可能对图像格式进行转换，以便节省缓存空间或者减少缓慢链路上的流量。no-transform指令不允许这样做。

• only-if-cached: 表明客户端只接受已缓存的响应，并且不要向原始服务器检查是否有更新的拷贝。

缓存响应指令

服务器可以在响应中使用的标准 Cache-Control 指令。

• must-revalidate: 一旦资源过期（比如已经超过max-age），在成功向原始服务器验证之前，缓存不能用该资源响应后续请求。

• no-cache: 在发布缓存副本之前，强制要求缓存把请求提交给原始服务器进行验证 (协商缓存验证)。

• no-store: 缓存不应存储有关客户端请求或服务器响应的任何内容，即不使用任何缓存。

• no-transform: 不得对资源进行转换或转变。Content-Encoding、Content-Range、Content-Type等 HTTP 头不能由代理修改。例如，非透明代理或者如Google's Light Mode可能对图像格式进行转换，以便节省缓存空间或者减少缓慢链路上的流量。no-transform指令不允许这样做。

• public: 表明响应可以被任何对象（包括：发送请求的客户端，代理服务器，等等）缓存，即使是通常不可缓存的内容。（例如：1.该响应没有max-age指令或Expires消息头；2. 该响应对应的请求方法是 POST 。）

• private: 表明响应只能被单个用户缓存，不能作为共享缓存（即代理服务器不能缓存它）。私有缓存可以缓存响应内容，比如：对应用户的本地浏览器。

• proxy-revalidate: 与 must-revalidate 作用相同，但它仅适用于共享缓存（例如代理），并被私有缓存忽略。

• max-age=<seconds>: 设置缓存存储的最大周期，超过这个时间缓存被认为过期 (单位秒)。时间是相对于请求的时间。

• s-maxage=<seconds>：覆盖max-age或者Expires头，但是仅适用于共享缓存 (比如各个代理)，私有缓存会忽略它。

扩展Cache-Control指令

拓展缓存指令不是核心 HTTP 缓存标准文档的一部分，使用前请注意检查兼容性！

• immutable: 表示响应正文不会随时间而改变。资源（如果未过期）在服务器上不发生改变，因此客户端不应发送重新验证请求头（例如If-None-Match或 If-Modified-Since）来检查更新，即使用户显式地刷新页面。

• stale-while-revalidate=<seconds>： 表明客户端愿意接受陈旧的响应，同时在后台异步检查新的响应。秒值指示客户愿意接受陈旧响应的时间长度。

• stale-if-error=<seconds>：表示如果新的检查失败，则客户愿意接受陈旧的响应。秒数值表示客户在初始到期后愿意接受陈旧响应的时间。

三、最佳实践组合示例

1. 静态资源（图片、CSS、JS）

   Cache-Control: public, max-age=31536000, immutable
   ETag: "abc123"
   

   • 作用：公共缓存存储 1 年，且资源不可变（immutable 指令让浏览器无需验证, immutable非标准Cache-Control使用时需要考虑兼容性），配合 ETag 作为资源唯一标识。 注意：ETag变更但max-age没有过期的话，仍不会向服务器发起验证请求。

2. 动态页面（用户登录状态页）

   Cache-Control: no-cache, private
   Pragma: no-cache
   Expires: 0

   • 作用：禁止公共缓存，每次请求前必须验证（no-cache），私有缓存（浏览器）也需每次验证，兼容旧版浏览器（Pragma 和 Expires）。

3. CDN 加速场景

   Cache-Control: public, s-maxage=86400, stale-while-revalidate=3600
   
   

   • 作用：公共缓存（CDN）存储 1 天，过期后允许用户继续使用 1 小时旧资源，同时 CDN 后台验证更新，提升用户体验。

4. 敏感数据接口（如订单详情）

   Cache-Control: no-store
   

   • 作用：绝对禁止任何缓存，确保每次请求都从服务器获取最新数据，防止敏感信息泄露或缓存污染。

四、与其他 Header 的配合使用

• 与 ETag/Last-Modified 配合：
  no-cache 或 must-revalidate 需结合这两个字段，验证时服务器通过 304 Not Modified 告知缓存资源未更新，减少数据传输。

• 与 Pragma 兼容旧浏览器：
  对不支持 Cache-Control 的浏览器，可同时设置 Pragma: no-cache。

• 与 Expires 时间戳配合：
  可设置 Expires: Thu, 31 Dec 2025 23:59:59 GMT，与 max-age 共同控制缓存过期时间（Expires 为绝对时间，max-age 为相对时间）。