Nginx 中怎么配置 proxy_cache 缓存带参数的动态接口请求-Nginx-PHP中文网

Nginx缓存带参请求的关键是显式配置proxy_cache_key包含$request_uri（已含参数），并用map过滤敏感参数；需设proxy_cache_valid按状态码分级缓存，配合proxy_cache_bypass和proxy_no_cache跳过不安全请求，响应头X-Proxy-Cache可验证命中状态。

nginx 中怎么配置 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 Voice Proxy

⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**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; —— 同样条件，既不读缓存也不写缓存

这样可灵活支持调试或强一致场景，而无需临时停用整个缓存配置。