如何配置proxy_cache_key定制多维度组合的专属反代缓存键-Nginx-PHP中文网

多维度反代缓存键需按业务语义分层设计，仅纳入影响响应内容的维度（如$device、$cookie_user_id、主语言），剔除干扰参数（utm/v/t等），加业务前缀便于管理，并配套分级缓存策略。

如何配置proxy_cache_key定制多维度组合的专属反代缓存键

配置 proxy_cache_key 实现多维度组合的专属反代缓存键，核心在于按业务语义分层设计——不是堆字段，而是明确哪些维度真正影响内容差异、哪些只是干扰项，再通过 Nginx 的 map、参数归一化和结构前缀等手段落地。

只有真正导致响应内容不同的字段才应进入缓存键，否则会引发缓存分裂：

设备类型用 $device（需提前用 map 提取 desktop/mobile/tablet），别直接用完整 $http_user_agent
登录态个性化内容可加 $cookie_user_id，但未登录用户统一设为 "guest"，避免匿名用户缓存碎片化
语言地区建议提取主语言（如 zh 或 en）而非全量 $http_accept_language，或结合 $geoip_country_code

utm、v、t、_t 等不影响实际内容的参数必须剔除，否则同一接口因不同来源链接生成大量无效缓存：

WebChat Voice Proxy

⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**

下载

在 http 块中定义 map 清洗 $args，例如：
map $args $clean_args {
~^(.*&)?(utm_source|v|t|_t)=[^&]+(&.*)?$ "$1$2";
default $args;
}
在 proxy_cache_key 中引用 $clean_args，而不是原始 $args
配合 proxy_ignore_headers Set-Cookie 和 proxy_cache_bypass $arg_nocache，让调试请求自动绕过缓存

自定义缓存键上线后，刷新方式随之改变，需提前规划可观测性和可维护性：

在键开头加入业务标识，例如：
proxy_cache_key "api_v2:$scheme://$host$request_uri:$device:$lang";
带 Cookie 或 Header 的键无法用“按 URL 刷新”，必须改用“按 Cachekey 刷新”，有前缀便于批量识别和清理
避免使用 $request_time、$msec 等易变无意义值，否则命中率归零
上线前用 log_format 记录真实 key，抽样验证是否符合预期