Nginx 键值指南：如何利用 fastcgi_cache_key 组合多元化变量构建独一无二的缓存键

构建有效的 fastcgi_cache_key 需精准表达缓存共享范围，避免污染与命中率下降；必须按业务选配变量，如 $request_method、哈希后的 $cookie_user_id、$http_x_requested_with，并清洗 UTM 等干扰参数；需通过日志和响应头验证 key 生效，且依赖 fastcgi_cache_path、fastcgi_cache 配置及后端缓存头三者协同。

构建有效的 fastcgi_cache_key 不是拼凑变量，而是精准表达“哪些请求应共享同一份缓存”。键值重复或遗漏关键维度，会导致缓存污染（如用户A看到用户B的数据）、命中率骤降，甚至移动端返回PC版内容。

核心变量必须按业务场景选配

默认的 $scheme$host$request_uri 忽略方法、登录态和设备差异，多数生产环境需增强：

• 加入 $request_method：区分 GET 与 HEAD 请求，防止 HEAD 响应覆盖 GET 缓存
• 用 $host 替代 $proxy_host：确保 api.example.com 和 www.example.com 不共用缓存
• 处理登录态：推荐哈希后使用 md5($cookie_user_id)，避免明文 $cookie_user_id 泄露或引发 key 膨胀
• 适配终端类型：优先采用 $http_x_requested_with（值为 XMLHttpRequest 或空），比解析 $http_user_agent 更轻量、更稳定

过滤干扰参数，减少缓存碎片

UTM 参数、时间戳、随机数等不改变实际响应内容，却会让相同 URL 生成大量无效 key。不能直接拼 $args，需预清洗：

• 在 http 块中定义 map 指令剔除无关参数，例如：

map $args $clean_args {    ~^(.*)(?:&|&)?utm_[^&=]*=[^&]*(&.*)?$ $1$2;    ~^(.*)(?:&|&)?ts=[^&]*(&.*)?$ $1$2;    ~^(.*)(?:&|&)?random=[^&]*(&.*)?$ $1$2;    default $args;}

• 在 key 中使用清洗后变量：fastcgi_cache_key "$scheme$request_method$host$request_uri$is_args$clean_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-FastCGI-Cache（需配置 add_header X-FastCGI-Cache $upstream_cache_status;）和 Age 字段变化
• 临时设 key 为固定字符串（如 "debug_key"），观察不同请求是否全部命中 HIT，可快速确认配置是否加载成功

配套前提：key 生效的三个硬性条件

即使 key 写得再精确，缺以下任一环节，缓存也不会工作：

• fastcgi_cache_path 已在 http 块声明，路径存在且 Nginx 进程有读写权限（注意 macOS 上 /usr/local/var/cache/nginx 的 owner/group）
• 对应 location 中启用了 fastcgi_cache zone_name;，且引用的 keys_zone 名称与 fastcgi_cache_path 中一致
• 后端响应含有效缓存控制头（如 Cache-Control: public, max-age=300），或 Nginx 侧用 fastcgi_cache_valid 强制指定状态码缓存策略