Nginx 缓存实战：如何配置 proxy_cache_key 自定义独一无二的缓存键-Nginx-PHP中文网

配置 proxy_cache_key 的核心是确保每个缓存项精准对应内容一致的请求，需剔除干扰参数、合理选取影响响应的变量，并通过日志和测试验证生效。

nginx 缓存实战：如何配置 proxy_cache_key 自定义独一无二的缓存键

配置 proxy_cache_key 的核心，不是堆变量，而是让每个缓存项真正对应“内容一致的请求”。键写得不准，轻则缓存命中率暴跌，重则用户看到别人的数据、移动端加载 PC 版页面、带身份信息的响应被公开缓存。

缓存键里每多一个变量，就可能多出一倍缓存碎片。必须问清楚：这个字段变，响应内容真会不同吗？

区分设备类型，用 $device（需提前 map 提取 desktop/mobile/tablet），别直接塞整个 $http_user_agent
登录态个性化内容可加 $cookie_user_id，但未登录用户统一设为 "guest"，避免匿名用户生成海量小缓存
语言地区建议取主语言（如 zh 或 en），而不是全量 $http_accept_language；若需区域细化，再结合 $geoip_country_code
绝对不要加入 $request_time、$msec、$date_gmt 这类每次请求都变的变量，否则缓存永远不命中

UTM、时间戳、随机数等参数不影响实际返回内容，却会让同一个接口产生成百上千个 key。不能靠拼接 $args 硬来，要预处理：

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

下载

在 http 块中定义 map 清洗参数串，例如剔除 utm_*、v=、t=、_t=
示例：map $args $clean_args { ~^(.*&)?(utm_source|v|t|_t)=[^&]+(&.*)?$ "$1$2"; default $args; }
在 proxy_cache_key 中使用 $clean_args，而非原始 $args
若后端对参数顺序不敏感（如 ?a=1&b=2 和 ?b=2&a=1 返回相同结果），Nginx 不支持自动排序，建议仅对明确需参数区分的路径启用缓存（如 location ~ \.php$）

自定义键上线后，刷新和排查都依赖可读性和可识别性：

配置写完不等于 key 按预期生成，必须实测确认：

添加日志格式：log_format cache '$cache_key - $upstream_cache_status';，再在 access_log 中启用该格式
用 curl -I 观察响应头中的 X-Cache-Status（需配 add_header X-Cache-Status $upstream_cache_status;）和 Age 字段变化
临时把 key 设为固定字符串（如 "debug_key"），看多个不同请求是否全部命中 HIT，快速验证配置是否加载成功
注意三个前提缺一不可：proxy_cache_path 已声明且路径权限正确、对应 location 启用了 proxy_cache zone_name、后端响应含有效缓存控制头或 Nginx 侧指定了 proxy_cache_valid