Nginx 的配置有个特点：需求简单时，几行就能解决；一旦碰上灰度发布、租户隔离、请求头分流，map、if 和动态 proxy_pass 很快就会挤到一起。

配置能跑，但隔几个月再回来维护，往往要先把匹配顺序重新捋一遍。Nginx 1.31.5 新增的 predicate location，解决的正是这类配置不够顺手的问题。

这个版本于 2026 年 9 月 2 日发布。现在的 location 除了匹配 URI，还可以根据变量的真假，决定请求是否进入某个配置块。

新增能力不是动态路径

“location 支持变量”这句话容易产生歧义。它并不是允许把变量直接拼进 URI 路径：

1.31.5 新增的是谓词 location，变量本身就是这个配置块的匹配条件：

请求到达时，Nginx 会计算 $use_canary 的值。空字符串和字符串 0 代表不匹配，其他非空值代表匹配。

这里没有新增一套条件表达式语法。涉及多个请求头、Cookie、来源地址等条件时，仍然应该先用 map 计算出结果，再把结果交给 location。

换句话说，变量负责给出“是”或“否”，location 负责选择整套请求处理规则。两层职责是分开的。

用灰度路由看一遍完整配置

假设订单接口同时运行稳定版和灰度版。请求头 X-Release-Channel 等于 canary 时，不仅要切换上游服务，超时和响应头也要使用另一套配置。

以前也能根据变量切换 upstream，所以这项能力的价值不只是“换一个后端地址”。它允许灰度请求进入独立的 location，把代理、限流、缓存、超时、日志和响应头作为一组规则管理。

如果需求只是根据变量切换 upstream，没有其他策略差异，map 配合动态 proxy_pass 依然更简单。谓词 location 更适合切换整套处理逻辑，不需要为了使用新语法重写原有配置。

还有一个明确的限制：谓词 location 中的 proxy_pass 不能携带 URI 部分。

应该使用不带 URI 的上游地址：

匹配顺序决定请求最终走向

谓词 location 没有替换原来的 URI 匹配，而是加入了现有的匹配流程。在同一层级中，可以按下面的顺序理解：

1.  精确匹配 location = /path 命中后，直接结束；

2.  查找最长的前缀 location；

3.  最长前缀没有使用 ^~ 时，继续检查正则 location；

4.  正则没有命中，再按照配置顺序检查谓词 location；

5.  谓词没有命中，使用之前找到的前缀 location。

因此，正则匹配仍然优先于谓词匹配。最长前缀使用了 ^~，谓词也不会继续参与匹配。

同一层还可以配置多个谓词 location。当多个变量同时为真时，Nginx 选择配置中排在最前面的那一个：

如果 $is_emergency 和 $is_canary 同时为真，请求会进入维护规则。调换两个配置块的顺序，路由结果也会改变。

这部分需要在评审时重点检查。谓词配置的先后顺序不是排版问题，而是实际的业务优先级。

适合切换整套请求处理策略

谓词 location 比较适合下面几类场景：

•  根据请求头或 Cookie 进入灰度服务；

•  为不同租户配置独立的限流、缓存和超时；

•  根据客户端证书或来源网段应用不同的安全策略；

•  维护开关开启后，让部分请求进入降级逻辑；

•  配合 1.31.5 的请求体提前读取和 JSON 变量能力，按请求体字段路由。

按请求体路由需要额外说明。Nginx 默认先选择 location，之后才读取请求体。要让请求体字段参与谓词判断，还需要启用 1.31.5 新增的请求体提前读取能力，并把 JSON 字段提取为变量。predicate location 只负责使用已经计算好的变量，并不会单独完成请求体解析。

升级前确认实际使用的 Nginx 版本

1.31.5 属于 mainline 主线版本。生产环境准备使用新语法时，首先要确认当前运行的是不是对应版本的原生 Nginx。

OpenResty、Tengine、Ingress Controller 以及各 Linux 发行版的软件包都有自己的版本节奏。官方 Nginx 已经支持，不代表这些产品或软件源中的版本已经同步。

升级后先检查版本和配置，再做平滑重载：

验证时不能只测试变量为真的情况。变量为空、值为 0、正则优先命中、前缀使用 ^~、多个谓词同时为真，这几条分支都应该覆盖。

总结

Nginx 1.31.5 没有把 location 变成条件表达式，而是让它可以使用变量的真假选择路由。

只需要切换 upstream，原有的 map 方案通常已经够用；需要连同限流、缓存、超时和日志一起切换，谓词 location 会更清晰。

这项功能的语法很短，使用时真正需要关注的是变量如何计算、各种 location 的匹配顺序，以及条件不成立时请求最终落到哪里。

阅读原文：点击这里​