Go GopherLua Go 回调返回数量写错会出现什么问题

我第一次把 GopherLua 的 Go 函数接进业务脚本时，回调本身没有报错，Lua 却拿到了 nil。后来发现，问题不在注册函数，而在“压入了几个值”和“return 几个值”没有对上。

GopherLua 的 Go 回调类型是 func(*LState) int。这个 int 不是业务状态码，而是告诉虚拟机：当前回调在栈顶准备了多少个 Lua 返回值。调用方还会通过 NRet 表达自己想接收多少个值。三者只要有一个写错，结果就可能变成 nil、少一个值，甚至把参数槽误当成返回值。

官方地址：https://github.com/yuin/gopher-lua

我遇到的症状：回调执行了，结果却不对

这类问题容易误判，因为 Go 回调已经进入了，日志也能看到，Lua 侧却表现为“函数没有返回值”。最常见的现场是：Go 代码调用 L.Push，最后却写了 return 0；或者一次压入一个值，却为了“保险”写成 return 2。

先不要急着改 Lua 脚本。检查回调时，先记录三个事实：回调到底压入了几个值、最后返回的整数是多少、调用方用 NRet 请求了几个值。它们分别对应“值在哪里”“有几个值”“最多取几个值”。

先分清三个数量：压入值、return 值和 NRet

GopherLua 的回调返回值可以按下面这条关系理解：

• 压入数量：回调调用了多少次 L.Push，这些值位于当前 LState 的栈顶。
• return 数量：Go 回调返回的整数，告诉 VM 从栈顶往前取多少个值。
• NRet：调用方希望接收的返回值数量，例如 CallByParam(lua.P{NRet: 1})。

一个只返回一个数字的回调，最小写法如下。这里的 return 1 必须和一次 L.Push 配对：

func add(L *lua.LState) int {
	// 从 Lua 的第 1、2 个参数读取整数，参数不合法时由 CheckInt 报错。
	left := L.CheckInt(1)
	right := L.CheckInt(2)

	// 把唯一的计算结果放到当前 LState 栈顶。
	L.Push(lua.LNumber(left + right))

	// 告诉 GopherLua：栈顶有 1 个值属于本次回调的返回值。
	return 1
}

这里不需要让 return 1 等于 Lua 业务上“加法结果是 1”。它描述的是返回值个数，不是返回值内容。

返回 0 时，为什么 Lua 看到的是 nil

假设回调已经执行了 L.Push(lua.LNumber(3))，但最后返回 0。VM 会把“可用返回值数量”当成零，不会把刚压入的数字复制到调用方的返回区。调用方如果仍然请求一个值，空出来的位置会按返回值复制规则补成 nil。

func addWrong(L *lua.LState) int {
	// 计算结果确实压入了栈，但返回数量没有同步更新。
	L.Push(lua.LNumber(3))

	// 错误：0 表示本次回调没有返回值。
	return 0
}

这个错误通常带来两个误导：第一，Go 回调内部的日志看起来完全正常；第二，Lua 侧只看到空值，很像是类型转换失败。遇到这种情况，先对照每个 L.Push，再看函数最后的整数。

返回数量写大时，为什么会拿到错位值

反方向的问题更隐蔽。回调只压入一个值却返回 2，VM 会按“有两个可用返回值”计算起始位置。栈上如果刚好还有参数或临时槽，复制范围就可能把不属于结果的槽位一起算进去；不足的部分则会用 nil 补齐。

func addTooMany(L *lua.LState) int {
	// 这里只准备了一个结果。
	L.Push(lua.LNumber(3))

	// 错误：声明了两个结果，第二个结果并不存在。
	return 2
}

所以不要把返回数量理解成“最多返回几个”。它是当前回调已经准备好的返回值数量。返回值多于调用方需要的数量时，调用方可以通过 NRet 只接收需要的部分；回调自己却不能用一个偏大的整数代替真实的压栈数量。

调用方的 NRet 也会改变你看到的结果

回调写对了，不代表调用方一定会取到全部结果。比如回调压入两个值并返回 2，但调用方使用 NRet: 1，最终只会保留一个结果。这不是回调丢值，而是调用方明确只要一个。

if err := L.CallByParam(lua.P{
	// 只取一个结果，并把运行时错误转换成 error 返回。
	Fn:      L.GetGlobal("add"),
	NRet:    1,
	Protect: true,
}, lua.LNumber(1), lua.LNumber(2)); err != nil {
	// 受保护调用失败时，优先把错误交给上层处理。
	return err
}

// 读取调用方保留下来的唯一结果。
result := L.Get(-1)
L.Pop(1) // 取完后弹出结果，避免继续占用栈空间。

排查时建议先让回调和调用方都只处理一个结果：回调只压入一次并返回 1，调用方使用 NRet: 1。单值链路正常后，再增加多返回值。这样能把“回调计数错误”和“调用方主动截断”分开。

我现在会按这张清单排查

1. 确认注册到 Lua 全局名上的确是目标 Go 函数，而不是同名旧函数。
2. 数一遍当前分支实际执行了多少次 L.Push，包括错误分支和提前返回分支。
3. 检查每个分支的 return n 是否和压入值数量一致。
4. 检查 CallByParam、Call 或包装器传入的 NRet 是否故意只取部分值。
5. 多返回值场景中，确认读取顺序与压栈顺序一致，并在读取后清理结果槽。

我觉得最稳妥的习惯是：把“返回多少个 Lua 值”当作回调接口的一部分写进函数旁边的注释或测试说明，而不是把它当成随手填写的整数。GopherLua 官方示例也是先 Push，再用准确的数量返回。

几个容易混淆的问题

回调返回的 int 是 Go 错误码吗？

不是。LGFunction 的整数表示 Lua 返回值数量。运行错误应通过 GopherLua 的错误机制或受保护调用返回。

Lua 只使用一个返回值，回调可以返回两个吗？

可以，但调用方的 NRet 会决定最终保留几个。不要为了兼容未知调用方而虚报数量；需要多返回值时，应让回调确实按顺序压入它们。

返回数量正确但仍然是 nil，下一步看哪里？

再看是否走了另一条分支、是否把 LNil 主动压入栈、调用方是否使用了错误的函数引用，以及 NRet 是否为零。

结论：把三个数量对齐，问题通常就结束了

Go GopherLua 回调最容易忽略的不是注册语法，而是返回协议：先把结果压入 LState，再返回准确的数量，最后确认调用方的 NRet 与预期一致。返回少了会让结果缺失，返回多了可能把其它栈槽带进结果，调用方 NRet 偏小则会主动截断。按这三个位置逐项对齐，比继续修改 Lua 脚本更快。