Nginx 的 proxy_cache_key 决定缓存项唯一性，默认为 $scheme$proxy_host$request_uri，macOS 下需自定义以包含请求方法、认证头等，并确保 proxy_cache_path 权限正确、location 启用缓存且响应可缓存。
在 macOS 下配置 Nginx 的 proxy_cache_key，核心是确保缓存键能准确区分不同请求，避免误命中或覆盖。它不依赖系统特性，而是由 Nginx 配置本身决定，但需注意 macOS 默认无 systemd、路径权限和文件系统（APFS）对缓存目录的兼容性。
proxy_cache_key 的作用与默认行为
proxy_cache_key 定义“什么算同一个缓存项”。Nginx 默认值是 $scheme$proxy_host$request_uri，即协议 + 后端主机名 + 完整请求 URI（含查询参数）。这意味着：
-
GET /api/user?id=1和GET /api/user?id=2是两个独立缓存项 -
GET /index.html和HEAD /index.html被视为同一项（因默认不含$request_method） - 若后端依赖 Cookie 或 Header（如
Authorization），默认 key 不包含它们，会导致用户 A 的响应被缓存并返回给用户 B
macOS 下推荐的自定义 key 写法
为兼顾安全与实用性，建议显式构造 key，尤其在开发/测试环境使用本地路径时：
- 基础增强（含方法与参数）：
proxy_cache_key "$request_method|$scheme://$host:$server_port$request_uri"; - 带认证上下文（防越权）：
proxy_cache_key "$request_method|$scheme://$host:$server_port$request_uri|$http_authorization|$cookie_session_id"; - 忽略特定查询参数（如跟踪用的 utm_*）：
set $args_clean $args;配合 map 指令预处理，再用于 key
⚠️ 注意：macOS 上不要在 key 中硬编码本地路径（如 /usr/local/var/www），key 应只反映客户端请求特征，与服务端文件路径无关。
配合 cache_key 生效的关键前提
仅设 proxy_cache_key 不足以启用缓存，还需确认以下三点已在 macOS 的 nginx.conf 中正确配置：
-
proxy_cache_path已在http块中声明，且路径（如/usr/local/var/cache/nginx）存在、Nginx 进程有读写权限（sudo chown -R $(whoami):staff /usr/local/var/cache/nginx） - 对应
location块中已启用proxy_cache并引用了该 path 的keys_zone名称 - 后端响应带有可缓存标识（如
Cache-Control: public, max-age=300），或 Nginx 侧用proxy_cache_valid强制缓存指定状态码
验证是否按预期生成 key
在 macOS 终端中，可通过日志快速验证 key 构造效果：
- 添加日志格式记录 key：
log_format cache_log '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$upstream_cache_status" "$cache_key"'; - 在 location 中启用：
access_log /usr/local/var/log/nginx/cache.log cache_log; - 重启 Nginx（
brew services restart nginx）并发起请求，检查日志中$cache_key字段是否符合预期
实际调试时，可临时把 key 设为简单字符串（如 "DEBUG-$request_uri"）便于观察，确认逻辑后再还原为完整表达式。
