OpenResty 下的 Lua 调试,先分清两件事:脚本挂在哪个阶段、错误去了哪里。启动期(init_by_lua*、init_worker_by_lua*)出错通常表现为 nginx -t 不通过或启动即退出;请求期(rewrite/access/content/header_filter/body_filter/log_by_lua*)出错往往只影响单个请求,客户端看到 500 而关键信息在 error_log 里。先看日志、再决定是加埋点还是改配置,比直接猜代码快。
判断路径建议这样走:先确认脚本所在阶段与 error_log 路径、级别,把 lua_code_cache 在开发环境临时设为 off 便于改动生效;再用最小 location 复现同一请求,用 ngx.log 输出关键变量并 curl 触发;验证看 error_log 有无 [error] 行、返回体是否符合预期;改完恢复 lua_code_cache on、清掉调试 location。边界是 off 只适合开发、init 阶段多数 ngx API 不可用、生产不要开 debug 级别日志。
先确认当前场景和目标
动手前把下面几项确认清楚,否则很容易在错误的方向上加日志。
- 脚本所在阶段:是 init_by_lua*、init_worker_by_lua*,还是 rewrite/access/content/header_filter/body_filter/log_by_lua*,抑或 ngx.timer 回调、balancer_by_lua*。阶段决定了哪些 ngx API 可用。
- 错误表现:nginx -t 报错、reload 后 worker 退出、请求返回 500、返回内容与预期不符、完全没有报错但逻辑没执行——这四种对应的排查入口不同。
- error_log 位置与级别:确认 nginx.conf 里 error_log 的路径,以及级别是否足够看到你写入的日志(默认 error 级别会吞掉 notice/info)。
- 模块路径:自己写的 lua 模块是否已通过 lua_package_path 加入搜索路径,否则报的是模块找不到,而不是业务逻辑错。
- lua_code_cache:开发环境常设为 off 以便改文件即生效;生产必须是 on。
一个可用于确认环境的配置骨架,路径和端口按自己环境替换:
http {
lua_package_path "/usr/local/openresty/nginx/conf/lua/?.lua;;";
error_log logs/error.log info;
server {
listen 8080;
location = /debug/lua {
content_by_lua_block {
ngx.log(ngx.INFO, "hit /debug/lua, uri=", ngx.var.uri, " args=", tostring(ngx.var.args))
ngx.say("ok")
}
}
}
}
用 nginx -t 检查语法,reload 后 curl -i 'http://127.0.0.1:8080/debug/lua?a=1',再 tail -f logs/error.log。这一步能跑通,说明日志通道是开的,后面加的埋点才看得到。
按这个顺序处理
- 先让错误可见。用 ngx.log 而不是裸 print,级别自己定。注意 ngx.log 只接受字符串和数字,nil、table 直接传会抛参数错误,反而把真正的错误盖住,建议统一转成字符串。
- 做一个最小复现点。单独开一个 location,用 content_by_lua_block 把待排查的代码搬进去,用 curl 直打,排除上游、代理、鉴权等干扰。
- 按阶段分流。init 类错误看 nginx -t 与启动时的 error_log;请求类错误看带 request 行和 lua 行号的堆栈;timer 回调里的错误不会返回给客户端,只能从 error_log 找。
- 纯 Lua 逻辑外提验证。OpenResty 自带的 resty 命令行可以单独跑一段 Lua,适合验证字符串处理、JSON 编解码、模块加载;但它没有真实请求上下文,ngx.say、ngx.req 这类 API 的行为与线上不同,不能拿它替代请求级验证。
- 收尾清理。定位完成后把 INFO 级日志降回需要的级别,删除临时 location,恢复 lua_code_cache on。
下面是一个可直接替换使用的日志包装片段,放在 lua_package_path 覆盖的目录里,例如 conf/lua/dbg.lua:

local cjson = require "cjson.safe"
local _M = {}
function _M.dbg(tag, ...)
local n = select("#", ...)
local parts = {}
for i = 1, n do
local v = select(i, ...)
local t = type(v)
if t == "table" then
parts[i] = cjson.encode(v) or "<encode_failed>"
elseif t == "nil" then
parts[i] = "nil"
else
parts[i] = tostring(v)
end
end
ngx.log(ngx.ERR, "[", tag, "] ", table.concat(parts, " "))
end
return _M
再把待排查逻辑包进最小复现点,pcall 兜住错误,保证出错时也能看到原因:
location = /debug/target {
content_by_lua_block {
local dbg = require "dbg"
local ok, err = pcall(function()
-- 把待排查的代码贴到这里,参数用自己的
local input = ngx.var.arg_id
dbg("target.in", "id", input)
local out = { id = input, ok = true }
ngx.say(require("cjson").encode(out))
end)
if not ok then
dbg("target.err", err)
ngx.status = 500
ngx.say('{"error":"internal"}')
end
}
}
触发方式仍是 curl 加 tail 日志。如果日志里出现 [target.err] 并带行号,基本就锁定在那一行的调用上了。
改完后怎么验证
验证分两轮:修完逻辑一轮,清理调试代码后再一轮。
- 配置与启动:
nginx -t通过;reload 或重启后 error_log 里没有新的 [error]、[crit] 行,worker 正常拉起。 - 请求结果:用与报错时相同的参数重放请求,返回体、状态码、响应头都与预期一致,而不只是“没报错”。
- 日志信号:搜索自己埋的 tag,确认进入分支、变量值与实际一致;注意多 worker 下同一请求可能只落在一个 worker,日志出现次数与 worker 数的关系要自己核对,不要把次数当结论。
- 异常路径:故意构造一次参数缺失或上游超时,确认 pcall 分支、错误返回和日志仍然符合设计。
- 清理后回归:删除临时 location、把 lua_code_cache 改回 on、把日志级别降到日常配置,再重放一次正常请求,确认功能还在。
判断是否达到目标的标准可以很朴素:同样的请求不再产生未预期的错误日志,且返回内容正确;如果仍偶发失败,说明还有并发或上游因素,不要急着下结论。
容易忽略的边界
- lua_code_cache off 会改变行为:模块每次请求重新加载,模块级 upvalue、局部缓存的状态都不一样,某些问题在 off 下根本不复现。排查完必须改回 on 并 reload,再确认一次。
- init 阶段 API 受限:init_by_lua* 里不能 cosocket、不能 ngx.say、拿不到请求信息,把这些代码写在那里会报“API disabled in the context”,容易被误判成语法错误。
- filter 阶段不能直接输出:header_filter_by_lua* 之后不能再 ngx.say;body_filter 里改响应体要按 chunk 处理,不能假设一次拿全。
- 日志级别要先于日志本身:error_log 设成 error 时,notice/info 级别输出看不到,print 的输出也常因此“消失”。先确认级别,再怀疑代码。
- timer 与子请求的错误不回流:这类错误只进 error_log,客户端无感知,排查时以日志为准。
- 生产限制:不建议在生产长期开 debug 日志级别或保留调试 location,可能带来日志量和信息暴露问题;需要临时开启时,排障完成即恢复,并在变更记录里写明。
- 版本与模块差异:不同 OpenResty 版本内置的 LuaJIT 与 lua-resty 库版本不同,同样的写法表现可能不一致,遇到与文档不符的行为需要结合自身版本确认,不要直接套用他人环境的结论。
- 权限:worker 运行用户需要对日志目录有写权限,改 error_log 路径后尤其要检查,否则报错会变成“打不开日志文件”。