OpenResty里Lua脚本怎么调试

文章导读
OpenResty 下的 Lua 调试,先分清两件事:脚本挂在哪个阶段、错误去了哪里。启动期(init_by_lua*、init_worker_by_lua*)出错通常表现为 nginx -t 不通过或启动即退出;请求期(rewrite/access/content/header_filter/body_filter/log_by_lua*)出错往往只影响单个请求,客户端看到 500 而关键信息在
📋 目录
  1. Ⅰ 先确认当前场景和目标
  2. Ⅱ 按这个顺序处理
  3. Ⅲ 改完后怎么验证
  4. Ⅳ 容易忽略的边界
A A

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。这一步能跑通,说明日志通道是开的,后面加的埋点才看得到。

按这个顺序处理

  1. 先让错误可见。用 ngx.log 而不是裸 print,级别自己定。注意 ngx.log 只接受字符串和数字,nil、table 直接传会抛参数错误,反而把真正的错误盖住,建议统一转成字符串。
  2. 做一个最小复现点。单独开一个 location,用 content_by_lua_block 把待排查的代码搬进去,用 curl 直打,排除上游、代理、鉴权等干扰。
  3. 按阶段分流。init 类错误看 nginx -t 与启动时的 error_log;请求类错误看带 request 行和 lua 行号的堆栈;timer 回调里的错误不会返回给客户端,只能从 error_log 找。
  4. 纯 Lua 逻辑外提验证。OpenResty 自带的 resty 命令行可以单独跑一段 Lua,适合验证字符串处理、JSON 编解码、模块加载;但它没有真实请求上下文,ngx.say、ngx.req 这类 API 的行为与线上不同,不能拿它替代请求级验证。
  5. 收尾清理。定位完成后把 INFO 级日志降回需要的级别,删除临时 location,恢复 lua_code_cache on。

下面是一个可直接替换使用的日志包装片段,放在 lua_package_path 覆盖的目录里,例如 conf/lua/dbg.lua:

OpenResty里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 路径后尤其要检查,否则报错会变成“打不开日志文件”。