如何利用 rewrite_log 指令在日志中调试复杂的 URL 重写逻辑-Nginx-PHP中文网

rewrite_log 自 1.19.0 起已废弃，应改用 error_log debug 级别、map + log_format 追踪、if 临时调试及 nginx -t 查看实际配置。

如何利用 rewrite_log 指令在日志中调试复杂的 url 重写逻辑

rewrite_log 指令本身在较新版本的 Nginx 中已被移除（自 1.19.0 起彻底废弃），它曾用于开启重写模块的调试日志，但实际使用中存在明显局限：仅输出到 error_log、依赖 debug 级别、不支持条件过滤、且与现代 Nginx 日志机制不兼容。因此，**不能也不应再依赖 rewrite_log 调试 URL 重写逻辑**。

改用 error_log 的 debug 级别捕获重写细节

Nginx 自 1.15.0 起通过增强的 error_log 指令支持更精细的重写调试信息。只需确保：

编译时启用了 --with-debug（大多数预编译包默认不带，需自行编译或选用 debug 版本）
在 nginx.conf 的 main 或 http 块中配置：
error_log /var/log/nginx/debug.log debug;
重启 Nginx 后，所有重写匹配、变量展开、跳转动作都会以 debug 级别记录，例如：
2024/05/12 10:23:41 [debug] 12345#0: *6789 http script regex: "^/old/(.*)$" ... matched

用 map 指令 + log_format 构建可读性强的重写追踪日志

相比 debug 日志的冗长，用 map 预判重写路径并注入标记更直观：

定义一个 map 将关键重写规则映射为易识别的标签：

map $request_uri $rewrite_trace {<br>  ~^/api/v1/users$ "to_v2_api";<br>  ~^/static/(.+)\.(js|css)$ "cache_bust";<br>  default "no_rewrite";<br>}

在 log_format 中加入该变量：
log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$rewrite_trace"';
访问时即可在 access.log 中直接看到哪条规则被触发，无需解析 debug 日志

配合 if + return 临时插入调试响应（仅限开发环境）

对于难以复现的分支逻辑，可在 server 块内添加临时调试段：

用 if 判断目标 URI 或变量值，立即返回含上下文的响应：

if ($args ~* "debug=1") {<br>  return 200 "URI: $request_uri\nHost: $host\nRewrite Test: $my_custom_var";<br>}

这样可通过 curl 直接查看当前请求中所有变量展开结果，快速验证正则捕获、变量拼接是否符合预期
注意：if 在 location 外使用有风险，仅限调试且务必在上线前删除

用 nginx -t + nginx -T 验证配置语法与实际展开效果

很多重写问题源于配置未生效或变量作用域错误：

nginx -t 检查语法和文件引用是否正确
nginx -T（大写 T）输出**完全展开后的最终配置**，含所有 include、变量默认值、继承关系，能清晰看到 rewrite 规则实际落在哪个 server/location 块中
特别适合排查“为什么这条 rewrite 没执行”——可能因 location 匹配优先级更高，或 rewrite 被后续指令覆盖