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"）便于观察，确认逻辑后再还原为完整表达式。