在 nginx 中配置按 http 状态码设置不同的缓存有效期,核心做法是利用 map 指令将响应状态码映射为具体的过期时间变量,随后在 location 块中使用 add_header cache-control 引用该变量。这样,nginx 会根据实际返回的状态码动态生成 cache-control 头部,实现细粒度的缓存控制。

如何定义状态码到时间的映射关系
要实现这一功能,第一步是建立状态码与缓存时长的映射表。这需要在 http 上下文(通常在 nginx.conf 或独立的 .conf 文件中)使用 map 指令。我们创建一个变量(例如 $cache_ttl),其值取决于上游服务器返回的状态码 $upstream_status。对于常见的成功状态码如 200 和 301,可以设置较长的缓存时间;而对于错误状态码如 404 或 500,则应设置为 0 以禁止缓存。
map $upstream_status $cache_ttl {
default 0;
200 3600;
301 86400;
404 60;
500 0;
}上述配置中,default 0 确保未明确列出的状态码默认不缓存。单位默认为秒。定义好映射后,Nginx 内部就拥有了一个根据状态码实时计算的 TTL 值。

如何在 Location 中应用映射结果
定义好映射变量后,下一步是在处理请求的 location 块中应用它。关键在于使用 add_header 指令来添加 Cache-Control 头部。需要注意的是,add_header 默认只在响应状态码为 200、204 和 301-304 时生效。如果希望错误页面也携带特定的缓存头,必须显式指定 always 参数。
server {
listen 80;
server_name example.com;
location /api/ {
proxy_pass http://backend_servers;
# 应用之前定义的 cache_ttl 变量
add_header Cache-Control "max-age=$cache_ttl";
# 确保所有状态码都添加此头部
add_header Cache-Control "max-age=$cache_ttl" always;
}
}在实际测试中,当请求返回 200 OK 时,响应头将包含 Cache-Control: max-age=3600;若返回 404 Not Found,则包含 Cache-Control: max-age=60。这种机制允许前端浏览器或中间代理根据状态码智能决定缓存策略,减少无效资源的重复下载。

如何处理 Proxy Cache 与 Header 缓存的冲突
当 Nginx 同时开启了 proxy_cache(服务端缓存)和基于状态码的 Cache-Control(客户端/代理缓存)时,需要特别注意两者的交互逻辑。服务端缓存的有效期由 proxy_cache_valid 控制,而客户端缓存由 add_header 控制。如果两者不一致,可能导致用户看到过期的服务端数据,或者浏览器拒绝刷新已缓存的资源。
最佳实践是保持两者逻辑一致或让服务端缓存更严格。例如,如果服务端缓存只保留 200 状态码 10 分钟,那么客户端的 max-age 不应超过这个时间,否则浏览器可能从本地读取旧数据,而服务端已更新。可以通过以下配置验证这一行为:
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m;
server {
location /api/ {
proxy_pass http://backend;
proxy_cache my_cache;
# 服务端缓存:仅缓存 200 和 302,时长 10 分钟
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
# 客户端缓存:与服务端保持一致
add_header Cache-Control "max-age=$cache_ttl" always;
}
}在此配置下,如果后端返回 200,Nginx 会缓存该响应 10 分钟,并告知客户端缓存 10 分钟。如果后端返回 404,Nginx 缓存 1 分钟,客户端也缓存 1 分钟。这种同步确保了缓存的一致性和有效性,避免了因缓存层级不同步导致的脏数据问题。


















