Nginx 反向代理中配置 proxy_cache_key 缓存键值自定义-Nginx-PHP中文网

自定义 proxy_cache_key 是为精准控制缓存粒度，避免缓存污染与击穿；需结合 Cookie、User-Agent、关键参数等变量，并配合 cache 策略生效。

nginx 反向代理中配置 proxy_cache_key 缓存键值自定义

在 Nginx 反向代理中，proxy_cache_key 决定了哪些请求会被视为“相同”，从而复用缓存内容。默认值是 $scheme$proxy_host$request_uri，但实际业务中往往需要更精细的控制——比如区分登录态、忽略无关参数、适配多端设备等。

为什么要自定义 proxy_cache_key

默认键值不包含 Cookie、User-Agent 或特定查询参数，容易导致缓存污染或缓存击穿。例如：

用户 A 和用户 B 请求同一 URL，但返回内容不同（如个人中心页），若未纳入 Cookie 或 token，Nginx 可能错误地将 A 的响应返回给 B；
带跟踪参数（如 ?utm_source=weibo）的链接大量涌入，若全量计入 key，会大幅降低缓存命中率；
移动端和桌面端返回不同 HTML，但 URL 相同，需靠 $http_user_agent 区分。

常用变量组合与写法示例

支持所有 Nginx 内置变量和自定义变量，推荐用 md5 哈希缩短长度并避免特殊字符问题：

aperture: the L402 aware reverse proxy

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

下载

基础安全版（含协议、主机、路径、关键参数）：
proxy_cache_key "$scheme://$host$request_uri?$arg_id&$arg_type";

区分登录用户（提取 session ID）：

set $cache_key "$scheme://$host$request_uri $cookie_sessionid";<br>proxy_cache_key $cache_key;

忽略 UTMs 并标准化 query：

map $args $clean_args {<br>  ~^(.*&)?(utm_[^&]+&?)+(.*)$ $1$3;<br>  default $args;<br>}<br>proxy_cache_key "$scheme$host$request_uri?$clean_args";

多端适配（PC/移动端分离缓存）：

map $http_user_agent $device {<br>  ~*Mobile|Android|iPhone "mobile";<br>  default "desktop";<br>}<br>proxy_cache_key "$scheme$host$request_uri $device";

注意事项与避坑点

自定义 key 不只是拼字符串，还涉及缓存一致性与调试成本：

变量为空时会参与拼接（如未携带 Cookie 时 $cookie_xxx 是空字符串），建议用 map 提前处理或加默认值；
避免使用动态变化过快的变量（如 $time_iso8601、$request_time），否则缓存完全失效；
修改 proxy_cache_key 后，旧缓存不会自动清理，需手动执行 rm -rf /path/to/cache/* 或使用 proxy_cache_purge 模块（需编译支持）；
可通过 add_header X-Cache-Key $cache_key; 输出 key 到响应头，方便调试命中情况。