nginx http代理缓存过期逻辑需多参数协同:先用proxy_cache_valid显式定义各响应码有效期,再通过proxy_cache_use_stale updating配合proxy_cache_background_update实现过期后秒级返回旧内容并后台更新,启用proxy_cache_lock防并发回源,并用x-cache-status头验证命中状态。

在 Nginx 中配置 HTTP 代理缓存过期逻辑,核心是控制“缓存什么时候失效”和“失效后怎么应对”,不是只设一个时间就完事。它依赖多个参数协同工作,缺一不可。
明确设置响应码对应的有效期(proxy_cache_valid)
这是整个过期机制的起点。Nginx 不会凭空知道某个响应该缓存多久,必须显式声明。
- 对常见成功响应,例如:
proxy_cache_valid 200 301 302 10m;表示这些状态码的响应缓存 10 分钟 - 对错误或缺失响应,建议单独设短周期,例如:
proxy_cache_valid 404 30s;避免无效内容长期占位 - 兜底规则可加:
proxy_cache_valid any 1m;,防止漏配状态码导致不缓存
启用过期后返回旧内容的能力(proxy_cache_use_stale updating)
仅设有效期还不够。默认情况下,缓存一过期,Nginx 就会阻塞等待回源,用户得等新响应回来才能看到页面。要实现“秒级返回旧内容 + 后台悄悄更新”,必须打开 stale 更新通道。
- 关键配置:
proxy_cache_use_stale updating error timeout http_500 http_502 http_503 http_504; - 其中 updating 是强制项,没有它,后台更新根本不会触发,用户也会卡住
- 搭配
proxy_cache_background_update on;才能真正启动后台刷新任务
防止并发回源压垮上游(proxy_cache_lock)
高并发场景下,大量请求同时击中同一个过期缓存 key,若不做限制,可能瞬间发起几十个相同回源请求。
- 开启锁:
proxy_cache_lock on;确保同一 key 只有一个请求真正回源 - 设超时:
proxy_cache_lock_timeout 5s;锁等待超过 5 秒就放弃,走 stale 路径返回旧内容 - 可选防抖:
proxy_cache_lock_age 15s;锁释放后 15 秒内禁止新更新,避免反复刷新
验证是否生效(X-Cache-Status 响应头)
上线后不能只看配置有没有报错,得靠真实响应确认行为是否符合预期。
- 加一行:
add_header X-Cache-Status $upstream_cache_status; - 观察响应头:
X-Cache-Status: HIT(新鲜命中)、STALE(返回过期内容并后台更新)、MISS(未命中,正常回源) - 配合日志调试:开启
error_log ... debug;,搜索resolving或cache miss关键字,确认刷新节奏与配置一致











