Nginx缓存浏览器X-Cache-Status始终返回MISS问题求助

问题描述 #

正在学习使用Nginx缓存Next.js的API接口，配置如下：

worker_processes 1;

events {
    worker_connections 1024;
}

http {
    proxy_cache_path /tmp/nginx/cache levels=1:2 keys_zone=portfolio:10m max_size=1g inactive=60m use_temp_path=off;

    server {
        listen 2300;
        server_name localhost;

        # Default route - no caching
        location / {
            proxy_pass http://localhost:3000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
        
        # API routes with caching
        location /api/ {
            proxy_pass http://localhost:3000/api/;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            
            # Cache configuration
            proxy_cache portfolio;
            proxy_cache_methods GET HEAD;
            proxy_cache_key "$request_uri";
            proxy_cache_valid any 10m;
            proxy_cache_lock on;
            proxy_cache_lock_age 10s;
            proxy_cache_lock_timeout 3s;
            add_header X-Cache-Status $upstream_cache_status;
            add_header Cache-Control "public, max-age=600";
        }
    }
}

当前现象：

• curl请求时，首次请求后X-Cache-Status正常显示HIT；
• 从响应时间缩短、Next.js无API调用可判断缓存实际生效；
• 但浏览器中X-Cache-Status始终显示MISS，仅偶尔部分API显示HIT且不稳定。

解决办法 #

1. 验证是否是浏览器本地缓存拦截了请求 #

当浏览器本地缓存生效时，会直接读取本地数据，不会向Nginx发起新请求，因此不会获取到Nginx返回的X-Cache-Status头。可以通过以下方式验证：

• 打开浏览器开发者工具（F12），在Network标签勾选Disable cache，重新请求API查看X-Cache-Status；
• 或者按Ctrl+F5强制刷新页面，绕过浏览器本地缓存。

2. 统一缓存键，处理Vary头影响 #

如果Next.js上游返回Vary头（比如Vary: Cookie），Nginx会自动将Vary指定的头字段加入缓存键，导致不同请求头生成不同的缓存条目，出现HIT不稳定的情况：

• 若不需要区分这些请求（比如API不需要用户个性化内容），可以在Nginx的location /api/块中添加：

  proxy_ignore_headers Vary;
  

• 若需要区分请求头，修改proxy_cache_key包含对应字段，比如：

  proxy_cache_key "$request_uri$http_cookie";
  

3. 强制覆盖上游的Cache-Control头 #

Nginx的add_header默认不会覆盖上游已存在的Cache-Control头，如果Next.js返回的Cache-Control是private或短时效指令，会导致浏览器缓存策略和Nginx不一致：

• 在location /api/块中添加以下配置，先隐藏上游的Cache-Control，再添加自定义的缓存策略：

  proxy_hide_header Cache-Control;
  add_header Cache-Control "public, max-age=600";
  

4. 检查缓存目录权限与缓存配置 #

• 确保/tmp/nginx/cache目录的所有者是Nginx运行用户（通常是www-data或nginx），拥有读写权限，避免缓存无法正常写入；
• 可以适当调整proxy_cache_valid的时效，比如延长至30m，减少缓存失效频率。

内容的提问来源于stack exchange，提问作者Mahmud Araf