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

必须在 ./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 参数：

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

   ./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 块）设置：

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

   events {
   debug_connection 192.168.1.100;
   }

验证与启动前检查

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

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

调试日志的实际使用要点

debug 日志信息密集，需有针对性地观察：

1. 默认输出包含事件循环、连接建立、HTTP 解析、模块调用等全过程，行首带 [debug] 标识
2. 遇到段错误或 core dump 时，先查 error.log 最末几行是否有 segmentation fault 及附近上下文
3. rewrite 或 Lua 模块异常时，配合 rewrite_log on; 和 log_not_found off; 可缩小范围
4. 生产环境切勿长期开启全局 debug，建议仅复现问题时临时启用，排查后降级为 warn 或 error