同一个请求,Nginx 其实有两次机会不去打扰后端:第一次是浏览器自己手里有缓存,连 Nginx 都不问;第二次是 Nginx 手里有缓存,问一句就直接回。两层缓存各管一段路,规则也各不相同——浏览器缓存由响应头说了算,代理缓存由 Nginx 的 proxy_cache 指令说了算。把这两本账分开记,缓存才不会变成「有时候快、有时候串数据」的玄学。这篇先把双层结构画出来,再逐条讲 proxy_cache_path、proxy_cache_key、proxy_cache_valid 三个核心指令,随后讲命中状态、防击穿、浏览器缓存与清理办法。反向代理的基础写法在第 2 篇《Nginx 反向代理深挖:proxy_pass 的斜杠、头传递与缓冲取舍》里已经讲过,这篇默认你已经会配 proxy_pass 与 upstream。
双层缓存长什么样
请求从浏览器出发,到拿到响应为止,会经过两道缓存关卡。第一道在浏览器:资源带了 Cache-Control: max-age=... 或 Expires,且没过期,浏览器直接用本地副本,连请求都不发。第二道在 Nginx:请求到了 Nginx,proxy_cache 先按 key 查磁盘缓存,命中且未过期就直接返回,不再回源;没命中或已过期才去找上游,拿到响应后按规则写一份进缓存再返回。
图注:双层缓存结构与命中路径——浏览器缓存与 Nginx 代理缓存各管一段路,MISS 时才回源。
两层缓存的失效语义完全不同:浏览器缓存过期了,浏览器会重新发请求;Nginx 缓存过期了,Nginx 会重新回源。它们之间没有自动同步——Nginx 缓存里明明还是旧内容,浏览器也可能因为自己的缓存没过期而继续用更旧的内容。调缓存之前先想清楚:你要控制的是哪一层。
proxy_cache_path:先把缓存落在哪、占多大说清楚
代理缓存的第一条指令是 proxy_cache_path,它只能写在 http 块里,定义缓存落盘的位置和清理策略:
http { proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=10g inactive=60m use_temp_path=off;}五个参数各有分工:
| 参数 | 含义 |
|---|---|
levels=1:2 | 缓存文件按 key 的哈希分两级子目录存放,避免单个目录下文件过多拖慢文件系统 |
keys_zone=my_cache:10m | 共享内存区的名和大小,存所有缓存条目的元数据(key、过期时间等);1MB 大约能存 8000 个 key |
max_size=10g | 磁盘缓存上限,超过后由 cache manager 按 LRU 淘汰最久未用的文件 |
inactive=60m | 一份缓存超过这么久没被访问就删掉,不管它原本的有效期还有多久 |
use_temp_path=off | 响应直接写进缓存目录,不先写临时目录再搬运,少一次磁盘拷贝 |
inactive 和有效期是两回事:有效期(proxy_cache_valid)决定「过期后要不要重新回源验证」,inactive 决定「多久没人问就从磁盘上删掉」。一份缓存可能有效期是 10 分钟,但 60 分钟没人访问才会被清理;也可能有效期是 1 天,但 60 分钟没人访问就被删了——下次再有人问,就得重新回源。keys_zone 太小会直接限制能缓存的条目数,缓存没满、内存区先满了,表现就是命中率上不去,查问题时先看这行。
WARNING
proxy_cache_path的目录必须让 Nginx worker 进程可写,且不要放在/tmp这类会被系统定时清理的路径下。目录权限或磁盘空间出问题时,Nginx 不会报错退出,只会默默不缓存——请求照常回源,你看到的现象是「缓存配了却一个 HIT 都没有」。
proxy_cache_key:缓存的 key 决定了什么算「同一个请求」
proxy_cache 默认只缓存 GET 与 HEAD 请求。开缓存的第二步,是在 server 或 location 里启用它并定 key:
proxy_cache my_cache;proxy_cache_key $scheme$proxy_host$request_uri;上面这行就是 Nginx 的默认 key:协议 + 上游 host + 完整请求 URI(含查询串)。默认 key 有两个常见坑。第一,查询串会进 key:?utm_source=wechat 和 ?utm_source=weibo 会被当成两个不同的缓存条目,同一个页面被各种推广参数冲出几十份重复缓存。第二,key 里没有 Cookie、没有请求头,意味着登录用户和游客拿到的可能是同一份缓存——这正是下面要讲的红线。
定制 key 的思路是:把区分内容的维度放进 key,把不区分内容的维度拿掉。只按路径区分的页面可以这样写:
proxy_cache_key $scheme$proxy_host$uri;需要按语言区分的,再把相关请求头或参数拼进去:
proxy_cache_key $scheme$proxy_host$uri$is_args$arg_lang;key 越粗,命中率越高,但串数据的风险也越大;key 越细,越安全,但缓存越碎。定 key 之前先问自己一句:这份响应的内容到底由哪些东西决定?答案里的每一项都应该进 key,答案之外的东西都不应该进。
proxy_cache_valid:按状态码设有效期
默认情况下,Nginx 只在上游响应带了明确的 Expires 或 Cache-Control: max-age 时才缓存,而且按那个时长来算过期。很多后端根本不发这些头,这时就得用 proxy_cache_valid 自己定:
proxy_cache_valid 200 302 10m;proxy_cache_valid 404 1m;proxy_cache_valid any 1m;三行的意思是:200 和 302 缓存 10 分钟,404 缓存 1 分钟,其他状态码缓存 1 分钟。404 也值得缓存一小会儿——否则爬虫扫不存在的路径时,每次都要打到后端。优先级上,上游响应里的 X-Accel-Expires 头会覆盖 proxy_cache_valid;上游的 Cache-Control: max-age 同样优先于它。也就是说,proxy_cache_valid 是「上游没表态时」的兜底,不是最高指令。
还有两个配套指令值得一起配上。proxy_cache_min_uses 2; 表示一个 key 被请求两次以上才写入缓存,能挡住一次性扫过的大量冷门 URL 把缓存区冲满。proxy_cache_revalidate on; 则让过期后的回源带上条件请求(If-Modified-Since / If-None-Match),上游回 304 时 Nginx 直接续用旧缓存,省一次完整传输。
命中状态:先把 X-Cache-Status 立起来
缓存配完第一件事不是调参数,而是让命中状态看得见。加一个响应头:
add_header X-Cache-Status $upstream_cache_status;$upstream_cache_status 的取值是一张状态表,排障时按表查:
| 状态 | 含义 |
|---|---|
| HIT | 缓存命中,直接返回 |
| MISS | 缓存里没有,回源并按规则写入缓存 |
| EXPIRED | 缓存过期,回源取新内容 |
| STALE | 缓存过期但按 proxy_cache_use_stale 返回了旧内容 |
| UPDATING | 缓存过期,正在回源更新,其他请求按 proxy_cache_lock 在等 |
| BYPASS | 请求被 proxy_cache_bypass 绕过缓存 |
| REVALIDATED | 条件请求得到 304,旧缓存续用 |
注意 add_header 写在 location 里会覆盖从上层继承的所有 add_header,如果上层还加了别的安全头,需要在同一个 location 里一并重写一遍。$upstream_cache_status 只在经过 proxy_pass 的请求上有值,直出静态文件的 location 里它是空的。
缓存判定全流程:一个请求在缓存里走哪条路
把上面几节串起来,一个请求在 Nginx 缓存里的完整判定流程是下面这样:
图注:Nginx 缓存判定流程——方法与 bypass 先过滤,命中直接返回,未命中回源后再决定是否写入。
PPT 式把这个流程再拆成五步,每一步对应一个检查点:
第 1 步:方法过滤。 只有 GET 与 HEAD 请求会进缓存逻辑,POST、PUT、DELETE 默认直接回源,既不查也不写。proxy_cache_methods 可以改这个默认值,但改之前要想清楚:把 POST 的响应缓存下来,等于把「提交一次表单」的结果发给所有后来的人。
第 2 步:bypass 检查。 proxy_cache_bypass 命中的请求会跳过缓存直接回源,proxy_no_cache 命中的请求回源后不写入缓存。两者常配合 Cookie 或参数使用,例如登录用户带了 nocache Cookie 就绕过缓存:
proxy_cache_bypass $cookie_nocache $arg_nocache;proxy_no_cache $cookie_nocache $arg_nocache;第 3 步:按 key 查缓存。 key 命中且未过期,直接返回,状态 HIT;key 不存在是 MISS;key 存在但过期了是 EXPIRED。查不到或过期了都进入回源分支。
第 4 步:响应可缓存性检查。 回源后,Nginx 按响应状态码和响应头决定写不写缓存。默认不缓存的响应包括:带 Set-Cookie 的响应、Cache-Control 含 private、no-store 或 no-cache 的响应。想强制缓存这类响应要用 proxy_ignore_headers,但那等于亲手关掉安全阀——除非你清楚自己在做什么,否则别动这一行。
第 5 步:写入与返回。 可缓存的响应先写磁盘缓存再返回;不可缓存的只返回不写。回源失败时,如果配了 proxy_cache_use_stale,Nginx 可以拿过期的旧内容先顶上:
proxy_cache_use_stale error timeout invalid_header updating http_500 http_502 http_503 http_504;proxy_cache_background_update on;proxy_cache_background_update on 的意思是:过期后第一个请求触发后台回源更新,其他请求先拿旧内容,不用排队等。这对读多写少的页面很友好,但要配合 updating 一起用——否则后台更新期间的其他请求可能直接穿透到后端。
缓存击穿:过期那一秒,所有请求一起回源
热门页面的缓存刚过期那一刻,如果同一秒涌进来几百个请求,默认行为是它们全部打到后端——这就是缓存击穿。proxy_cache_lock 的作用是让同一 key 的过期回源只放行一个请求,其他请求等着:
proxy_cache_lock on;proxy_cache_lock_timeout 5s;proxy_cache_lock_age 5s;proxy_cache_lock_timeout 是等待上限,超过还没拿到新内容就直接回源,不再等;proxy_cache_lock_age 是上一个回源请求超过多久还没返回,就放下一个请求也去回源,避免第一个请求挂死导致所有人无限等待。锁的粒度是 key,锁住 A 页面不影响 B 页面。
微缓存是另一个思路:给本来「动态」的内容也设一个很短的有效期,比如 1 秒:
proxy_cache_valid 200 1s;高并发下,同一秒内的几百个请求只打一次后端,剩下 999 个都命中缓存。内容延迟最多 1 秒,对列表页、热搜这类场景完全可以接受。微缓存的本质是拿 1 秒的延迟换几百倍的回源削减,代价小、收益大,是动态站最划算的一行配置。
浏览器缓存:expires 与版本化文件名
代理缓存管的是 Nginx 到后端这一段,浏览器缓存管的是浏览器到 Nginx 这一段。静态资源的浏览器缓存用 expires 指令:
location ~* \.(jpg|jpeg|png|gif|css|js|woff2)$ { expires 30d; access_log off;}expires 30d 会同时发 Expires 与 Cache-Control: max-age=2592000 两个头。注意 expires 与 add_header Cache-Control 不要在同一个 location 里混用,两者都会写 Cache-Control,结果是发出去两个值,浏览器按哪个算要看实现,等于把决定权交了出去。
浏览器缓存真正好用的形态是「长缓存 + 文件名带哈希」:构建时把 app.js 输出成 app.a3f9c2.js,内容一变文件名就变,旧文件永远不会被错拿。这时可以放心给一年:
location ~* \.[0-9a-f]{8}\.(css|js)$ { expires 1y; add_header Cache-Control "public, immutable";}immutable 告诉浏览器:这个 URL 的内容永远不会变,连条件请求都别发。没带哈希的文件名千万别加 immutable,否则改了内容用户也拿不到新文件,只能等缓存自然过期或者手动清浏览器缓存。ETag 与 Last-Modified 默认是开着的,浏览器缓存过期后会带条件请求回来验证,命中 304 就不用重新下载全文——这是浏览器缓存的第二道防线。
Cloudflare 那一层的缓存规则是另一个维度的玩法,边缘节点的缓存策略见《Cloudflare 缓存规则》。Nginx 这一层与 CDN 层的区别在于:CDN 缓存面向全球访客,Nginx 缓存面向回源请求,两者可以叠加,但失效与清理要分开算。
缓存清理的现实办法
缓存最大的麻烦不是建,是清。Nginx 开源版没有像商业版那样的缓存清理 API,现实中可用的办法按从常用到少用排:
| 办法 | 做法 | 适用场景 |
|---|---|---|
| 改文件名 / 改路径 | 静态资源换带新哈希的文件名,或换 URL | 静态资源更新,首选 |
proxy_cache_bypass | 带特定参数或 Cookie 的请求绕过缓存 | 单个页面紧急刷新 |
| 换 key 前缀 | proxy_cache_key 里加版本号,发布时改版本号 | 整站内容大改版 |
| 删缓存目录文件 | 直接删 /var/cache/nginx 下对应文件后重载 | 兜底手段,事后要确认 key 的哈希路径 |
| 第三方 purge 模块 | 编译 ngx_cache_purge 模块,加 proxy_cache_purge 指令 | 需要编译进 Nginx,不推荐新手碰 |
| Nginx Plus | 商业版自带 purge API | 有商业版授权时才有 |
开源版没有 purge 接口是官方文档明确写清的事实,不要指望靠重启 Nginx 清缓存——重启不会删磁盘上的缓存文件,起来之后旧内容照样命中。真正可靠的清理策略是在设计期就留好:静态资源走哈希文件名,页面内容走短有效期 + proxy_cache_bypass 的紧急通道,整站大改版走 key 前缀版本号。
排障小节:缓存不生效的五种常见原因
1. 配了缓存却一个 HIT 都没有。 先看响应头:上游回了 Set-Cookie 或 Cache-Control: private,默认就不缓存。再看请求方法:POST 请求本来就不进缓存。最后看 proxy_cache_path 的目录权限与磁盘空间,写不进盘的缓存等于没配。
2. 登录用户串了数据。 匿名页与登录后页面共用同一个 key,登录用户看到的是游客的缓存页,或者反过来。解法是把登录态排除在缓存之外:proxy_no_cache 与 proxy_cache_bypass 按登录 Cookie 生效,或者直接给登录后的 location 关掉 proxy_cache。:::warning
带登录态、带个人信息的响应绝不能进共享缓存。一份缓存错发给陌生人,泄露的就是别人的账号信息,事后删缓存也收不回已经发出的数据。
:::
3. 缓存了不该缓存的错误页。 proxy_cache_valid any 1m 会把 500 错误也缓存一分钟,等于把一次后端故障放大成一分钟的故障。proxy_cache_valid 按状态码分开写,错误码给极短有效期或不写进去;配合 proxy_cache_use_stale,回源失败时宁可返回旧的正确内容,也别缓存新的错误内容。
4. 缓存过期后后端被打垮。 热门页面过期瞬间大量回源,先确认 proxy_cache_lock 开了没有,再看 proxy_cache_background_update 是否配合 updating 使用。如果后端本身就扛不住单次回源的并发,锁也救不了——这时应该先上微缓存,把回源频率压到每秒一次。
5. 磁盘被缓存占满。 max_size 没设或设得太大,cache manager 淘汰跟不上写入速度,磁盘写满后 Nginx 照常服务但新缓存写不进去。查 df 与缓存目录大小,max_size 按磁盘实际余量设,并留出余地;inactive 太长会让冷门内容长期占盘,太短又让缓存频繁失效,按访问规律调。
小结
Nginx 缓存是两本账:proxy_cache 管 Nginx 到后端,浏览器缓存管浏览器到 Nginx。配代理缓存抓住三条主线——proxy_cache_path 定落盘与清理策略,proxy_cache_key 定什么算同一个请求,proxy_cache_valid 定按状态码的有效期;再用 X-Cache-Status 把命中状态立起来,proxy_cache_lock 与微缓存防击穿,proxy_cache_use_stale 兜底回源失败。浏览器缓存抓住一条主线:长缓存只给带哈希文件名的静态资源,动态内容靠短有效期与条件请求。清理没有银弹,开源版没有 purge 接口,设计期留好哈希文件名、bypass 通道与 key 版本号,比事后删文件可靠得多。下一篇讲 HTTPS 方向:TLS 调优、OCSP 装订与 HTTP/3 的开启条件。