如何利用error_log的debug级别在线调试复杂的重写规则-Nginx-PHP中文网

开启Nginx error_log的debug级别是排查重写规则最有效方式，需确认编译含--with-debug、配置error_log path debug、聚焦作用域，并通过日志关键词定位匹配与执行过程。

如何利用error_log的debug级别在线调试复杂的重写规则

直接开启 error_log 的 debug 级别，是排查 Nginx 重写规则最有效、最底层的方式之一。它不依赖外部工具，能清晰展示每条 rewrite 指令的匹配、执行、跳转与终止过程，特别适合处理嵌套 if、多层 location 匹配、break/last 行为混淆等复杂场景。

确认 Nginx 编译时启用了 debug 日志支持

默认发行版（如 Ubuntu 官方包、CentOS 的 yum 包）通常**不包含 debug 日志功能**。需确认：

运行 nginx -V 2>&1 | grep -o with-debug，有输出才表示支持；
若无，需重新编译 Nginx，添加 --with-debug 参数；
注意：debug 日志会产生大量输出，**仅限测试环境短期启用**，不可用于生产。

在配置中正确设置 error_log 并指定 debug 级别

在 http、server 或具体 location 块中添加：

error_log /var/log/nginx/rewrite_debug.log debug;

关键点：

路径需 Nginx 工作进程（如 www-data 或 nginx 用户）有写权限；
必须写 debug，不能写 debug_http 或其他变体（Nginx 1.19+ 后已统一为 debug）；
该指令作用域越小（如只放在某个 location 内），日志越聚焦，干扰越少。

读懂 rewrite 相关的 debug 日志关键行

触发请求后，查看日志中含 rewrite、regex、using、test、matched、not matched 的行。典型流程如下：

test location: "/api/v2/users" → Nginx 开始匹配 location 块；
using configuration "/api/v2/" → 进入对应 location；
rewrite phase: 3 → 进入重写阶段（phase 3 是 rewrite 指令执行期）；
rewriting "/api/v2/users" using "^/api/v2/(.*)$" => "/v2/$1" → 正则匹配成功并替换；
rewrite "/v2/users" break → 执行 break，停止当前 location 内后续 rewrite；
rewrite or internal redirection cycle while internally redirecting to "/v2/users" → 出现无限重定向（常见于 last 后又匹配到同一 location）。

配合调试技巧快速定位问题

单靠日志还不够高效，建议组合使用：

用 curl -v http://your.site/path 观察真实响应头（尤其是 Location）和状态码，与日志比对；
在关键 location 中临时加 return 200 "in location X";，确认是否进入预期块；
把复杂正则拆成简单模式逐条测试，例如先测 ^/api/，再加 v2，再加捕获组；
注意 if 指令的坑：它在 location 内独立执行，且不继承 rewrite 结果，debug 日志中会显示 if 条件判断过程（如 if condition true），需重点观察。