Nginx 如何排查 Nginx 在配置复杂的 Rewrite 规则时由于优先级判断失误导致的失效

Nginx Rewrite 失效主因是 location 匹配顺序与 rewrite 执行时机错配：需确认请求是否进入含 rewrite 的 location，区分 =、^~、~、/ 四类匹配优先级，注意 ^~ 终止正则匹配，rewrite 后 break 停止当前块、last 重启 location 匹配，避免 if 块滥用及外层 return 干扰，并通过 curl -I 和 rewrite_log 日志验证执行路径。

排查 Nginx Rewrite 规则因优先级判断失误导致失效，核心是理清 location 匹配顺序 与 rewrite 执行时机 的关系。很多“规则不生效”并非语法错误，而是被更高优先级的 location 拦截、或 rewrite 被跳过、或在错误上下文中执行。

确认 rewrite 所在的 location 是否真正匹配请求

rewrite 指令只在它所属的 location 块内执行。如果请求根本没进到写 rewrite 的那个 location，规则自然不触发。

1. 用 curl -v https://domain.com/path 查看实际匹配的 location（Nginx 日志中可开启 log_format 记录 $request_uri 和 $uri）
2. 检查 location 类型：精确匹配（=）> 前缀匹配（^~）> 正则匹配（~ 或 ~*）> 普通前缀（/）。例如 location = /api 只匹配 /api，不匹配 /api/v1
3. 注意 ^~ 会终止正则匹配——一旦命中 location ^~ /static，后面的 location ~ .js$ 就不会被检查

验证 rewrite 是否被 location 内部的其他指令覆盖或跳过

rewrite 不是“一写就跑”，它受所在块的上下文和后续指令影响。

1. rewrite 后若跟 break，则停止当前 location 内所有后续 rewrite；若跟 last，则重新开始 location 匹配（可能进入另一个 block）
2. 如果 location 中有 proxy_pass 且前面没有 rewrite，或 rewrite 用了 redirect/permanent，那 rewrite 实际已作为 HTTP 响应发出，不再走后端逻辑
3. 避免在 if 块中滥用 rewrite——if 在 location 外定义时行为不可靠，且容易因变量为空被跳过

检查是否被更高层级的 rewrite 或 return 干扰

server 块或更外层的 if 语句中的 rewrite/return 会先于 location 内部执行，可能直接终结请求。

1. 比如 server 块里写了 if ($scheme = http) { return 301 https://...; }，这个判断在 location 之前运行，但若漏了 $scheme 判断，HTTPS 请求也可能被误重定向
2. 多个 rewrite 链式存在时，注意是否某条规则提前返回（如 return 404）或改变 $uri 导致后续 location 不再匹配
3. 用 nginx -t 确保语法无误后，务必用 curl -I 查看响应头中的 Location 和状态码，比浏览器更真实（避开缓存和自动跳转干扰）

用调试日志定位真实执行路径

启用 rewrite 日志可直观看到每一步改写过程。

1. 在对应 server 或 location 块中添加：rewrite_log on;（需编译时启用 debug 日志）
2. 同时设置 error_log /path/to/log warn;，warn 级别即可输出 rewrite 跳转信息
3. 观察日志中是否出现 “using configuration”、“rewritten to”、“tested URI” 等关键词，确认 rewrite 是否被执行、是否被 break/last 中断、是否进入预期 location