自定义 proxy_cache_key 的核心是让缓存键精准表达响应内容，需识别业务语义、剔除干扰项、预处理动态值；静态资源用 "$scheme$host$uri"，多语言保留 $arg_lang，个性化接口只取 $cookie_user_id 或设为 "guest"，子域名场景必须含 $host；所有清洗归一化用 map 提前完成，避免复杂逻辑写入 key 行；谨慎引入 header/cookie，仅保留真正影响响应的字段；上线前须通过 x-cache-status、log_format 和对比测试验证效果。
自定义 proxy_cache_key 的核心不是“堆字段”，而是让每个缓存键精准表达“这个请求该返回什么内容”。键太宽，缓存混乱；键太窄，命中率暴跌。关键在识别业务语义、剔除干扰项、预处理动态值。
只保留真正影响响应结果的变量
后端返回内容不变，就不该生成新缓存。常见误操作是直接用 $args 或完整 $request_uri，结果一个 ?utm_source=weibo&t=1678901234 就把本该复用的缓存打散成几十份。
- 静态资源（JS/CSS/图片）：用
"$scheme$host$uri"—— 路径一致，内容就该一致 - 多语言 API：保留
$arg_lang或预处理后的$lang，但剔除ref=、v=、_ga= - 用户个性化接口：只取
$cookie_user_id或$arg_uid，未登录统一设为"guest"，避免空值或缺失导致 key 不稳定 - 子域名多租户场景：必须显式包含
$host，否则shop-a.example.com/api和shop-b.example.com/api会互相污染
用 map 预处理，不写复杂逻辑进 key 行
所有清洗、归一化、提取动作，都应在 http 块里用 map 提前完成。这样 key 行干净可读，也便于复用和调试。
- 设备类型标准化：
map $http_user_agent $device { ~*(iPhone|Android|Mobile) "mobile"; default "desktop"; } - 语言提取：
map $http_accept_language $lang { ~^zh "zh"; ~^en "en"; default "en"; } - 参数过滤：
map $args $cache_args { ~^(lang=[^&]+|region=[^&]+|id=[^&]+) $1; default ""; } - 用户 ID 提取：
map $http_cookie $cache_user_id { ~user_id=([^;]+) $1; default "guest"; }
最终 key 可写成："api_v3:$scheme://$host$uri|$device|$lang|$cache_args|$cache_user_id"
谨慎引入 Header 和 Cookie
除非后端真依赖它，否则别往 key 里塞。高频变动字段会让缓存彻底失效。
- 可保留：
$http_accept_language（语言）、$http_x_region（地区）、$http_x_user_role（角色） - 应避免：
$http_cookie（整段 Cookie）、$http_referer、$http_x_forwarded_for、$http_user_agent（原始值） - 如需区分用户，只取特定字段，比如
$cookie_user_id，而非整个$cookie - 敏感字段建议哈希后使用，例如
md5($cookie_user_id)，防明文泄露
上线前必须验证效果
配置写完不等于生效。没验证的 key 是盲调。
- 加响应头：
add_header X-Cache-Status $upstream_cache_status;，用curl -I看是否从 HIT 变多 - 记录真实 key：
log_format cache_log "$cache_key - $upstream_cache_status";，配合 access_log 查看实际生成值 - 对比测试：对同一 URL 分别带
?utm_source=xxx和不带参数请求，确认X-Cache-Status都是 HIT - 临时设 key 为固定字符串（如
"debug_key"），验证缓存模块本身是否正常工作
不复杂但容易忽略。
