Go GopherLua 怎么把 Go 函数注册给 Lua 调用

如果 Go 程序要把一小段 Lua 当作可配置脚本，最小的接入方式不是把 Go 函数改写成 Lua，而是让它实现 GopherLua 需要的 lua.LGFunction 签名，再用 L.NewFunction 包装，最后通过 SetGlobal 或一个命名空间表暴露给脚本。

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

注册链路可以记成：Go 函数接收 *lua.LState，从状态中读取 Lua 参数，把返回值压回状态，再由返回整数告诉 GopherLua 有几个结果；脚本侧通过 DoString 或 DoFile 接收调用错误。

先分清 Go 函数与 Lua 函数的边界

GopherLua 的注册函数不是普通的 func(string) string。它的公开函数类型是 lua.LGFunction，本质上接收一个 *lua.LState 并返回整数。参数和结果都通过这个状态对象传递：Lua 调用时把参数放进状态，Go 函数用读取方法取出结果，再用 Push 放回 Lua 可见的值。

这层边界很重要。Go 函数本身不需要知道 Lua 的调用表达式，但必须遵守状态的参数位置、GopherLua 值类型和返回值数量约定；否则脚本可能拿到空值、错误数量，或者在参数类型不对时直接失败。

用 L.NewFunction 创建 Lua 可调用值

先写一个符合 lua.LGFunction 约定的 Go 函数，再创建状态并注册到全局名字。下面的例子让 Lua 调用 greet 时传入一个字符串，Go 侧读取第一个参数并返回一条字符串。

package main

import (
    "fmt"

    "github.com/yuin/gopher-lua"
)

// greet 从 Lua 的第一个参数读取姓名，并把一个字符串结果压回状态。
func greet(L *lua.LState) int {
    name := L.CheckString(1)
    L.Push(lua.LString("你好，" + name))
    return 1 // 告诉 GopherLua 当前函数返回一个结果。
}

func main() {
    L := lua.NewState()
    defer L.Close() // LState 持有运行时资源，宿主结束时统一释放。

    L.SetGlobal("greet", L.NewFunction(greet))
    script := `print(greet("Lua")) -- Lua 侧调用已注册的 Go 函数`
    if err := L.DoString(script); err != nil {
        // 脚本解析或调用失败时，把错误交回 Go 的入口层。
        panic(fmt.Errorf("执行 Lua 脚本失败: %w", err))
    }
}

L.NewFunction(greet) 负责把 Go 函数转换成 Lua 可以持有的函数值，L.SetGlobal 再把它绑定到脚本可见的 greet 名称。绑定完成后，Lua 不需要知道 Go 函数的真实包名，只按这个名称调用即可。

参数类型和返回值数量要对齐

状态对象的参数位置从 1 开始。CheckString(1) 不只是取值，也会把“第一个参数必须是字符串”这个约束放在注册函数边界内；如果脚本传入其他类型，当前调用会失败，错误可以沿着 DoString 返回到 Go。

返回值则相反：先用 L.Push 压入一个或多个 LValue，再返回压入值的数量。返回 0 表示没有结果，返回 1 表示 Lua 可以接收一个结果；只压入一个值却返回两个，会让调用契约变得不清楚。

func add(L *lua.LState) int {
    // 两个参数都由注册函数校验，避免把 Lua 的动态值直接当作 Go 数字使用。
    left := L.CheckInt(1)
    right := L.CheckInt(2)
    L.Push(lua.LNumber(left + right))
    return 1 // 只压入一个和，因此返回值数量也必须是 1。
}

func registerMath(L *lua.LState) {
    // 表中的键是 Lua 侧的方法名，值仍然是 LGFunction 包装后的函数。
    mathTable := L.NewTable()
    L.SetField(mathTable, "add", L.NewFunction(add))
    L.SetGlobal("mathx", mathTable)
}

当入口数量增加时，把函数放在 mathx.add 这类命名空间下比不断增加全局函数更容易维护。无论使用全局名字还是表字段，函数内部的参数约束和返回值数量都应保持明确。

让脚本错误回到 Go

注册函数只负责当前调用的参数检查和结果准备，脚本入口负责接收错误。示例中的 DoString 可以换成 DoFile，但都应保留返回错误的处理，不要在注册函数中打印后继续返回一个看似有效的空结果。

如果注册函数需要主动报告业务错误，可以在 Go 侧先把错误转换为 Lua 可见的失败路径，并由脚本入口统一决定是终止、降级还是记录。文章的重点是注册边界，不要把错误吞掉后让 Lua 继续使用不完整数据。

选择全局注册还是命名空间注册

少量入口用全局绑定最直观；当脚本开始同时访问文件、字符串、业务规则等多组能力时，应优先考虑命名空间。这样既减少全局名称碰撞，也能让宿主程序更容易限制每组能力的暴露范围。

常见问题

为什么注册函数的参数是 *lua.LState，不是业务参数？

因为 GopherLua 需要通过统一状态传递不同数量和类型的 Lua 值。业务参数由 CheckString、CheckInt 等方法从状态中读取，返回值也通过状态压回。

返回值数量为什么必须和 Push 次数一致？

返回整数是 Go 函数向 Lua 调用约定声明的结果数量。压入和声明不一致时，调用方无法稳定判断哪些值属于本次返回。

多个 Go 函数应该都注册成全局变量吗？

少量函数可以这样做；如果函数有明确的业务分组，建议放进表字段或模块导出表，用命名空间表达能力边界。

小结

Go GopherLua 注册函数的固定链路是：实现 lua.LGFunction，用 L.NewFunction 包装，再用 SetGlobal 或表字段交给 Lua 调用。函数内部从 LState 读取参数、压入返回值并返回数量；脚本入口用 DoString 或 DoFile 接收错误，最后让每个 LState 在明确的生命周期边界关闭。