HTTP 缓存语义:Cache-Control 与 ETag 带来的八处静默分歧
静态站的缓存问题从来不出错。它只是让你把一份改过的文件重新发一遍、让读者刷新三次还是看到旧的、让你在发布后第五分钟去抽查页面、看到 404 就开始怀疑构建是不是挂了。这三个症状我都撞过,而且都落在同一个地方:响应头。
我实际做了三轮实验。第一轮用 curl 抓本站真实响应头并逐字段拆开;第二轮在本机起三个最小 HTTP 服务,让 CacheControl 0.15.0(requests 2.34.2)去访问,数它到底回源了几次、回来的 body 是哪一版;第三轮把 304 直接丢给 urllib 和 requests,看它们各自怎么处理「没有 body 的成功响应」。下面八处分歧全部来自这三轮,没有一处是抄文档抄来的。
TL;DR:ETag 的引号是语法而不是格式,把引号去掉,本机实测从 304(0 字节)退化成每次 200 全量 85,576 字节;no-cache 会存但每次验证,no-store 才是真不存,而 immutable 直接跳过验证;本站 404 页没有任何 Cache-Control,CDN 照样缓存它;想用 ?cb= 或 Pragma: no-cache 破缓存,两个都无效;Vary 缺一行,缓存就会把中文页交给英文读者。
先把一个真实响应拆开
拿本站任意一篇已发布文章,curl -sI 得到的是这样一组头(下面是 11-16 那篇的原文,只删了请求 ID):
HTTP/1.1 200 OK
Content-Length: 85576
Last-Modified: Mon, 16 Nov 2026 21:26:57 GMT
ETag: "6afb7521-14e48"
expires: Mon, 16 Nov 2026 22:21:50 GMT
Cache-Control: max-age=600
Age: 0
Vary: Accept-Encoding
X-Cache: MISS
一行一行读,主管单位不一样:
| 字段 | 谁写的 | 它管什么 |
|---|---|---|
Cache-Control: max-age=600 | 源站(GitHub Pages) | 600 秒内可以直接用本地副本,不必问源站 |
ETag | 源站 | 过期之后拿什么去问「变了吗」 |
expires | 源站 | 老式过期时间,这里等于 Date 加 600 秒 |
Age: 0 | 中间缓存(Fastly) | 这份副本已经在 CDN 上躺了几秒 |
X-Cache | 中间缓存 | 这次是命中还是回源 |
Vary: Accept-Encoding | 源站 | 压缩版和未压缩版是两个对象,别互相顶替 |
expires 那行的值是 22:21:50,而响应 Date 是 22:11:50 —— 正好差 600 秒。也就是说同一个策略这里写了两遍:一遍新式的 Cache-Control,一遍老式的 expires。为什么要写两遍,第五处会讲。
第一处:ETag 的引号是语法,不是装饰
把上面那个 ETag 原样放进 If-None-Match,再用四种写法各打一次,结果完全不「差不多」:
| 请求头里的写法 | 状态码 | 实际传输 |
|---|---|---|
If-None-Match: "6afb7521-14e48" | 304 | 0 字节 |
If-None-Match: 6afb7521-14e48(去掉引号) | 200 | 85,576 字节 |
If-None-Match: W/"6afb7521-14e48" | 304 | 0 字节 |
If-None-Match: "deadbeef-1" | 200 | 85,576 字节 |
去掉引号那一行是这套机制里最贵的一个错字。ETag 的语法是 entity-tag = [ weak ] opaque-tag,而 opaque-tag 必须带双引号;不带引号的东西在解析器眼里不是「同一个值少了两字符」,而是一个格式不合法的头,整条被忽略。忽略之后请求退化成无条件 GET,服务器老老实实把 85,576 字节再传一遍,状态码 200,日志里一行错误都没有。
自己拼 HTTP 头、或者用某个中间层把 ETag 存进数据库再读出来时,这条很容易踩:JSON 序列化和反序列化不会帮你保住引号,很多模板引擎还会把双引号转义。判据很简单 —— 条件请求必须能看到 304,看到 200 就说明你发的不是合法 ETag。
顺带测了两个边界:If-None-Match: * 对存在的资源返回 304(这个词的意思是「只要有任何一份表示就匹配」),对不存在的路径返回 404;把一个列表 "aaa", "6afb7521-14e48" 丢过去也返回 304,说明多值解析是好的。
第二处:ETag 里装着修改时间和字节数
上面那个 ETag 长得像随机串,其实不是。把两段十六进制分别解出来:
6afb7521 = 1794864417 → 2026-11-16 21:26:57 UTC (正好等于 Last-Modified)
14e48 = 85576 (正好等于 Content-Length)
再抽三篇验证:另一篇正文的 ETag 是 "6afb7521-dd19",0xdd19 = 56,601,与它的 Content-Length 一致;404 页的 ETag 是 "6afb7521-92d",0x92d = 2,349,也与 404 页体积一致;sitemap.xml 的 "6afb7521-3efdc" 解出来是 258,012,跟它的 Content-Length 分毫不差。
下面是推断不是实测(我没有权限去改线上文件的 mtime):这套 ETag 的强度只到「秒级修改时间 + 总字节数」。两个直接后果 ——
- 同一秒内完成、且改完之后总字节数恰好不变的修改,ETag 不变。对压缩过的产物这不罕见:改一个字符同时删一个空格,体积一模一样。
- 换一台机器重新构建、mtime 变了,哪怕内容一字未改,ETag 也会全站变化,所有客户端的缓存一次性作废。
所以我更愿意把它当「版本号」而不是「内容指纹」用:拿它判断「这份是不是我刚推的那份」很可靠;拿它证明「内容没变」不可靠。
第三处:弱验证器让两种表示共用同一个 ETag
同一篇文章,加不加 Accept-Encoding 拿到的是两个不同的对象:
Accept-Encoding: gzip → 47,144 字节 ETag: W/"6afb7521-14e48" Content-Encoding: gzip
Accept-Encoding: identity → 85,576 字节 ETag: "6afb7521-14e48"
两件事值得记:体积差 45%,而 ETag 的 opaque-tag 部分完全一样,只差一个 W/ 前缀;并且两个方向的条件请求都拿到 304 —— 拿压缩版的弱 ETag 去要未压缩版是 304,拿未压缩版的强 ETag 配 Accept-Encoding: gzip 也是 304。
RFC 9111 的 4.3.4 节规定:304 带强验证器时,缓存会把所有持有同一个强验证器的已存响应都更新掉;带弱验证器时只更新最近的那一份。这里之所以没出事,是因为 Vary: Accept-Encoding 把两种表示隔成了两个对象 —— 也就是说,Vary 才是那个真正负责不串的东西,ETag 只负责「变了没」。
这条对一个多语种站是硬约束:如果你把中文页和英文页放在同一个 URL 上按 Accept-Language 分流,却不发 Vary: Accept-Language,缓存就会把它们当成同一个对象。第八处有实测。
第四处:no-cache 存了但每次验证,no-store 才是真不存
这一组是本轮最反直觉的。我起了四个端点,分别发四种指令,每个都用独立缓存目录跑 2 到 3 次请求,数服务器被打了多少次、回来的 body 是哪一版:
| 响应头 | 请求次数 | 回源次数 | 条件请求 | 拿到的 body |
|---|---|---|---|---|
Cache-Control: no-store + ETag | 2 | 2 | 0 | 第 1 次 NOSTORE 1,第 2 次 NOSTORE 2 |
Cache-Control: no-cache + ETag | 3 | 3 | 2 | 三次都是 NOCACHE 1 |
Cache-Control: max-age=0, must-revalidate + ETag | 2 | 2 | 1 | 两次都是 MAXAGE0 1 |
Cache-Control: max-age=3600, immutable + ETag | 2 | 1 | 0 | 两次都是 IMMUTABLE 1 |
no-store 那一行:每次请求都拿到不同的 body,说明上一份真的没落盘。no-cache 那一行正好相反:三次请求打了三次服务器,但 body 一直是第一次那份 —— 它存了,只是每次用之前都要问一遍。RFC 9111 的 5.2.2.4 节原文是 MUST NOT be used to satisfy any other request without forwarding it for validation,主语是「用」不是「存」;no-store(5.2.2.5 节)才是 MUST NOT store any part。
max-age=0, must-revalidate 的表现和 no-cache 一模一样(2 次请求 2 次回源、body 不刷新)。这不是巧合:max-age=0 让它一出生就过期,must-revalidate 禁止用过期的副本,两条合起来的效果就是「每次都得问」。区别只在于它多了一条「过期后不许拿旧的顶」的兜底。
而 immutable 是另一个极端:两次请求只打了 1 次服务器,连条件请求都没发。浏览器刷新、前进后退都不会去问。所以它只适合文件名里带内容哈希的静态资源 —— 用在 HTML 上,就是把读者锁在旧版本里。
第五处:Expires 和 Cache-Control 打架时后者赢
三种组合,同样跑 3 次请求:
| 响应头组合 | 回源次数 | 说明 |
|---|---|---|
Expires 一小时后 + Cache-Control: max-age=0 | 3 | 每次都回源,Cache-Control 赢 |
只有 Expires 一小时后 | 1 | 后两次直接命中 |
Cache-Control: max-age=3600 + Expires 一小时前 | 1 | 后两次直接命中,Cache-Control 又赢 |
方向是单向的:Cache-Control 在场,Expires 就被无视;Cache-Control 缺席,Expires 才管事。这也解释了为什么本站两个都发 —— 发给只认 HTTP/1.0 语义的老中间层时,Expires 是那条还在起作用的线。
真正容易出错的是只删了一个。改配置时把 Cache-Control 删掉、留着 Expires,看起来「还有过期时间」,实际上是换了一套语义;反过来把 Expires 删掉、留下 Cache-Control,行为又变一次。要动就两个一起动。
第六处:不发 Cache-Control 也是一种策略
python -m http.server 起的预览服务,响应头是这样的(本机实测,Python 3.13.14):
Server: SimpleHTTP/0.6 Python/3.13.14
Content-type: text/plain
Content-Length: 1100
Last-Modified: Mon, 16 Nov 2026 22:14:38 GMT
没有 Cache-Control,也没有 ETag,只有 Last-Modified。但它会处理条件请求:带上 If-Modified-Since 再请求一次,返回 304。也就是说,本地预览的缓存行为完全由客户端的启发式规则决定,而「变没变」只能精确到秒。
线上也一样有空档:本站 404 页的响应里根本没有 Cache-Control(连 expires 都没有),但同一个 404 URL 连打两次,第二次 X-Cache: HIT、Age: 1 —— 没策略不等于不缓存,CDN 会按自己的默认值留一会儿。这就是「刚发布的新页面,五分钟内打开还是 404」的一条真实机制:你看到的可能不是你刚推的那份,而是上一次那份 404。
RFC 9111 的 4.2.2 节允许缓存在没有显式过期时间时自行估算启发式新鲜度。估算值不可观测,也不可协商 —— 这本身就是一条要写进发布流程的风险。
第七处:查询串与 Pragma 都救不了你
破缓存的两招,一招都不灵。
第一招是加查询串。我拿四个不同的随机 ?cb= 连打同一篇文章,每次都在几秒内:
?cb=<随机 1> Age: 181 X-Cache: HIT
?cb=<随机 2> Age: 182 X-Cache: HIT
?cb=<随机 3> Age: 184 X-Cache: HIT
无查询串 Age: 185 X-Cache: HIT
四个不同的 URL,年龄完全同步增长 —— 说明它们命中的是同一个缓存对象,这个站(GitHub Pages 加 Fastly)的缓存键里不含查询串。既然是同一个对象,?cb= 就没有制造新副本,它只是让 URL 看起来不一样。
第二招是 Pragma: no-cache。带上它、再加上正确的 If-None-Match,依然返回 304 —— 它被完全忽略。RFC 9111 的 5.4 节写得很直白:这个头是为 HTTP/1.0 缓存定义的,本规范弃用它。
有意思的是客户端侧反着来:同一个 CacheControl 客户端,/q?a=1 与 /q?a=2 是两个不同的缓存条目(第二次没有命中)。所以「查询串算不算缓存键」这件事,CDN 和客户端库给出的答案可能相反 —— 你按其中一边的直觉写的破缓存手法,在另一边是空转。
第八处:Vary 缺失时缓存把语种串给你
两个端点,返回的 body 都随 Accept-Language 变,Cache-Control 都是 max-age=300,差别只在于一个发了 Vary: Accept-Language、一个没发。先用 zh 请求一次,再换 en 请求一次:
| 端点 | 第 1 次(zh) | 第 2 次(en) | 第 2 次回源 |
|---|---|---|---|
| 不发 Vary | LANG=zh FIRST=True | LANG=zh FIRST=True | 0 次(命中缓存) |
| 发 Vary | LANG=zh FIRST=True | LANG=en FIRST=False | 1 次 |
不发 Vary 的那个,英文请求拿到的是中文 body,而且一次都没有回源、没有任何报错、状态码 200。这就是「缓存串版」的完整机制:URL 相同、缓存键相同,缓存认为你要的就是它手里那份。
对一个同时有中英日的站,这条的直接含义是:只要有任何一层(CDN、反向代理、公司网关)在同一个 URL 上按 Accept-Language 分流,就必须把 Vary: Accept-Language 一起发出去;只靠 Cache-Control 管不住这件事。同理,Accept-Encoding 丢 Vary 的后果是把 gzip 字节喂给不支持 gzip 的客户端 —— 本站这一行一直在,属于少数不需要操心的地方。
304 拿到的不是一段 body:三个客户端的三种反应
把同一个 304 响应丢给三种客户端,行为完全不同:
| 客户端 | 结果 |
|---|---|
curl | 状态 304,下载 0 字节,正常退出 |
urllib.request.urlopen | 抛 HTTPError: HTTP Error 304: Not Modified |
requests.get | status_code 为 304,r.text 为空字符串 |
CacheControl(带缓存) | 返回缓存里的 body,并把头部更新成 304 里的那份 |
urllib 把 304 当异常,是因为它对非 2xx 统一走 HTTPError 分支 —— 而 304 是成功语义。写校验脚本时这一点会咬人:try/except HTTPError 里如果把 304 当失败,你的健康检查会在「内容没变」这个最健康的情况下报警。
requests 不抛异常,但 body 是空的。紧跟着 r.json() 就会炸 —— 报错原文在下一节。正确的处理只有一句:304 视为成功,并且复用本地已有的那份内容。
带缓存的客户端(CacheControl)展示了标准做法:它把 304 的头部更新到已存响应上(RFC 9111 的 4.3.4 节),body 继续用旧的。实测把 max-age=2 的端点隔 2.5 秒连打三次,服务器被打了 3 次、条件请求每次都发,但三次拿到的 body 全是第一版 —— 回源不等于重传。
扩展指令不是协议保证
stale-while-revalidate 和 immutable 都不是 RFC 9111 里的东西。前者来自 RFC 5861(2010 年,Independent Submission,状态 Informational):允许缓存在后台验证的同时先给一份过期的内容。后者是事实标准,浏览器支持,但同样不在 RFC 9111 正文里。
实测 CacheControl 0.15.0:端点发 Cache-Control: max-age=1, stale-while-revalidate=600,等 1.6 秒再请求 —— 它没有先给旧内容,而是直接回源(服务器被打第 2 次,from_cache 为 False)。同一个库对 immutable 却是执行的(2 次请求 1 次回源)。
结论不是「这个指令没用」,而是「依赖扩展指令时,你依赖的是具体那个实现」。它们没有互操作性保证,测一遍比读文档快。
落到自己站上:三个判断
一,发布后的十分钟是个真实的窗口。 max-age=600 意味着推送成功之后,旧副本还能再活最多 600 秒。终检看到 404 或者旧版,先分清是「构建还没跑完」还是「缓存还没过期」:前者看构建状态,后者等,别改代码。
二,?cb= 不能当破缓存手段。 上面测过,这个站的缓存键不含查询串。要判断「线上是不是新版」,可靠的做法是比对 ETag(它就是 mtime 加体积),或者比对一个只在正文里出现一次的字符串。这也是我为什么在发布后核对里从不看体积:sitemap.xml 每次构建都会重建,体积会变,而 Cache-Control 还是 600。
三,多语种站的 Vary 要单独核。 中文页、英文页、日文页是三个不同 URL,这条还好;但只要有一层按 Accept-Language 在同一个 URL 上分流,就必须发 Vary。检查方法很简单:curl -sI 看有没有那一行,没有就补。
这套「静默分歧」的读法和我在 Windows 路径语义 里用的是一套:字符串看起来一样、行为不一样、而且不报错。同源的还有 YAML 配置读错值 与 shell 脚本九个静默失败,如果你也在维护一条自动发布链路,这三篇可以一起看。
常见报错与处理
报错一:urllib.error.HTTPError: HTTP Error 304: Not Modified
Traceback (most recent call last):
File "check.py", line 12, in main
with urllib.request.urlopen(req, timeout=5) as r:
urllib.error.HTTPError: HTTP Error 304: Not Modified
原因:urllib 把非 2xx 全部归到 HTTPError,304 虽然属于成功语义,仍然会抛。处理:显式接住它,当成「内容未变」而不是失败。
except urllib.error.HTTPError as e:
if e.code == 304:
return cached_copy # 视为成功
raise
报错二:json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
原因:requests 对 304 返回 304 状态码加空 body,紧接着 r.json() 解析空字符串。处理:先判 304,再决定用本地副本;不要对可能为 304 的响应无条件调 .json()。
r = sess.get(url, headers={"If-None-Match": etag})
if r.status_code == 304:
return local_cache
return r.json()
报错三:ImportError: NOTE: In order to use the FileCache you must have filelock installed
完整原文:
NOTE: In order to use the FileCache you must have
filelock installed. You can install it via pip:
pip install cachecontrol[filecache]
原因:cachecontrol 0.15.0 把 filelock 设成可选依赖,FileCache 一旦真正用到就报。处理:装 cachecontrol[filecache],或改用内存缓存(DictCache)—— 但后者跨进程不共享,别用它验证「另一个进程有没有命中」。
症状四:条件请求一直返回 200 而不是 304。 按可能性排序:ETag 少了引号(第一处)、用了 If-Modified-Since 但本地时间比 Last-Modified 新、Last-Modified 精度只到秒而你的改动在同一秒内完成。判据是先回显自己发出去的头,再回显服务器回的 ETag 原文,逐字节比。
本文的边界
- 真实网络侧只在本站(GitHub Pages 加 Fastly)上测,样本是 11-16 与 11-17 的几篇文章、一个 404 页和
sitemap.xml。Cloudflare、nginx、CloudFront 的默认值不同,不要照搬。 - 客户端侧只测了 CacheControl 0.15.0 加 requests 2.34.2(CPython 3.13.14,Windows 11)。浏览器未测,Service Worker 未测。
- 没有覆盖 Range 请求与
If-Range、HTTP/3、stale-if-error、private与共享缓存的分野。 - 第二处的结论是解码推断,我没有权限修改线上文件的 mtime 去制造「同秒同体积」的碰撞。
本文不含任何联盟推广链接。
常见问题
Q:no-cache 是不是告诉浏览器「别缓存」?
不是。它是「存下来,但每次用之前必须问我」。真正让缓存不落盘的是 no-store —— 实测里它每次请求都拿到不同 body,而 no-cache 三次请求都在用第一份 body。名字起反了,是这条指令最常见的误读来源。
Q:改了 CSS 但文件名没变,怎么让所有人拿到新的?
最稳的是改文件名(带内容哈希)加 immutable;不想改文件名就至少给 max-age 一个短值并保留 ETag,让缓存每次回源验证。最不可靠的是加查询串 —— 在本站实测中缓存键不含查询串,加了等于没加。
Q:304 会让 CDN 上的 max-age 重新计时吗?
分两层看。CDN 侧实测 304 响应里 Age 是继续递增的(26 到 27),它记的是对象年龄,不会因为一次 304 归零。客户端侧按 RFC 9111 的 4.3.4 节用 304 的头部更新已存响应,新鲜度从这次验证重新起算。把两者混起来算,就会得出「缓存每 10 分钟自动永久续命」这种不成立的结论。
Q:为什么本地预览好好的,线上就是旧版?
因为本地 python -m http.server 根本不发 Cache-Control,浏览器走启发式估算,通常当场就过期、每次都问;而线上明写 max-age=600,十分钟内不问。两边策略不同,症状自然不同。排查从 curl -sI 开始,不要从清浏览器缓存开始。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。