proxy_cache_valid 是 nginx 主动控制反向代理缓存有效期的核心指令，仅设定不同状态码的本地缓存时长，必须配合 proxy_cache_path、proxy_cache 和可缓存响应三者才能生效，且需按状态码语义分层配置、置于启用缓存的 location 块内。

直接为不同 HTTP 状态码单独写 proxy_cache_valid 指令，是最可靠、最易维护的方式。它不依赖后端响应头，由 Nginx 主动控制本地缓存寿命，但必须满足三个硬性前提：已定义 proxy_cache_path、所在 location 启用了 proxy_cache、且上游响应本身可被缓存（例如不含 Set-Cookie 或 Cache-Control: no-cache）。

按状态码语义分层设置有效期

不同状态码代表完全不同的业务含义，缓存时间理应区别对待：

• 200 / 301 / 302：成功响应或重定向，资源稳定，适合中长期缓存。例如：proxy_cache_valid 200 301 302 7d;
• 404：资源暂不可用，缓存太长会掩盖新上线内容，建议极短周期，如：proxy_cache_valid 404 1m;
• 500 / 502 / 503 / 504：后端故障类错误，缓存几秒即可缓解雪崩，例如：proxy_cache_valid 500 502 503 504 10s;
• 304：表示未修改，Nginx 不写新缓存，而是复用并刷新原缓存过期时间，设为：proxy_cache_valid 304 24h;
• any：仅作兜底，覆盖未显式声明的状态码（如 403、429），但不能替代明确配置，例如：proxy_cache_valid any 5s;

必须写在启用缓存的 location 块内

该指令不具备继承性，脱离上下文即失效：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

• 写在 server 或 http 块顶层？会被忽略
• 写在没配 proxy_cache my_cache; 的 location？不生效
• 正确位置示例：
    location /static/ {
      proxy_cache static_cache;
      proxy_cache_valid 200 1h;
      proxy_cache_valid 404 30s;
      proxy_pass https://cdn.example.com;
    }

注意顺序与覆盖逻辑

Nginx 按照配置顺序匹配，更具体的规则优先，同状态码后出现的会覆盖前面的：

• 若 http 块设了 proxy_cache_valid 200 5m;，而某个 location 内又写了 proxy_cache_valid 200 30s;，则该路径下以 30 秒为准
• 同一 location 中多次写 proxy_cache_valid 200，只有最后一条生效
• 避免混用模糊写法（如 proxy_cache_valid 200 302 10m;）和精细写法（如分开写 301 和 302），否则易引发预期外覆盖

配合关键指令确保真正生效

光设时间不够，还需协同其他配置：

• 用 proxy_ignore_headers Cache-Control Set-Cookie; 强制忽略后端禁止缓存的响应头
• 用 proxy_cache_key $scheme$host$request_uri; 避免因 $args 或 $http_user_agent 导致缓存键过于分散
• 对临时重定向 302，需确认是否加了 proxy_ignore_headers Cache-Control;，否则后端返回 no-cache 会绕过你的 proxy_cache_valid
• 搭配 proxy_cache_use_stale error timeout updating http_404; 可在缓存过期或回源失败时，仍返回旧缓存，提升可用性