必须启用lua_code_cache off且error_log级别≥notice，否则Lua异常堆栈丢失行号；典型报错含“runtime error”和“stack traceback”，需检查文件行号及nil值操作，禁用print而用ngx.log或让异常自然抛出。
直接看 error_log 里带 lua 和 stack traceback 的错误行，重点确认是否启用了调试必需的配置——否则堆栈会丢失行号、定位失准。
检查 Lua 异常是否被完整记录
Nginx 默认不会输出 Lua 堆栈，必须满足两个前提：
- lua_code_cache off：仅开发环境启用；生产环境开启后，Lua 脚本被编译缓存，错误位置会指向编译后的匿名函数，无法对应源码行号
-
error_log 级别 ≥ notice：例如
error_log /var/log/nginx/error.log notice;；设为 info 或 debug 可看到更详细上下文，但 warn 及以下会直接过滤掉 Lua 异常堆栈
若日志中只有 runtime error 但无 stack traceback，大概率是上面任一条件未满足。
识别典型 Lua 报错格式与关键信息
正常捕获的 Lua 异常长这样：
2026/09/03 17:22:15 [error] 12345#0: *678 lua entry thread aborted: runtime error: /usr/local/openresty/nginx/lua/auth.lua:12: attempt to index a nil value (field 'token')
stack traceback:
coroutine 0:
/usr/local/openresty/nginx/lua/auth.lua:12: in function <usr/local/openresty/nginx/lua/auth.lua:1>
- 第一行末尾的
/auth.lua:12是出错的具体文件和行号，优先检查该行变量是否未初始化或取值为空 -
attempt to index a nil value类型错误最常见，说明对 nil 做了.xxx或[xxx]操作 -
stack traceback中的in function <...:1>表示整个文件被当作一个匿名函数执行，这是lua_code_cache off下的正常表现
排除干扰：别依赖 print()，用 ngx.log 或让异常自然抛出
在 Lua 脚本中写 print("debug") 不会输出到 Nginx 日志，它默认输出到标准输出（通常丢弃）：
- 调试时应改用
ngx.log(ngx.ERR, "user_id:", ngx.var.arg_id)，日志会进 error_log（需级别 ≥ err） - 更推荐“不加 try-catch”，让错误自然抛出——Nginx 会自动捕获并记录完整堆栈；手动
pcall后吞掉错误，反而失去定位能力 - 若用了
set_by_lua*指令，注意其返回值限制：只能返回字符串或 nil，返回 table 或函数会直接报错且无堆栈
验证模块加载与路径是否正确
有时报错看似是 Lua 执行失败，实则是模块根本没加载成功：
- 执行
nginx -V 2>&1 | grep -o with-http_lua_module，确认输出存在；否则所有access_by_lua_file都会提示unknown directive - 检查
lua_package_path是否包含脚本所在目录，路径错误会导致module 'xxx' not found类报错 - 若用
load_module加载ngx_http_lua_module.so，确保路径为绝对路径，且放在main上下文（即 events 块之前）
