proxy_cache_valid 失效主因是未匹配响应状态码,默认仅对200/301/302生效;若上游返回206/404等需显式声明,且cache-control: no-cache会覆盖该指令,需配合proxy_ignore_headers禁用。

nginx proxy_cache_valid 配置失效的常见原因
缓存过期时间不生效,大概率不是语法写错,而是 proxy_cache_valid 没匹配到响应状态码。它默认只对 200、301、302 生效,而你的后端返回了 206(断点续传)、404 或自定义 201,那就完全不会缓存——更别说设过期时间了。
实操建议:
- 用
curl -I http://your-upstream看真实响应头里的Status,确认是哪个码 - 显式写出所有要缓存的状态码:
proxy_cache_valid 200 206 301 302 404 10m; - 注意:如果上游返回了
Cache-Control: no-cache或max-age=0,nginx 默认会忽略proxy_cache_valid,需加proxy_ignore_headers Cache-Control Expires; -
proxy_cache_valid的优先级低于Cache-Control,但可被后者覆盖,这点容易误判
CDN边缘节点中 proxy_cache_use_stale 的实用组合
CDN场景下,源站偶发超时或 5xx 是常态,不能让终端用户直接卡住。用 proxy_cache_use_stale 让 nginx 在异常时返回“脏”缓存,比单纯调长 proxy_cache_valid 更有效。
典型配置片段:
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; proxy_cache_background_update on;
说明:
-
updating是关键:当缓存即将过期,后台悄悄刷新,前端仍用旧缓存,避免“缓存雪崩”式回源 -
proxy_cache_background_update on必须开启,否则updating不起作用 - 别滥用
http_404—— 404 缓存太久会导致错误资源长期无法更新 - 该机制对静态资源(JS/CSS/图片)友好,但对带用户态的 API 响应要谨慎,避免缓存了错误身份数据
如何验证缓存是否按预期过期并命中
光看配置没用,得从响应头和日志里找证据。nginx 不会告诉你“这次用了缓存”,但会留下痕迹。
必须检查的三项:
- 响应头中是否有
X-Proxy-Cache: HIT或MISS(需在配置里加add_header X-Proxy-Cache $upstream_cache_status;) - 日志中
$upstream_cache_status变量值:常见的有HIT、MISS、EXPIRED、STALE、BYPASS—— 注意EXPIRED表示缓存存在但已过期,会触发回源;STALE才是用了过期缓存 - 用
curl -I对比两次请求的Date和Age头:Age大于 0 且稳定增长,说明缓存正在生效
小技巧:临时把 proxy_cache_valid 设为 5s,反复刷页面,观察 Age 是否从 0 跳到 5 再跳到 10,能快速验证逻辑链是否打通。
多级缓存下 max-age 与 proxy_cache_valid 的冲突处理
CDN边缘节点常处于多层缓存链中(浏览器 → CDN边缘 → 自建反向代理 → 源站),各层的 Cache-Control: max-age 和 proxy_cache_valid 会互相影响,最常见问题是:源站设了 max-age=3600,但你希望边缘只缓存 10 分钟。
解决路径很明确:
- 在反向代理层用
proxy_hide_header Cache-Control干掉上游的Cache-Control,再用add_header Cache-Control "max-age=600";强制下发 - 或者更稳妥:用
proxy_cache_valid显式覆盖,并配合proxy_ignore_headers Cache-Control确保不被干扰 - 注意:浏览器和中间 CDN(如 Cloudflare)也会读取
Cache-Control,所以仅改 nginx 缓存策略不够,必须控制响应头本身 - 若源站使用了
ETag或Last-Modified,即使缓存过期,nginx 仍可能发条件请求(If-None-Match),此时实际带宽节省有限,需结合proxy_cache_revalidate on判断是否真需要回源
边缘节点性能优化的核心不在“缓多久”,而在“什么时候不该缓”和“缓错了怎么办”。过期时间只是开关,背后的失效策略、降级逻辑和可观测性才是落地难点。











