Lua 宿主排错：加载、回调、内存与关闭边界

前置为完整工程。示例未执行；排查步骤是后续运行时的检查顺序，错误文字仅是预期。不要先通过扩大权限、打开全部标准库或忽略类型校验消除报错，应先确认失败属于哪个边界。

按阶段识别错误

Lua宿主加载成功却不能执行怎么排查？区分 load、chunk、contract、callback 和 result 阶段。load 失败通常是文件、文本编译或模式不匹配；chunk 成功只说明顶层代码完成，还需检查它返回函数；callback 才是业务函数执行；result 则检查返回值是否符合宿主协议。

本例保留 Request.phase，主程序输出 error[阶段]；这比只检查错误字符串更稳定。not-function.lua 应到 contract，wrong-result.lua 到 result，syntax-error.lua 在 load；若把它们都叫“Lua 脚本错误”，读者无法判断修文件路径还是修函数接口。保护调用非零状态下不能继续把栈顶当成功返回值解析。

若 attempt to call a nil value 指向 missing_capability，这是故意未提供的能力或脚本拼写错误。当前状态没有打开标准库，所以 print 和 require 也不存在；需求确实需要时应逐项设计导出，而不是调用 luaL_openlibs 后仍保留“只有两个计数器方法”的能力描述。

错误对象与 traceback

Lua错误对象不是字符串怎么办？先判断实际类型，再选择报告策略，不对任意对象直接 %s。Lua 抛出的值可以不是字符串；C 调用 lua_error 会使用栈顶值作为错误对象，pcall 不保证把它变成文本。本例对字符串使用长度输出，对其他类型固定输出 non-string error object，避免错误处理再次执行对象元方法。

若需要 traceback，应在 pcall 前放置消息处理器，并把其普通栈索引传给 msgh，处理器在栈展开前调用 luaL_traceback。处理器自身可能失败，因此还要处理 LUA_ERRERR；内存错误等情形不能承诺获得完整堆栈。不要在 pcall 返回后再试图恢复已经展开的原调用链。

本例 msgh=0，没有生成 traceback；日志保留阶段、退出码和原错误字节。日志若需要持久存储，必须在 lua_close 前复制所需数据，并约定长度与编码，避免泄漏脚本路径或打印二进制字节影响日志协议。这里的 fwrite 只是演示正确字节长度，不是完整结构化日志系统。

栈失衡与引用泄漏

Lua宿主循环调用后内存增长怎么查？分别检查栈顶和 registry 引用，清栈不能解除 registry 引用。记录每轮入口与出口 top，检查错误分支是否只留下一个错误对象并及时消耗；再记录每轮成功 ref 与 unref 的数量及对应状态。字符串、函数和 userdata 可因引用仍在而持续可达，强制 GC 无法回收强引用对象。

不要把 lua_gettop 恒定解释为“没有泄漏”。registry、全局表、闭包 upvalue 和外部 C 分配都不等于栈值数量。也不要用反复 lua_settop(0) 隐藏协议错误，它可能删掉调用者的值。本例只在 main 的最外层清零，因为这一层拥有整个状态，且没有 to-be-closed 栈槽。

一次性状态退出时统一 lua_close 能回收其 Lua 对象，但长期宿主需要在替换回调时先建立新引用、完成校验，再按明确顺序替换旧引用并 unref，失败保留旧版本或显式拒绝切换。引用数字可复用，日志中应同时记录状态或请求归属，不能只凭 ref 整数关联对象。

版本、ABI 与库路径

Lua宿主链接失败或启动崩溃先查什么？先核对头文件、库文件和运行时装载路径，再看架构和数值配置。undefined reference 或 unresolved external 通常发生在链接层，不是 Lua chunk 语法错误；找不到 DLL/共享库发生在装载层，也不会被 lua_pcall 捕获。

本例固定 5.4.9；CMake 成功找到一个路径，仍应审阅它实际选择的开发库，避免系统旧库优先。Windows 导入库与 DLL 要对应，静态链接还要包含所需平台库；Linux/macOS 的运行时查找策略与 Windows 不同。不能把把头文件复制到项目目录当成依赖配置完成。

如果不同模块共享一个状态，它们必须使用兼容 Lua ABI 与构建配置；跨模块 malloc/free 或运行库边界也需要清楚的释放协议。本文没有构建任何平台二进制，所以没有对具体链接错误作实测结论。

内存统计与资源上限

Lua GC能限制整个宿主内存吗？不能。GC 处理 Lua 管理对象的可达性，既不是固定内存预算，也不覆盖任意 C 外部分配和进程开销。可达的大表不会因触发 GC 就变成垃圾；进程 RSS 也不等于 Lua 内存统计值。

自定义 allocator 可以追踪 Lua 向它请求的块，但必须遵守 lua_Alloc 的分配/重分配/释放契约，区分 osize 的含义、失败时原块仍有效以及新大小为零的释放；计数运算本身也要防止溢出。不能随意依赖 osize 直接加减而不核对回调语义。工程使用默认 allocator，没有实现字节配额，故不宣称内存上限。

CPU 预算同样独立：关闭标准库并不阻止死循环，指令 hook 也不能覆盖任意长期阻塞 C 回调。生产策略应按威胁模型选择进程超时、内存限制、允许能力和回收方法。本课程只覆盖可信同步插件的接口正确性，未实现安全执行恶意脚本。

练习

1. top 每次相等，但每轮 luaL_ref 后从不 unref，强制 GC 会解决吗？
2. 插件报错后有状态变更，为什么 pcall 不能替你回滚？
3. Lua 库找不到导致进程无法启动，应修改插件代码还是先查装载配置？

参考解答

1. 不会。registry 强引用使对象仍可达；应按请求/回调归属解除引用，避免为诊断随意清空整个 registry。
2. pcall 只改变控制流与返回状态，不记录业务写入日志；需要宿主显式快照、暂存后提交或销毁独立请求状态。
3. 先查装载路径、架构与库版本，错误发生在任何 Lua 代码执行之前；pcall 无法捕获操作系统装载失败。

依据：Lua 5.4 错误处理、内存分配器、引用辅助 API，核对 2026-10-17。理论与源码审阅不能替代实际构建、压力测试或分配失败注入。