Lua脚本调用C函数报错怎么解决

Lua 调用 C 函数报错，先别急着改代码，先分清错在哪一层：是 require 根本没找到模块，是动态库加载时符号解析失败，还是加载成功但调用时参数或返回值对不上。这三种情况的排查路径完全不同，把加载期的错当成调用期的错去改，通常只会把问题挪到下一次运行。

先按“加载失败、符号解析失败、调用参数不匹配”三类把报错分开：require 找不到模块就查 package.cpath 和 luaopen_ 导出名，undefined symbol 就查 Lua 版本 API 和链接方式，bad argument 就查函数签名与返回值个数。改完在同一宿主程序里用最小脚本 require 并调用一次，确认类型和返回结果后再放回业务脚本。宿主是 LuaJIT 或自编译 lua_State 时，不要照搬系统 Lua 的编译参数。

先确认当前场景和目标

报错信息本身是第一手材料，先完整抄下来，不要只看最后一行。判断条件大致是这样：如果错误发生在 require 语句上，属于加载期；如果 require 返回了 table 但调用某个字段报错，属于调用期；如果报错里出现 .so 路径和 undefined symbol，属于链接与符号问题。

同时确认三项环境信息，它们的组合决定了后面能怎么修：

宿主是什么：系统 lua、lua5.1/5.3/5.4、LuaJIT、OpenResty 这类自带 Lua 的程序，还是自己用 C 嵌进去的 lua_State。用 lua -v、print(_VERSION)、print(jit and jit.version) 各取一次。
模块怎么被加载：走 require("mymod") 的 C 模块约定，还是宿主直接 lua_register/luaL_dostring 注册的全局函数。前者要求导出 luaopen_mymod，后者不需要。
编译产物是什么：给谁编译的、头文件来自哪个 Lua 版本。print(package.cpath) 能看到搜索路径，路径里第一个命中的 .so 就是要排查的对象。

按这个顺序处理

验证模块名与搜索路径的映射。 require("a.b") 会去找 a/b.so 并期望导出 luaopen_a_b。名字里有下划线或点，最容易在这里对不上。先把 .so 放到当前目录，用 LUA_CPATH="./?.so" 临时指定，排除路径干扰。
看导出符号和未定义符号。 nm -D --defined-only ./mymod.so | grep luaopen 应为空则说明符号没导出；ldd -r ./mymod.so 会列出运行期解析不到的符号。C++ 编译的模块必须在 luaopen_ 上加 extern "C"，否则名字被修饰，Lua 永远找不到。
对齐 Lua 版本 API。 5.1 用 luaL_register，5.2 以后用 luaL_newlib；LuaJIT 走 5.1 的 API。头文件和宿主版本不一致时，编译能过、加载会崩。
检查链接方式。 模块是给已有 Lua 的宿主加载的，通常不要再把 liblua 静态编进 .so，否则容易出现“multiple Lua VMs detected”或状态指针不一致。Linux 上一般只加 -fPIC -shared，符号留给宿主解析。
最后才查函数签名。 C 函数必须是 static int f(lua_State *L)，返回压栈的结果个数；忘记 return 或返回数量写错，Lua 侧看到的就是 nil 或栈错乱。

/* mymod.c：一份可兼容 5.1 与 5.3+ 的最小骨架 */
#include <lua.h>
#include <lauxlib.h>

static int l_add(lua_State *L) {
    lua_Integer a = luaL_checkinteger(L, 1);
    lua_Integer b = luaL_checkinteger(L, 2);
    lua_pushinteger(L, a + b);
    return 1;                 /* 返回结果个数 */
}

static const luaL_Reg mymod[] = {
    {"add", l_add},
    {NULL, NULL}
};

#if LUA_VERSION_NUM >= 502
int luaopen_mymod(lua_State *L) { luaL_newlib(L, mymod); return 1; }
#else
int luaopen_mymod(lua_State *L) { luaL_register(L, "mymod", mymod); return 1; }
#endif

编译时把 -I 指向宿主实际使用的头文件目录，例如 cc -O2 -fPIC -shared -I/usr/include/lua5.3 -o mymod.so mymod.c；macOS 上换成 -bundle -undefined dynamic_lookup。参数里的路径要按自己的环境替换，不确定头文件在哪就先用 pkg-config --cflags lua5.3 之类的方式确认真实路径。

改完后怎么验证

不要直接拿业务脚本验证，先用一行最小脚本，并且必须用报错时的同一个宿主程序执行：

lua -e 'print(_VERSION); local m = require("mymod"); print(type(m.add), m.add(1, 2))'

预期信号是：require 正常返回 table，type(m.add) 为 function，调用返回计算结果。如果宿主是 OpenResty 或嵌入程序，就换成对应的 resty 命令或你自己的可执行程序，因为系统 lua 通过不代表宿主通过。另一个明显信号是错误文本的变化：从 undefined symbol 变成 bad argument，说明加载环节已经通了，剩下的是参数问题。

调试期反复改 .so 时，require 会缓存已加载模块，需要先 package.loaded["mymod"] = nil 再 require，否则你看到的还是旧版本的行为。这一步没做，很容易误判“改了没效果”。

容易忽略的边界

版本不通用：5.1 与 5.3/5.4 的 API 和整数子类型不同，5.4 的 integer/float 与 5.1 的 number 语义也不完全一致，跨版本复用同一个 .so 基本不可行。
LuaJIT 与标准 Lua 的头文件不能混用；给 LuaJIT 编译的模块，其 lua_Number 与 ABI 细节需要按宿主实际情况确认。
package.cpath 中的相对路径依赖进程当前目录，服务方式启动时工作目录变化会导致“昨天能加载，今天找不到”。生产配置里建议写绝对路径。
动态库自身依赖的其他 .so 缺失时，报错同样出现在 require 阶段，需要看 ldd 输出，而不是改 Lua 代码。
如果宿主版本无法更改、又没有稳定头文件对应，回退方案是走 FFI 或把 C 侧能力做成独立进程/命令行工具由 Lua 调用，避免和宿主 ABI 强绑定；代价是调用开销和进程管理复杂度上升，不适合高频细粒度调用。