必须满足编译支持、配置精准、日志聚焦三个前提：先验证nginx -v含--with-debug，再在server或location块中设error_log /path/debug.log debug，配合debug_connection限制ip范围，并关注[debug]前缀的关键线索。
开启 error_log 的 debug 级别，是深入看清 Nginx 内部行为最直接的方式——它不依赖外部工具，能逐阶段还原请求匹配、重写执行、代理转发、SSL 握手等全过程。但这个能力不会自动生效，必须满足编译支持、配置精准、日志聚焦三个前提。
确认 Nginx 编译时启用了 debug 支持
绝大多数系统包（如 Ubuntu apt、CentOS yum 安装的 nginx）默认不含 debug 日志功能。运行以下命令验证：
-
nginx -V 2>&1 | grep -o with-debug—— 有输出才表示支持 - 若无输出，需从源码重新编译，并添加
--with-debug参数 - OpenResty 用户通常已内置该支持，无需额外操作
在合适作用域中设置 error_log debug
debug 日志量极大，不能全局启用。应按需缩小范围：
- 只在怀疑出问题的
server或具体location块内写：error_log /var/log/nginx/debug.log debug; - 路径需确保 Nginx 工作进程用户（如
www-data或nginx）有写权限 - 配合
debug_connection 192.168.1.100;可限制仅对某 IP 生效，进一步减少干扰 - 避免放在 main 上下文（即 nginx.conf 最外层），否则所有 worker 进程都会打满日志
识别关键 debug 日志线索
日志中带 [debug] 前缀的行才是有效信息，重点关注以下模式：
-
test location: "/api/v2/"→ 表示开始匹配 location -
using configuration "/api/v2/"→ 成功进入该 location 块 -
rewrite phase: 3→ 进入重写阶段（phase 3 是 rewrite 指令执行期） -
"^/api/v2/(.*)$" matches "/api/v2/users"→ 正则成功匹配并显示捕获组 -
http proxy header: "GET /path HTTP/1.0"→ 表明已向 upstream 发起代理请求 -
ssl handshake: TLSv1.3或SSL_do_handshake() failed→ SSL 握手过程细节
配合其他手段提升调试效率
单看 debug 日志容易淹没重点，建议组合使用：
- 用
curl -v http://host/path观察真实响应头与状态码，和日志中upstream timed out或rewrite or internal redirection cycle对照 - 在关键 location 中临时加
return 200 "in /v2";，确认是否真的进入了目标块 - 对复杂正则，先拆成简单子模式测试：比如先验证
^/api/，再加v\d+，最后补上捕获组 - 若用
if判断变量，注意它在 location 内独立执行，日志中会单独出现if condition true行，需结合上下文判断是否继承了前面 rewrite 的结果
