Nginx 中怎么配置 proxy_cache 结合 X-Proxy-Cache 响应头输出状态-Nginx-PHP中文网

在Nginx中启用proxy_cache并显示X-Proxy-Cache响应头需四步：1. http块定义proxy_cache_path；2. location中配置proxy_cache、proxy_cache_key等；3. 用add_header X-Proxy-Cache $upstream_cache_status输出状态；4. 重载验证HIT/MISS/BYPASS等值。

nginx 中怎么配置 proxy_cache 结合 x-proxy-cache 响应头输出状态

在 Nginx 中启用 proxy_cache 并通过 X-Proxy-Cache 响应头显示缓存状态（如 HIT、MISS、BYPASS），是调试和监控反向代理缓存行为的常用手段。关键在于正确配置缓存区域、设置缓存键、启用响应头注入，且注意该头默认不输出，需手动添加。

1. 定义 proxy_cache 区域和基础缓存参数

在 http 块中声明共享内存缓存区，并设置基本缓存策略：

proxy_cache_path /var/cache/nginx/proxy_cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;

keys_zone=my_cache:10m：定义名为 my_cache 的共享内存区，10MB 可存储约 8 万条缓存键
inactive=60m：缓存项 60 分钟未被访问则自动清理
use_temp_path=off：避免临时文件写入，提升性能

2. 在 location 中启用缓存并设置缓存键

在需要缓存的 location 块中启用缓存，并确保缓存键能区分不同请求（尤其注意 GET 参数、请求头）：

location / {
    proxy_pass https://upstream_backend;
    proxy_cache my_cache;
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404 1m;
    proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
<pre class="brush:php;toolbar:false;"># 确保缓存键包含关键变量（如 Host、URI、部分请求头）
proxy_cache_key "$scheme$request_method$host$request_uri$http_accept_encoding";

# 可选：忽略某些请求头对缓存的影响（如 Cookie、Authorization）
proxy_ignore_headers Cache-Control Expires Set-Cookie;
proxy_cache_bypass $http_cache_control $arg_nocache;

}

proxy_cache_key 需稳定且具区分度；若后端依赖 Cookie 或 Authorization，通常应显式忽略或剔除，否则易导致缓存污染
proxy_cache_bypass 允许客户端通过请求头（如 Cache-Control: no-cache）或参数（如 ?nocache=1）绕过缓存

3. 添加 X-Proxy-Cache 响应头输出缓存状态

Nginx 不会自动输出缓存状态，需用 add_header 结合内置变量 $upstream_cache_status 实现：

aperture: the L402 aware reverse proxy

安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。

下载

location / {
    # ... 上述 proxy_cache 相关配置 ...
<pre class="brush:php;toolbar:false;"># 输出缓存状态到响应头
add_header X-Proxy-Cache $upstream_cache_status;

# （可选）仅对非 2xx/3xx 响应隐藏该头，或按需限制
# add_header X-Proxy-Cache $upstream_cache_status always;

}

$upstream_cache_status 取值包括：HIT（命中）、MISS（未命中）、BYPASS（被 proxy_cache_bypass 绕过）、EXPIRED（过期但尝试更新）、STALE（使用陈旧缓存）、UPDATING（后台更新中）、REVALIDATED（验证后刷新）
add_header ... always 可确保即使返回 304 或错误状态码也输出该头（默认只对 2xx/3xx 生效）

4. 验证与常见注意事项

配置完成后重载 Nginx（nginx -s reload），用 curl 测试：

curl -I https://example.com/
# 查看响应头中是否含：X-Proxy-Cache: HIT 或 MISS

首次请求通常是 MISS，再次请求同 URL 应为 HIT（前提响应头允许缓存、无 Set-Cookie 等禁止缓存字段）
若始终为 MISS，检查后端响应是否含 Cache-Control: private、no-store，或 Nginx 是否因 Set-Cookie 自动禁用缓存（默认行为）
BYPASS 表示请求匹配了 proxy_cache_bypass 条件，例如带 Cache-Control: no-cache 头或 ?nocache=1
确保后端响应有明确的 Cache-Control 或使用 proxy_cache_valid 强制缓存时间，否则 Nginx 默认不缓存

这样配置后，X-Proxy-Cache 就能清晰反映每次请求的缓存决策结果，便于排查缓存失效、命中率低等问题。