← 返回首页

HTTP 缓存语义:Cache-Control 与 ETag 带来的八处静默分歧

HTTP 缓存Cache-ControlETag

静态站的缓存问题从来不出错。它只是让你把一份改过的文件重新发一遍、让读者刷新三次还是看到旧的、让你在发布后第五分钟去抽查页面、看到 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 缺一行,缓存就会把中文页交给英文读者。

// FLOW_01从响应头到客户端行为:本文的核对顺序6 NODES01STEP_01curl -sI 取真实响应头02STEP_02拆 Cache-Control / ETag / Vary / Age03STEP_03构造 If-None-Match 条件请求04STEP_04看是 304 还是 200 全量05STEP_05换 CacheControl 客户端再跑一遍06STEP_06数回源次数与 body 版本END_OF_FLOW
从响应头到客户端行为:本文的核对顺序 · 依据本文步骤自绘示意图
响应头到客户端缓存行为的八个分岔点 概念图
响应头到客户端缓存行为的八个分岔点 概念图 · 依据本文主题生成的示意图
PythonGitGitHubJson
文中涉及的技术标识 · 图标来自 Simple Icons(CC0)

先把一个真实响应拆开

拿本站任意一篇已发布文章,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"3040 字节
If-None-Match: 6afb7521-14e48(去掉引号)20085,576 字节
If-None-Match: W/"6afb7521-14e48"3040 字节
If-None-Match: "deadbeef-1"20085,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

同一篇文章,加不加 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 + ETag220第 1 次 NOSTORE 1,第 2 次 NOSTORE 2
Cache-Control: no-cache + ETag332三次都是 NOCACHE 1
Cache-Control: max-age=0, must-revalidate + ETag221两次都是 MAXAGE0 1
Cache-Control: max-age=3600, immutable + ETag210两次都是 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=03每次都回源,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 次回源
不发 VaryLANG=zh FIRST=TrueLANG=zh FIRST=True0 次(命中缓存)
发 VaryLANG=zh FIRST=TrueLANG=en FIRST=False1 次

不发 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.getstatus_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 原文,逐字节比。

本文的边界

本文不含任何联盟推广链接。

常见问题

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 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页