Nginx中proxy_cache_valid按状态码分组设置缓存时间,具体状态码优先于any,后出现的同码配置覆盖前者;需配合proxy_cache_path、proxy_cache及可缓存响应头才生效。

直接在 location 或 server 块中写多条 proxy_cache_valid 指令,每条指定一组状态码和对应时间,Nginx 会按匹配优先级生效——更具体的状态码优先于 any,后出现的同状态码配置会覆盖前面的。
按状态码分组设置缓存时间
这是最常用也最清晰的方式。你可以为不同业务意义的响应码分别设定时长:
-
proxy_cache_valid 200 301 302 10m;→ 成功响应和重定向,通常内容稳定,适合较长时间缓存 -
proxy_cache_valid 404 30s;→ 资源不存在,缓存太长会导致“假 404”,建议控制在秒级 -
proxy_cache_valid 500 502 503 504 10s;→ 后端故障类错误,短时缓存可缓解雪崩,但不宜过久 -
proxy_cache_valid any 5s;→ 作为兜底,确保所有未显式声明的状态码也有默认缓存期(注意:它不会覆盖上面已定义的状态码)
利用层级覆盖实现精细控制
Nginx 允许在不同作用域重复使用 proxy_cache_valid,且以**最近的作用域为准**。例如:
- 在
http块设全局基础策略:proxy_cache_valid 200 5m; any 1m; - 在某个
location /api/中覆盖:proxy_cache_valid 200 30s; 500 5s; - 结果是:该 API 下的 200 缓存 30 秒,500 缓存 5 秒;其他未覆盖的状态码仍走
http块里的any 1m
必须配套的关键配置
单独写 proxy_cache_valid 不起作用,以下三项缺一不可:
-
定义缓存区:在
http块中用proxy_cache_path创建缓存存储和共享内存区,如keys_zone=my_cache:10m -
启用缓存区:在
location中用proxy_cache my_cache显式调用该区域 -
响应本身可被缓存:上游返回不能带
Cache-Control: no-cache、private或Set-Cookie(除非用proxy_ignore_headers Set-Cookie忽略)
验证是否生效的小技巧
加一行头信息方便调试:add_header X-Cache-Status $upstream_cache_status;。重启 Nginx 后访问接口,查看响应头:
-
HIT表示命中缓存,且未过期 -
MISS表示未命中(可能因首次请求、缓存未建或 key 不匹配) -
EXPIRED表示缓存存在但已超时,Nginx 正在后台更新(需配合proxy_cache_use_stale updating才能返回旧内容)


















