Nginx 如何在源码安装过程中启用调试日志输出排查底层源码问题

作者：袖梨 2026-09-01

必须在 ./configure 阶段添加 --with-debug 选项才能启用调试日志，否则配置文件中设置 error_log debug 会被静默忽略；编译后需在 nginx.conf 中正确配置 error_log 路径和 debug 级别，并通过 nginx -V 和 nginx -t 验证。

要在源码安装过程中启用调试日志来排查底层问题，关键是在 ./configure 阶段显式开启 --with-debug 编译选项，并在后续配置中将 error_log 级别设为 debug。仅靠配置文件设 debug 级别是无效的——如果编译时没加 --with-debug，Nginx 会静默忽略该级别，日志仍只输出到 error 或更高级别。

编译时必须启用 debug 支持

运行 ./configure 时，需明确添加 --with-debug 参数：

该选项会把调试宏和日志逻辑编译进二进制，否则所有 debug 相关代码会被预处理器剔除
它不依赖操作系统或发行版，但要求 PCRE、zlib、OpenSSL 等基础依赖已正确安装（尤其 pcre-devel 和 openssl-devel）
推荐与其他路径参数配合使用，例如：
./configure

--prefix=/opt/nginx

--with-debug

--error-log-path=/var/log/nginx/error.log

--http-log-path=/var/log/nginx/access.log

--conf-path=/etc/nginx/nginx.conf

配置文件中正确设置 debug 日志级别

安装完成后，在 nginx.conf 的顶层（如 main 或 http 块）设置：

error_log /var/log/nginx/error.log debug; —— 注意路径必须与 --error-log-path 一致或可写，且级别明确写 debug
避免写成 debug_core 或 debug_http 等子级别，除非你已确认源码中对应模块启用了细分调试开关
若只想对特定 IP 开启 debug 日志（减少日志量），可用 debug_connection 指令：
```
events {
```
debug_connection 192.168.1.100;
}

验证与启动前检查

启用后务必执行以下步骤再启动：

运行 nginx -V 2>&1 | grep -o with-debug，确认输出含 with-debug 字样
用 nginx -t 测试配置，确保无语法错误；若提示 unknown log level "debug"，说明编译遗漏 --with-debug
手动创建日志目录并授权：mkdir -p /var/log/nginx && chown nginx:nginx /var/log/nginx
首次启动建议加 -e stderr 直接看终端输出：/opt/nginx/sbin/nginx -c /etc/nginx/nginx.conf -e stderr