Nginx 缓存键设计怎么在 API 接口缓存中规范键名-Nginx-PHP中文网

api缓存键名设计需精准表达共享范围，避免污染：必须包含$request_method、$host、$uri$is_args$args；按需增强登录态、cors、设备类型字段；主动过滤utm等干扰参数；务必验证key生成是否符合预期。

nginx 缓存键设计怎么在 api 接口缓存中规范键名

API 接口缓存的键名（proxy_cache_key）不是越长越安全，而是要精准表达“哪些请求该共享一份缓存”。设计不当会直接导致缓存污染——比如用户 A 看到用户 B 的数据、移动端返回 PC 版本、带身份信息的响应被公开缓存。

默认的 $scheme$proxy_host$request_uri 太粗略，生产环境至少补全以下三项：

区分请求方法：加上 $request_method，避免 HEAD 请求命中并覆盖 GET 缓存；
统一主机标识：用 $host 替代 $proxy_host，防止子域名（如 api.example.com 和 www.example.com）误共享缓存；
保留路径与参数语义：用 $uri$is_args$args 替代 $request_uri，避免重写后 URI 变形影响一致性。

是否加入额外字段，取决于接口是否对这些因素敏感：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

登录态或角色差异：需区分用户时，添加 md5($cookie_user_id) 或 md5($http_x_user_role)，避免明文 cookie 泄露；
跨域请求（CORS）：若接口支持多 Origin 调用，必须含 $http_origin，并配 add_header Vary "Origin"，否则 A 站的 Access-Control-Allow-Origin: a.com 可能返回给 B 站；
设备类型适配：优先用 $http_x_requested_with（值为 XMLHttpRequest 或空）判断是否为 Ajax 请求，比解析 $http_user_agent 更轻量稳定。

UTM、时间戳、随机数等不影响内容的查询参数，会导致缓存键爆炸式增长。不能直接拼 $args，应预处理：

在 http 块中用 map 清洗参数串，例如剔除 utm_*、ts=、random=；
定义清洗后变量 $clean_args，再用于 key：proxy_cache_key "$scheme$host$uri$is_args$clean_args";；
若后端对参数顺序不敏感（如 ?a=1&b=2 ≡ ?b=2&a=1），Nginx 不原生支持排序，建议仅对明确需参数区分的路径启用缓存（如限定 location ~ \.json$）。

配置写完不等于生效，必须验证实际生成的 key：

添加日志格式：log_format cache '$cache_key - $upstream_cache_status';，并在 access_log 中启用；
用 curl -I 观察 X-Cache-Status 和 Age 字段变化；
临时设 key 为固定字符串（如 "debug_key"），看多个不同请求是否全部命中 HIT，可快速确认配置是否加载成功。