nginx 本身不生成php、java等后端脚本的错误堆栈,仅记录自身异常;php堆栈需配置php.ini和php-fpm,lua堆栈需lua_code_cache off并设error_log为notice级别,njs需info级别,后端堆栈须由应用自身输出且通过proxy_intercept_errors off等配置透传。

Nginx 本身不生成或输出脚本层(如 PHP、Java、Node.js)的错误堆栈,它只记录自身运行时的异常,比如配置加载失败、上游连接中断、worker 崩溃等。所谓“更详细的调试堆栈”,实际取决于你调试的是哪一层——Nginx 自身、嵌入式脚本(Lua/njs),还是后端应用。不能指望 Nginx 替后端打印 Java 的 Exception.printStackTrace() 或 Python 的 traceback。
明确日志归属层级
不同错误来源,日志位置和配置方式完全不同:
-
Nginx 核心错误(如配置语法错、bind 失败、worker segfault)→ 记录在
error_log,需开启debug级别并确认编译时带--with-debug -
PHP 脚本错误(Fatal Error、Parse Error)→ 由 PHP-FPM 控制,需配
php_admin_value[error_log]和catch_workers_output on,Nginx error_log 不会直接包含堆栈 -
Lua 脚本异常(OpenResty)→ 可在 Nginx error_log 中看到带行号的 traceback,但必须满足:
lua_code_cache off+error_log ... notice或更高 -
njs 错误→ 堆栈较简略,需
error_log ... info才能显示基本调用链 -
后端应用(如 Spring Boot)返回的 500 堆栈→ Nginx 默认不记录响应体内容;若临时调试,需关掉
proxy_intercept_errors、禁用缓冲,并确保后端已将堆栈写入响应体
启用 Nginx 自身 debug 日志
仅当排查 Nginx 内部行为(如 rewrite 执行路径、变量求值、模块初始化)时有效:
- 确认 Nginx 是 debug 编译版:
nginx -V 2>&1 | grep -- '--with-debug',无输出则需重编译 - 在
http或main上下文中设置:error_log /var/log/nginx/error.log debug; - 为避免日志爆炸,可限定 IP:
error_log /var/log/nginx/debug.log debug; debug_connection 192.168.1.100; - 重启前务必
nginx -t测试,debug 日志量极大,生产环境切勿长期开启
让 Lua 堆栈真正可见(OpenResty 场景)
这是少数能直接在 Nginx error_log 中看到完整堆栈的情况:
- 关闭缓存:
lua_code_cache off;(仅开发/测试环境) - 提升日志级别:
error_log /var/log/nginx/error.log notice;(error级别会过滤掉 Lua 异常) - 确保异常未被
pcall吞掉;自然抛出的错误才会触发完整 traceback - 示例输出:
stack traceback: /usr/local/openresty/nginx/lua/handler.lua:42: in function <...></...>
辅助定位后端堆栈的关键配置
Nginx 不记堆栈,但能帮你快速关联到对应请求和后端实例:
- 增强 access_log 格式,加入诊断字段:
upstream_addr、upstream_status、upstream_response_time、request_id(需后端透传) - 开启
proxy_set_header X-Request-ID $request_id;并用map或random_index生成唯一 ID - 确保后端日志也记录相同
request_id,实现全链路日志串联 - 对 5xx 响应,临时关闭拦截:
proxy_intercept_errors off;,并设proxy_buffering off;避免截断响应体











