Nginx缓存带参请求的关键是显式配置proxy_cache_key包含$request_uri（已含参数），并用map过滤敏感参数；需设proxy_cache_valid按状态码分级缓存，配合proxy_cache_bypass和proxy_no_cache跳过不安全请求，响应头X-Proxy-Cache可验证命中状态。
在 Nginx 中配置 proxy_cache 缓存带查询参数（query string）的动态接口请求，关键在于让 Nginx 正确识别并区分不同参数组合的请求为独立缓存项，同时避免缓存不安全或敏感内容。默认情况下，Nginx 会将整个请求 URI（含参数）作为缓存 key 的一部分，但需显式启用并合理控制。
确保 proxy_cache_key 包含 $args
Nginx 默认的缓存 key 是 $scheme$proxy_host$request_uri，其中 $request_uri 已包含原始请求路径和完整参数（如 /api/user?id=123&type=detail），所以通常无需额外修改即可缓存带参请求。但为明确性和可维护性，建议显式定义：
proxy_cache_key "$scheme$proxy_host$request_uri";
若需排除某些无意义参数（如 utm_source、ts 等用于追踪的时间戳），可用 $args 配合 map 指令标准化参数顺序或过滤：
map $args $cache_args {
default $args;
"~^(.*&)?(utm_[^&]+&?)(.*&?)$" "$1$3";
"~^(.*&)?(ts|random)=[^&]+(&?.*)$" "$1$3";
}
proxy_cache_key "$scheme$proxy_host$request_uri?$cache_args";
配置 proxy_cache_valid 并注意状态码范围
动态接口常返回 200、404、500 等状态码，需按需设置缓存时长。例如：
-
proxy_cache_valid 200 201 302 10m;—— 缓存成功响应 10 分钟 -
proxy_cache_valid 404 1m;—— 缓存 404 响应 1 分钟（防频繁探测） -
proxy_cache_valid any 1m;—— 所有状态码统一缓存 1 分钟（慎用）
注意：Nginx 不缓存默认不缓存 Set-Cookie 响应头的响应（除非显式开启 proxy_ignore_headers Set-Cookie;），这对带登录态的接口是保护机制，切勿随意关闭。
⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**
控制缓存行为：跳过缓存与强制更新
对需要实时性的请求（如带 no-cache 参数或特定 header），可通过 proxy_cache_bypass 和 proxy_no_cache 控制：
-
proxy_cache_bypass $arg_nocache $http_pragma $http_authorization;—— 当请求含?nocache=1或Pragma: no-cache时，直接回源，不读缓存 -
proxy_no_cache $arg_nocache $http_pragma $http_authorization;—— 同样条件，既不读缓存也不写缓存
这样可灵活支持调试或强一致场景，而无需临时停用整个缓存配置。
验证缓存是否生效
通过响应头确认缓存状态：
- 命中缓存时，响应头中会出现
X-Proxy-Cache: HIT（需自行添加add_header X-Proxy-Cache $upstream_cache_status;） - 未命中但成功写入缓存：显示
MISS - 因配置跳过缓存：显示
BYPASS
同时检查磁盘缓存目录（如 /var/cache/nginx/api_cache）是否有对应文件生成，注意文件名由 cache key 的 MD5 哈希生成，不可读但存在即说明 key 生效。
