Nginx rewrite捕获组变量（如$1）仅在正则匹配成功、同指令作用域内有效，且不跨location或被后续rewrite覆盖；需用debug日志、return验证、map或set暂存传值。
排查 Nginx Rewrite 规则中捕获组变量（如 $1、$2）传递失败，核心是确认正则是否匹配成功、变量是否在作用域内可用、以及后续指令是否覆盖或丢弃了这些变量。
检查正则是否真正匹配并捕获
捕获组变量只有在 rewrite 指令的正则表达式成功匹配且含括号时才会生成。常见误区是误以为只要写了 $1 就一定有值。
- 用
error_log配合debug级别查看真实匹配过程（需编译时启用--with-debug） - 临时加一条
return 200 "match: $1, uri: $uri";在 rewrite 后验证 —— 若输出为空或match:后无内容，说明未捕获 - 注意：URI 是 rewrite 前的原始 URI；
$request_uri带参数，$uri不带，正则通常对$uri或$request_uri操作，需保持一致
确认变量作用域和生命周期
Nginx 中 rewrite 捕获组变量只在当前 rewrite 所在的上下文（server / location）内有效，且仅对**同一条 rewrite 指令后的本行目标 URI 和 flag 生效**；跨指令、跨 location 或进入 proxy_pass 时不自动继承。
-
rewrite ^/api/(.*)$ /v1/$1 break;→$1只在此条 rewrite 内部可用，不能在下一行的set $x $1;中直接使用（除非在同一 location 且 rewrite 未跳转） - 若用了
last或redirect，Nginx 会重新匹配 location，此前的捕获变量全部丢失 - 想跨 location 传值？改用
map提前提取，或用set+if（谨慎）暂存到变量，再通过proxy_set_header或fastcgi_param透传
排查变量被覆盖或未生效的典型场景
看似写了 $1，但最终没生效，往往是因为其他指令干扰或配置顺序问题。
-
if块内定义的 rewrite，其捕获组变量无法“逃逸”到 if 外部（Nginx 的 if 是伪指令，作用域受限） - 多个 rewrite 连续出现时，后一条会覆盖前一条的 URI，但不会继承前一条的捕获组 —— 每条 rewrite 的
$1来自它自己的正则 - 使用
try_files时，rewrite 不会触发（除非 fallback 到 =404 或指定 URI），此时捕获组根本不会计算 - 浏览器地址栏显示旧路径？那是 rewrite 用
redirect或permanent导致 302/301 跳转 —— 检查是否误加了 flag，应改用break或last实现内部重写
快速验证与调试建议
不依赖日志也能快速定位：用最简配置隔离复现，逐步加逻辑。
- 新建一个专用 location，例如
location /test-rewrite { ... }，避免干扰主逻辑 - 用
echo（需 echo 模块）或return 200输出关键变量：return 200 "uri=$uri, args=$args, cap1=$1"; - 把正则复制到在线工具（如 regex101.com）选 PCRE 模式测试，确认分组逻辑和斜杠处理（Nginx 默认不开启
PCRE_DOTALL） - 特别注意特殊字符转义：路径中点（.）、问号（?）、美元符（$）要写成
\.、\?、\$，否则会被误解析
