Nginx 代理缓存中怎么配置 proxy_cache_key 自定义缓存的唯一标识-Nginx-PHP中文网

proxy_cache_key的核心作用是定义缓存键以决定哪些请求共用同一份缓存，需按业务逻辑精准设计区分维度，如多端适配、登录态隔离、多语言支持、子域隔离，并清洗无关参数，最后验证配置生效且缓存机制整体就绪。

nginx 代理缓存中怎么配置 proxy_cache_key 自定义缓存的唯一标识

proxy_cache_key 的核心作用是告诉 Nginx：“哪些请求该共用同一份缓存”。配置不是拼凑变量，而是按业务逻辑精准表达“内容是否相同”的判断依据。

默认值 $scheme$proxy_host$request_uri 只考虑协议、主机和路径，但实际场景常需更多区分：

多端适配：加入 $http_x_requested_with（值为 XMLHttpRequest 或空）比依赖 $http_user_agent 更稳定，避免因 UA 微小差异导致缓存碎片
登录态隔离：用 md5($cookie_user_id) 替代明文 $cookie_user_id，既保证用户间不串缓存，又规避敏感信息泄露风险
多语言支持：若后端通过 Accept-Language 或自定义头 HTTP_X_LANG 返回不同内容，需将其纳入 key，如 $http_accept_language
子域隔离：用 $host 替代 $proxy_host，确保 www.example.com 和 api.example.com 不共享缓存

UTM 参数、时间戳、随机数等不影响内容输出，却会让同一资源生成大量 key。不能直接拼 $args，应预处理：

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

下载

在 http 块中定义 map 清洗参数：

map $args $clean_args {<br>  default "";<br>  ~^(.*)(?:&|&?)(?:utm_[^&]*|ts=\d+|random=[^&]*)(?:&.*)?$ "$1";<br>}

key 中使用清洗后变量：
proxy_cache_key "$scheme$host$request_uri$is_args$clean_args|$lang|$device";

配置写完必须验证，否则无法确认是否生效：

添加日志格式：log_format cache '$cache_key - $upstream_cache_status';，并在 access_log 中启用
响应头中输出状态：add_header X-Cache-Status $upstream_cache_status;，用 curl -I 查看 HIT/MISS
临时设 key 为固定字符串（如 "debug"），观察多个请求是否全部命中 HIT，快速确认配置已加载

proxy_cache_key 再准确，缺以下任一条件也无法工作：

http 块中已声明 proxy_cache_path，路径存在且 Nginx 进程有读写权限
对应 location 中启用了 proxy_cache zone_name，且 zone_name 与 proxy_cache_path 中 keys_zone 名称一致
后端响应含有效缓存控制头（如 Cache-Control: public, max-age=3600），或 Nginx 侧用 proxy_cache_valid 强制指定状态码缓存策略