Nginx缓存键包含查询参数时,怎样配置并验证缓存区分效果?
两个请求的路径相同,不代表它们应该命中同一份缓存。比如 /goods?id=18 和 /goods?id=27,如果页面内容由 id 决定,缓存键却只取路径,两次请求就可能共享缓存;反过来,若把所有查询参数都纳入键,utm_source 这类不影响内容的参数又可能制造大量重复缓存。

要让查询参数参与缓存区分,关键是检查 proxy_cache_key 是否包含带参数的 URI,并确认请求没有被缓存绕过、响应也允许写入缓存。Nginx 默认缓存键通常包含 $request_uri,其中包括查询字符串;但自定义缓存键、重写规则或缓存控制条件,都可能改变最终效果。下面按配置、机制和验证结果逐项排查。
先区分 URI、查询参数与缓存键
Nginx 中几个容易混淆的变量,决定了查询参数是否进入缓存键:
| 变量 | 含义 | 是否包含查询字符串 |
|---|---|---|
$request_uri | 客户端请求的原始 URI,包含路径和参数 | 是 |
$uri | 当前请求的规范化 URI,可能受内部重写影响 | 否 |
$args | 当前请求的参数字符串 | 是,单独表示参数部分 |
$is_args | 有参数时为 ?,无参数时为空 | 只表示分隔符 |
例如请求 /goods?id=18 中,$request_uri 是 /goods?id=18,$uri 是 /goods,$args 是 id=18。因此,若配置写成:
proxy_cache_key "$scheme$proxy_host$uri";
那么 id=18 和 id=27 会得到相同的缓存键。只用 $uri 是常见的配置疏漏:日志里能看到参数,不代表缓存键也包含参数。
Nginx 的代理缓存默认键通常等价于:
proxy_cache_key $scheme$proxy_host$request_uri;
如果没有自定义 proxy_cache_key,不应先入为主地认定 Nginx 默认忽略查询参数。应先检查实际生效的配置、include 文件以及相关 location 中是否覆盖了缓存键。
缓存键如何影响命中
可把缓存键理解为缓存对象的索引。请求到达后,Nginx 根据缓存区域和缓存键查找对象;键相同,才有机会读取同一份缓存。键不同,即使路径相同,也会分别查找和存储。
例如:
proxy_cache_key "$scheme|$proxy_host|$request_uri";
在这个键下,以下请求通常对应不同缓存对象:
/goods?id=18
/goods?id=27
而重复请求 /goods?id=18,在缓存有效且未被绕过的情况下,才可能命中前一次生成的对象。
这里的“可能”很重要:缓存键负责区分对象,不负责保证对象一定被缓存。proxy_cache_bypass 可以让请求跳过缓存读取,proxy_no_cache 可以阻止响应写入缓存。上游响应的 Cache-Control、Set-Cookie 等信息也可能影响是否缓存,具体取决于 Nginx 配置及缓存规则。因此,看到键里有参数,只能说明区分条件具备,不能单凭这一点判断缓存已生效。
配置示例:让完整查询字符串参与键
以下示例适用于使用 Nginx 代理缓存的场景。proxy_cache_path 放在 http 块中,proxy_cache、缓存键和转发指令放在对应的 location 中;上游名称应替换为实际配置。
http {
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=page_cache:20m
max_size=2g inactive=30m use_temp_path=off;
upstream app_backend {
server 127.0.0.1:8080;
}
server {
listen 80;
server_name example.test;
location / {
proxy_pass http://app_backend;
proxy_cache page_cache;
proxy_cache_key "$scheme|$proxy_host|$request_uri";
proxy_cache_valid 200 10m;
add_header X-Cache-Status $upstream_cache_status always;
}
}
}
该示例中,$request_uri 将路径和原始查询字符串一并纳入键。proxy_cache_valid 200 10m 为状态码 200 的响应指定缓存时长;它不是绕过上游缓存控制规则的通用开关。如果应用返回禁止缓存的响应头,或配置中另有 proxy_no_cache 等规则,仍需检查实际响应和相关指令。
X-Cache-Status 用于验证缓存状态,常见值包括 MISS、HIT、BYPASS、EXPIRED。这是便于排查的响应头,正式使用时要确认不会泄露不适合公开的信息;也要确认没有其他配置覆盖或隐藏该响应头。
若不同客户端域名共用同一个上游,且上游会依据请求的 Host 返回不同内容,还应评估是否需要把 $host 纳入键。例如:
proxy_cache_key "$scheme|$host|$proxy_host|$request_uri";
这不是所有环境都必须添加的字段。应按响应实际依赖的请求属性设计缓存键:某项属性会改变响应内容,却没有进入键或被其他缓存机制正确区分,就可能发生不同请求共享对象的情况。
围绕 Nginx 缓存与业务响应的承载,A5idc数据提供香港、美国、日本等地区的物理服务器,配置涵盖 Xeon Gold、AMD EPYC、SSD 与 NVMe 存储,并有不同网络线路方案,可用于部署网站、业务后台、数据库和接口服务。多地区资源与不同硬件组合,为承载不同访问人群、应用负载及数据规模的业务提供服务器基础。
先核对配置是否真的生效
排查时,建议先确认配置,再观察请求结果,避免仅凭一条响应头推断原因。
- 检查目标
location中是否有proxy_cache,以及它引用的缓存区域是否在http块中定义。 - 搜索所有相关配置文件中的
proxy_cache_key、proxy_cache_bypass和proxy_no_cache,重点看include文件、正则location与更具体的路径规则。 - 判断键里使用的是
$request_uri、$uri还是自定义变量,并确认这些变量与业务响应的依赖关系相符。 - 检查请求是否因 Cookie、请求头、认证信息或其他条件被设置为绕过缓存或不写入缓存。
- 在修改配置后,先测试语法,再平滑重载,并确认请求命中的确是预期的虚拟主机和
location。
常见的检查命令如下:
nginx -t
测试通过后,如系统由 systemd 管理,可使用:
sudo systemctl reload nginx
若 Nginx 使用了非默认配置路径或由其他方式管理,应按实际启动参数和服务管理方式执行检查、重载。不要在未确认配置文件路径时直接修改或重载另一套 Nginx 实例。
用两组查询参数验证区分效果
验证时,最好让响应内容本身能够辨认参数对应的结果,例如应用返回的商品编号、语言或筛选条件。仅看到 MISS 和 HIT,只能说明某次缓存读取状态,不能单独证明内容与参数的对应关系正确。
下面命令分别请求两个参数值,并再次请求第一个值:
curl -sS -D - -o /dev/null 'http://example.test/goods?id=18'
curl -sS -D - -o /dev/null 'http://example.test/goods?id=27'
curl -sS -D - -o /dev/null 'http://example.test/goods?id=18'
在缓存启用、响应允许缓存且没有其他干扰时,典型结果可以是:
第一次请求 id=18:X-Cache-Status: MISS
第一次请求 id=27:X-Cache-Status: MISS
再次请求 id=18:X-Cache-Status: HIT
这组结果支持这样的判断:两个参数值分别生成缓存对象,重复的 id=18 请求复用了对应对象。若第二个请求直接返回 HIT,需要怀疑参数未进入缓存键、旧缓存对象仍有效,或实际请求被改写成同一 URI。若每次都为 MISS,则可能是响应未写入缓存、缓存时长已过、请求被绕过,或每次请求实际使用了不同的键。
可以通过返回正文、应用日志或上游访问日志进一步核对参数值。必要时在测试环境使用新的测试参数,避免既有缓存对象影响判断。不要为了验证而直接清空生产缓存目录:这可能导致缓存整体失效并增加上游压力。
常见影响因素与判断方法
查询参数顺序与编码
$request_uri 保留客户端发来的原始 URI 表示,因此:
/search?type=book&page=2
/search?page=2&type=book
虽然应用可能将两者视为相同查询条件,但在缓存键中可能是两个不同字符串,进而占用两份缓存。百分号编码方式、参数重复次数等差异,也可能导致键不同。
如果业务明确要求这类请求共用缓存,需要先定义哪些参数可以重排、合并或忽略,再设计规范化规则。不能仅为提高命中率就随意删减参数:只要某个被忽略的参数会改变响应,就可能让一个请求读到另一个请求的缓存内容。
非业务参数造成缓存碎片
广告跟踪参数、随机标识等字段若不影响响应,却全部进入键,会增加缓存对象数量、降低重复请求的命中机会。可考虑只把影响内容的参数纳入自定义键,但应先通过应用逻辑或测试确认其他参数确实不影响响应。
例如,业务只由 id 和 lang 决定,可以在 http 块中构造一个明确的键片段:
map $args $selected_args {
default "";
}
map "$arg_id|$arg_lang" $product_variant {
default "$arg_id|$arg_lang";
}
server {
location /goods {
proxy_pass http://app_backend;
proxy_cache page_cache;
proxy_cache_key "$scheme|$host|$uri|$product_variant";
proxy_cache_valid 200 10m;
add_header X-Cache-Status $upstream_cache_status always;
}
}
示例中的 $arg_id 和 $arg_lang 分别读取同名参数,键只保留这两个字段。部署前还要核对参数缺失、重复参数以及分隔符等情况是否符合应用规则,并确认其他参数确实不会改变响应。示例里的 $selected_args 未被使用,可删除;实际配置不需要定义无关变量。核心原则是:键只忽略经过验证的无关参数,不忽略业务依赖字段。
请求绕过与响应不可缓存
如果不同参数请求一直显示 BYPASS,应检查 proxy_cache_bypass 及其依赖变量;如果状态是 MISS,但重复请求始终不能转为 HIT,则要检查 proxy_no_cache、上游响应头、缓存有效期及缓存区域配置。还要注意,add_header 只负责展示状态,不会开启缓存。
Set-Cookie、Cache-Control: private 或 no-store 等响应信息可能使响应不适合共享缓存。若业务确实需要缓存这类响应,应先评估是否会缓存用户专属内容或敏感数据,不宜简单删除上游响应头来追求命中率。
适用边界:纳入参数不等于参数一定该纳入
若响应内容由查询参数决定,缓存键通常需要包含这些参数,或包含能等价区分响应的规范化信息。若参数仅用于统计且不影响响应,可以评估是否从键中排除,以减少重复对象。两类决策都应以响应依赖关系为依据,而不是只看 URL 长短或缓存命中率。
还要留意缓存键无法替代完整的缓存隔离设计。响应若依赖登录身份、语言请求头或其他未进入键的输入,就不能只靠加入查询字符串保证安全与正确。对含用户个人信息、授权结果或会话状态的页面,应先确定是否适合共享缓存,再考虑键的组成。
验证可以用三项结果收尾:不同业务参数是否产生预期的不同内容;各参数首次请求是否分别建立缓存对象;重复请求是否命中对应对象。只有三项相互吻合,且绕过条件、响应缓存头与配置位置也已核对,才能判断查询参数区分效果符合预期。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9022.html



