【Lua进阶系列】Lua 调试机制详解：从虚拟机调用栈、错误传播到 debug 库

🔥 本文专栏：Lua

🌸作者主页：努力努力再努力wz

💪 今日博客励志语录：人生可以有遗憾，但不要让对遗憾的恐惧，成为你拒绝开始的理由。

---

思维导图

这里先给出本文的整体逻辑。我们的重点并不是按函数名称逐个背 API，而是先认识调试机制依赖什么 ，再理解具体的调试函数为什么能工作。
#mermaid-svg-ules3LzDhf0SfAsq{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-ules3LzDhf0SfAsq .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-ules3LzDhf0SfAsq .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-ules3LzDhf0SfAsq .error-icon{fill:#552222;}#mermaid-svg-ules3LzDhf0SfAsq .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ules3LzDhf0SfAsq .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-ules3LzDhf0SfAsq .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ules3LzDhf0SfAsq .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ules3LzDhf0SfAsq .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-ules3LzDhf0SfAsq .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ules3LzDhf0SfAsq .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ules3LzDhf0SfAsq .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ules3LzDhf0SfAsq .marker.cross{stroke:#333333;}#mermaid-svg-ules3LzDhf0SfAsq svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ules3LzDhf0SfAsq p{margin:0;}#mermaid-svg-ules3LzDhf0SfAsq .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-ules3LzDhf0SfAsq .cluster-label text{fill:#333;}#mermaid-svg-ules3LzDhf0SfAsq .cluster-label span{color:#333;}#mermaid-svg-ules3LzDhf0SfAsq .cluster-label span p{background-color:transparent;}#mermaid-svg-ules3LzDhf0SfAsq .label text,#mermaid-svg-ules3LzDhf0SfAsq span{fill:#333;color:#333;}#mermaid-svg-ules3LzDhf0SfAsq .node rect,#mermaid-svg-ules3LzDhf0SfAsq .node circle,#mermaid-svg-ules3LzDhf0SfAsq .node ellipse,#mermaid-svg-ules3LzDhf0SfAsq .node polygon,#mermaid-svg-ules3LzDhf0SfAsq .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ules3LzDhf0SfAsq .rough-node .label text,#mermaid-svg-ules3LzDhf0SfAsq .node .label text,#mermaid-svg-ules3LzDhf0SfAsq .image-shape .label,#mermaid-svg-ules3LzDhf0SfAsq .icon-shape .label{text-anchor:middle;}#mermaid-svg-ules3LzDhf0SfAsq .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-ules3LzDhf0SfAsq .rough-node .label,#mermaid-svg-ules3LzDhf0SfAsq .node .label,#mermaid-svg-ules3LzDhf0SfAsq .image-shape .label,#mermaid-svg-ules3LzDhf0SfAsq .icon-shape .label{text-align:center;}#mermaid-svg-ules3LzDhf0SfAsq .node.clickable{cursor:pointer;}#mermaid-svg-ules3LzDhf0SfAsq .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-ules3LzDhf0SfAsq .arrowheadPath{fill:#333333;}#mermaid-svg-ules3LzDhf0SfAsq .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ules3LzDhf0SfAsq .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ules3LzDhf0SfAsq .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ules3LzDhf0SfAsq .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-ules3LzDhf0SfAsq .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ules3LzDhf0SfAsq .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-ules3LzDhf0SfAsq .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ules3LzDhf0SfAsq .cluster text{fill:#333;}#mermaid-svg-ules3LzDhf0SfAsq .cluster span{color:#333;}#mermaid-svg-ules3LzDhf0SfAsq div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-ules3LzDhf0SfAsq .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-ules3LzDhf0SfAsq rect.text{fill:none;stroke-width:0;}#mermaid-svg-ules3LzDhf0SfAsq .icon-shape,#mermaid-svg-ules3LzDhf0SfAsq .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ules3LzDhf0SfAsq .icon-shape p,#mermaid-svg-ules3LzDhf0SfAsq .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-ules3LzDhf0SfAsq .icon-shape rect,#mermaid-svg-ules3LzDhf0SfAsq .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ules3LzDhf0SfAsq .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-ules3LzDhf0SfAsq .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-ules3LzDhf0SfAsq :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Lua 源码
加载与编译
字节码和执行所需数据
源码行号等调试辅助信息
Lua 虚拟机执行
维护调用帧和运行时状态
可能发生运行时错误
主动 error / assert
虚拟机检测到非法操作
错误对象向外传播
pcall：保护调用边界
xpcall：先执行错误处理函数
Lua 调试接口
traceback：调用链文本
getinfo：函数及调用帧信息
getlocal：活跃局部变量

整个学习过程可以概括为：

Lua 如何执行代码 → 虚拟机保存了哪些运行时状态 → 错误如何产生和传播 → 如何在错误现场消失前获取信息 → 如何具体读取调用链、函数信息和局部变量。

---

一、从 Lua 的执行机制重新认识调试

1. 我们之前关注的是程序如何正常执行

在之前的 Lua 学习中，我们已经认识到，一个 Lua 脚本不是被 CPU 直接作为 Lua 源代码执行的。

例如：

local function add(a, b)
    return a + b
end

print(add(10, 20))

它的执行过程可以简化为：

Lua 脚本文件
    ↓
加载、词法和语法分析、编译
    ↓
生成可执行的 Lua 函数（Chunk）及字节码
    ↓
Lua 虚拟机
    ↓
取指 → 分派 → 执行

在这里，虚拟机不仅执行算术指令，还需要处理函数调用、函数返回、访问变量、条件跳转等操作。

但是，程序并不一定能够按照预期执行。如果执行期间出现错误，我们自然希望解决两个问题：

第一个问题：错误发生在什么位置？

也就是具体的源文件、行号，以及错误的原因。

第二个问题：程序是如何执行到这个位置的？

例如 main() 调用了 login()，login() 又调用了 checkPlayer()，最终在 checkPlayer() 内部发生错误。此时仅仅知道最后一行报错，并不足以解释整个出错过程。

所以，调试需要获得两类信息：源码位置 与运行时函数调用关系。

2. 函数调用栈原本就存在，并不是为了调试才创建的

我们之前已经学习过函数调用机制。当一个函数调用另一个函数时，虚拟机必须维护相关执行状态，才能保证被调用函数返回后，调用者可以继续执行。

例如：

local function C()
    local gold = 100
    print(gold)
end

local function B()
    C()
end

local function A()
    B()
end

A()

执行到 C() 内部时，A()、B()、C() 都尚未返回，因此当前存在一条活跃调用链。
#mermaid-svg-2PU19tP0fV0vrfb1{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-2PU19tP0fV0vrfb1 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-2PU19tP0fV0vrfb1 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-2PU19tP0fV0vrfb1 .error-icon{fill:#552222;}#mermaid-svg-2PU19tP0fV0vrfb1 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-2PU19tP0fV0vrfb1 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-2PU19tP0fV0vrfb1 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-2PU19tP0fV0vrfb1 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-2PU19tP0fV0vrfb1 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-2PU19tP0fV0vrfb1 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-2PU19tP0fV0vrfb1 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-2PU19tP0fV0vrfb1 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-2PU19tP0fV0vrfb1 .marker.cross{stroke:#333333;}#mermaid-svg-2PU19tP0fV0vrfb1 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-2PU19tP0fV0vrfb1 p{margin:0;}#mermaid-svg-2PU19tP0fV0vrfb1 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-2PU19tP0fV0vrfb1 .cluster-label text{fill:#333;}#mermaid-svg-2PU19tP0fV0vrfb1 .cluster-label span{color:#333;}#mermaid-svg-2PU19tP0fV0vrfb1 .cluster-label span p{background-color:transparent;}#mermaid-svg-2PU19tP0fV0vrfb1 .label text,#mermaid-svg-2PU19tP0fV0vrfb1 span{fill:#333;color:#333;}#mermaid-svg-2PU19tP0fV0vrfb1 .node rect,#mermaid-svg-2PU19tP0fV0vrfb1 .node circle,#mermaid-svg-2PU19tP0fV0vrfb1 .node ellipse,#mermaid-svg-2PU19tP0fV0vrfb1 .node polygon,#mermaid-svg-2PU19tP0fV0vrfb1 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-2PU19tP0fV0vrfb1 .rough-node .label text,#mermaid-svg-2PU19tP0fV0vrfb1 .node .label text,#mermaid-svg-2PU19tP0fV0vrfb1 .image-shape .label,#mermaid-svg-2PU19tP0fV0vrfb1 .icon-shape .label{text-anchor:middle;}#mermaid-svg-2PU19tP0fV0vrfb1 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-2PU19tP0fV0vrfb1 .rough-node .label,#mermaid-svg-2PU19tP0fV0vrfb1 .node .label,#mermaid-svg-2PU19tP0fV0vrfb1 .image-shape .label,#mermaid-svg-2PU19tP0fV0vrfb1 .icon-shape .label{text-align:center;}#mermaid-svg-2PU19tP0fV0vrfb1 .node.clickable{cursor:pointer;}#mermaid-svg-2PU19tP0fV0vrfb1 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-2PU19tP0fV0vrfb1 .arrowheadPath{fill:#333333;}#mermaid-svg-2PU19tP0fV0vrfb1 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-2PU19tP0fV0vrfb1 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-2PU19tP0fV0vrfb1 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-2PU19tP0fV0vrfb1 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-2PU19tP0fV0vrfb1 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-2PU19tP0fV0vrfb1 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-2PU19tP0fV0vrfb1 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-2PU19tP0fV0vrfb1 .cluster text{fill:#333;}#mermaid-svg-2PU19tP0fV0vrfb1 .cluster span{color:#333;}#mermaid-svg-2PU19tP0fV0vrfb1 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-2PU19tP0fV0vrfb1 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-2PU19tP0fV0vrfb1 rect.text{fill:none;stroke-width:0;}#mermaid-svg-2PU19tP0fV0vrfb1 .icon-shape,#mermaid-svg-2PU19tP0fV0vrfb1 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-2PU19tP0fV0vrfb1 .icon-shape p,#mermaid-svg-2PU19tP0fV0vrfb1 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-2PU19tP0fV0vrfb1 .icon-shape rect,#mermaid-svg-2PU19tP0fV0vrfb1 .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-2PU19tP0fV0vrfb1 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-2PU19tP0fV0vrfb1 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-2PU19tP0fV0vrfb1 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 当前 Lua 调用栈------栈顶在上
C() 调用帧

正在执行；局部变量 gold
B() 调用帧

等待 C() 返回
A() 调用帧

等待 B() 返回
主 Chunk 调用帧

等待 A() 返回

这里要注意，调用链 与调用栈相关，但不是同一个概念：

• 调用链描述函数之间的调用关系。
• 调用栈及调用帧是 Lua 运行时维护函数调用状态的内部机制。

我们可以把调用帧理解成一次函数调用所对应的运行时记录，而局部变量的值、执行位置等状态由调用帧、栈槽等内部结构共同管理。

因此，调试机制不是重新执行程序，去猜测函数之间发生了什么，而是借助虚拟机已经维护的运行时状态，读取当前仍然存在的调用关系。

这里还有一个限制：调用栈记录的是尚未结束的调用，而不是程序启动以来的全部函数调用历史。

---

二、编译结果为什么还能提供文件名和行号？

到这里，我们已经能够理解为什么调用栈可以帮助定位调用关系。但是还有一个问题：

虚拟机执行的是字节码，而不是源码，它怎么知道某条指令对应源文件中的哪一行？

1. 编译结果不仅有字节码指令

我们之前把 Lua 编译过程简化为"源码编译成字节码"，这并没有问题，但它省略了一些内部细节。

对于 Lua 函数，编译结果中的函数原型（Proto）不仅包含字节码指令和执行所需数据 ，还可以保存辅助调试的信息。
#mermaid-svg-UWQCoAXWXBd2ClCa{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-UWQCoAXWXBd2ClCa .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-UWQCoAXWXBd2ClCa .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-UWQCoAXWXBd2ClCa .error-icon{fill:#552222;}#mermaid-svg-UWQCoAXWXBd2ClCa .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-UWQCoAXWXBd2ClCa .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-UWQCoAXWXBd2ClCa .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-UWQCoAXWXBd2ClCa .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-UWQCoAXWXBd2ClCa .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-UWQCoAXWXBd2ClCa .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-UWQCoAXWXBd2ClCa .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-UWQCoAXWXBd2ClCa .marker{fill:#333333;stroke:#333333;}#mermaid-svg-UWQCoAXWXBd2ClCa .marker.cross{stroke:#333333;}#mermaid-svg-UWQCoAXWXBd2ClCa svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-UWQCoAXWXBd2ClCa p{margin:0;}#mermaid-svg-UWQCoAXWXBd2ClCa .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-UWQCoAXWXBd2ClCa .cluster-label text{fill:#333;}#mermaid-svg-UWQCoAXWXBd2ClCa .cluster-label span{color:#333;}#mermaid-svg-UWQCoAXWXBd2ClCa .cluster-label span p{background-color:transparent;}#mermaid-svg-UWQCoAXWXBd2ClCa .label text,#mermaid-svg-UWQCoAXWXBd2ClCa span{fill:#333;color:#333;}#mermaid-svg-UWQCoAXWXBd2ClCa .node rect,#mermaid-svg-UWQCoAXWXBd2ClCa .node circle,#mermaid-svg-UWQCoAXWXBd2ClCa .node ellipse,#mermaid-svg-UWQCoAXWXBd2ClCa .node polygon,#mermaid-svg-UWQCoAXWXBd2ClCa .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-UWQCoAXWXBd2ClCa .rough-node .label text,#mermaid-svg-UWQCoAXWXBd2ClCa .node .label text,#mermaid-svg-UWQCoAXWXBd2ClCa .image-shape .label,#mermaid-svg-UWQCoAXWXBd2ClCa .icon-shape .label{text-anchor:middle;}#mermaid-svg-UWQCoAXWXBd2ClCa .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-UWQCoAXWXBd2ClCa .rough-node .label,#mermaid-svg-UWQCoAXWXBd2ClCa .node .label,#mermaid-svg-UWQCoAXWXBd2ClCa .image-shape .label,#mermaid-svg-UWQCoAXWXBd2ClCa .icon-shape .label{text-align:center;}#mermaid-svg-UWQCoAXWXBd2ClCa .node.clickable{cursor:pointer;}#mermaid-svg-UWQCoAXWXBd2ClCa .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-UWQCoAXWXBd2ClCa .arrowheadPath{fill:#333333;}#mermaid-svg-UWQCoAXWXBd2ClCa .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-UWQCoAXWXBd2ClCa .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-UWQCoAXWXBd2ClCa .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-UWQCoAXWXBd2ClCa .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-UWQCoAXWXBd2ClCa .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-UWQCoAXWXBd2ClCa .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-UWQCoAXWXBd2ClCa .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-UWQCoAXWXBd2ClCa .cluster text{fill:#333;}#mermaid-svg-UWQCoAXWXBd2ClCa .cluster span{color:#333;}#mermaid-svg-UWQCoAXWXBd2ClCa div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-UWQCoAXWXBd2ClCa .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-UWQCoAXWXBd2ClCa rect.text{fill:none;stroke-width:0;}#mermaid-svg-UWQCoAXWXBd2ClCa .icon-shape,#mermaid-svg-UWQCoAXWXBd2ClCa .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-UWQCoAXWXBd2ClCa .icon-shape p,#mermaid-svg-UWQCoAXWXBd2ClCa .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-UWQCoAXWXBd2ClCa .icon-shape rect,#mermaid-svg-UWQCoAXWXBd2ClCa .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-UWQCoAXWXBd2ClCa .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-UWQCoAXWXBd2ClCa .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-UWQCoAXWXBd2ClCa :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 查询时结合
运行时状态
Lua 源码文件
Lua 编译器
函数原型 Proto
执行所需数据

指令、常量、子函数原型等
调试辅助信息

源码标识、行号映射、局部变量名称等
虚拟机执行
调试接口

这里我们必须区分：

字节码指令 负责告诉虚拟机要执行什么操作；调试信息则帮助调试接口把执行位置关联到源码中的位置。

因此，调试信息不是另一套"用于调试的字节码"，也不是需要虚拟机逐条执行的指令。

例如，虚拟机执行一条加法指令时，并不需要知道这条指令来自源码第几行；但如果我们希望报错信息显示源码位置，就需要相应的调试信息来辅助定位。

2. 什么叫剥离调试信息？

既然源码行号、局部变量名等信息不是正常执行字节码所必需的，那么在生成预编译文件时，就可以选择删除这部分辅助信息，以减小文件体积。

例如：

# 默认保留调试信息
luac -o normal.luac test.lua

# 生成预编译文件时剥离调试信息
luac -s -o stripped.luac test.lua

其中 -s 就是 strip，即剥离调试信息。

剥离之后，程序通常仍然可以正常执行，虚拟机也仍然维护函数调用栈；但是源码行号、局部变量原始名称等信息可能无法完整获取，从而增加调试难度。

所以，虚拟机能支持调试，并不只是因为编译器保留了调试信息，而是因为三个部分共同发挥作用：编译阶段提供源码辅助信息，执行阶段维护调用状态，调试接口负责查询这些信息。

3. 从 Lua 虚拟机内部到 debug 库

这里再联系此前学习 Lua 标准库时建立过的认识：debug 本质上是一个 Table，里面提供了 traceback、getinfo、getlocal 等调试函数。

不过，这些函数之所以能够读取调用栈，并不是因为普通 Lua 代码自己重新维护了一份调用栈，而是因为 Lua 运行时本身就提供了相应的调试接口。

从标准 Lua 5.4 的实现层次上，我们可以简单理解为：

Lua 脚本
    ↓
debug.getinfo() / debug.getlocal() / debug.traceback()
    ↓
Lua 标准调试库与辅助库
    ↓
Lua C API 调试接口（例如 lua_getstack、lua_getinfo、lua_getlocal）
    ↓
虚拟机正在维护的调用帧、栈槽、执行位置和源码调试信息

这也是为什么我们可以在 Lua 脚本层直接调用 debug.getinfo()，而不必亲自进入 Lua 虚拟机的 C 源码去查找调用帧。

需要注意，调用栈信息属于运行时状态 ，源码行号等属于编译后保留的辅助信息。调试接口可以结合这两类信息，但两者并不相互替代。

---

三、错误从哪里来？从执行错误过渡到错误传播

现在我们已经知道，Lua 具备获取运行时状态和源码位置的基础。那么接下来要研究的就是：错误是怎么产生的？

1. 区分编译阶段与运行阶段

例如：

local a =

这段代码语法本身就不完整，Lua 在编译阶段就会发现问题，无法正常生成并执行对应的 Chunk。

而我们接下来主要讨论的是运行时错误：源码可以正常编译，但执行到某个位置时发生错误。

2. 运行时错误的两种常见来源

第一种是程序员主动触发：

local function checkPlayer(player)
    if player == nil then
        error("玩家不存在")
    end
end

第二种是Lua 运行时检测到非法操作：

local player = nil
print(player.gold)  -- 对 nil 进行字段索引，触发运行时错误

再例如：

local a = nil
print(a < 10)  -- 无法完成该比较，触发运行时错误

注意，nil == 10 是合法表达式，结果为 false。并不是所有涉及 nil 的比较都会报错。

这里还要联系之前学过的元表：如果某种操作可以由适用的元方法处理，则未必一定报错；只有操作无法按 Lua 语义完成时，才会触发相应错误。

3. 与 C++ 底层执行故障的区别

我们之前还接触过 C++ 空指针解引用、硬件异常以及 Linux 信号。

对于 C++：

int* p = nullptr;
int value = *p;

从 C++ 语言层面，这属于未定义行为 ，不能保证一定产生某个信号。只有在程序确实执行了不合法的机器级内存访问时，CPU 才可能产生类似缺页异常（如 x86 的 #PF），内核再决定是否能够恢复，或向进程发送 SIGSEGV 等信号。

但是，对于 Lua：

local player = nil
print(player.gold)

通常是Lua 虚拟机在执行相关字节码时，按语言语义发现操作不合法，并在 Lua 运行时内部触发错误 ，而不是把 nil 直接当成机器指针交给 CPU 解引用。

我们可以把两种常见的 Lua 运行时错误来源统一归纳为：

程序员主动调用 error() 等函数
                │
                ├────→ Lua 运行时错误
                │              ↓
虚拟机执行操作时检测到错误 ───────→ 错误对象向外传播

4. 错误会沿调用关系向外传播

例如：

local function C()
    error("玩家不存在")
end

local function B()
    C()
end

local function A()
    B()
end

A()

执行到 C() 中的 error() 后，正常执行会中断。由于这段代码没有建立 Lua 层的保护调用边界，因此错误继续向外传播，直到达到宿主程序建立的保护边界，或者其他有效处理位置。

在正常的错误处理过程中，相关函数调用会退出，其调用栈也可能随之展开（Stack Unwinding）。

这里要区分两个概念：

• 错误传播：错误由 Lua 运行时向外寻找处理边界。
• 栈展开：相关函数调用退出，运行时恢复或清理必要状态。

栈展开不意味着函数使用过的所有 Table 都立刻销毁；仍然被引用的对象可以继续存在，闭包捕获的 Upvalue 也不一定消失。Lua 5.4 的 <close> 变量还可能在退出作用域时执行关闭操作。

这就引出了后面整个调试机制的关键：如果调用栈已经展开，我们可能就无法再直接读取原先出错的那些调用帧。

---

四、主动产生错误：error() 与 assert()

1. error()：主动触发运行时错误

调用协议：

error(message [, level])

message 是需要传播的错误对象。名字虽然叫 message，但它不一定必须是字符串。

例如：

error("玩家不存在")

如果错误对象是字符串，Lua 默认会尝试在前面拼接源码位置，例如：

test.lua:3: 玩家不存在

这里的文件名和行号是拼接到字符串中的内容，不是另一个独立的"异常结构体字段"。完整调用链也不会自动包含在这个字符串中。

第二个参数 level 可以指定这条错误消息关联的源码位置：

level	含义
0	不自动添加源码位置前缀
1（默认）	指向调用 error() 的位置
2	指向调用该函数的上一层位置
3 等	继续向外层定位

例如：

local function checkPlayer(player)
    if player == nil then
        error("玩家不存在", 2)
    end
end

local function login()
    checkPlayer(nil)
end

login()

此时 level = 2 可以使错误字符串更关注调用 checkPlayer() 的位置，这在封装参数校验函数时很有用。

但是，level 不会改变错误真正发生的位置，也不会修改调用栈，只是影响字符串错误消息中的位置前缀。

2. 错误对象也可以是 Table

local function test()
    error({
        code = 1001,
        message = "玩家不存在"
    })
end

local ok, err = pcall(test)

print(ok)           -- false
print(err.code)     -- 1001
print(err.message)  -- 玩家不存在

当错误对象是 Table 时，error() 不会自动把文件名和行号加到这个 Table 上，错误处理方得到的仍然是原来的 Table 引用。

那么这个错误对象最终由谁处理呢？

当我们使用 lua test.lua 启动独立解释器时，lua 命令行程序本身就是宿主程序 。Lua 运行时负责触发和传播错误，而命令行宿主程序负责处理没有被脚本捕获的错误，并且通常将错误描述输出到标准错误流 stderr。

而当 Lua 被嵌入到游戏服务端等 C/C++ 程序中时，最终如何记录、上报或处理错误，由宿主程序与业务框架的设计决定。

所以，error() 的职责很清晰：触发错误并提供错误对象，而不是直接负责打印日志。

3. assert()：带条件判断的 error()

调用协议：

assert(v [, message])

我们可以把它理解为一个带条件判断的错误触发函数：

• 如果 v 为 false 或 nil，则触发运行时错误，携带 message 作为错误对象。
• 如果 v 不为 false 或 nil，则不触发错误，并返回传入的全部参数。

例如：

assert(false, "玩家不存在")

会触发错误。它也支持 Table 错误对象：

assert(false, { code = 1001, message = "玩家不存在" })

如果断言成功：

local a, b, c = assert(10, "hello", 20)
print(a, b, c)  -- 10  hello  20

另外，Lua 中的 0、空字符串、空 Table 都属于真值，不会使断言失败。

所以，error() 与 assert() 的区别主要是触发错误的条件 ，而不是错误传播机制不同：一旦 assert() 触发错误，它同样进入 Lua 的运行时错误传播流程。

---

五、错误发生后如何不让它一直向外传播？pcall()

1. 为什么需要保护调用边界？

如果一个函数内部执行 error()，通常会打断这次调用，使错误沿调用关系向外传播。

但游戏服务端中的某一次业务逻辑出错，并不一定意味着外层程序也必须中止执行。例如，我们希望记录这次失败，再由上层业务决定下一步该怎么处理。

所以，Lua 提供了保护调用（Protected Call）。

pcall(f [, arg1, ...])

其中 f 是需要在保护模式下执行的函数值，后面的参数传递给 f。

这里要特别注意：

pcall(test)    -- 正确：让 pcall 调用 test
pcall(test())  -- 不同：先执行 test，再将返回值传给 pcall

第二种写法中，test() 的求值发生在这次 pcall() 调用之前，因此 test() 本身不受这次保护调用保护。

2. pcall() 如何捕获错误？

local function C()
    error("玩家不存在")
end

local function B()
    C()
end

local function A()
    B()
end

local ok, err = pcall(A)
print(ok, err)
print("外层代码继续执行")

这里的核心流程是：
#mermaid-svg-B2PtKQEZcb0uv4U9{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-B2PtKQEZcb0uv4U9 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-B2PtKQEZcb0uv4U9 .error-icon{fill:#552222;}#mermaid-svg-B2PtKQEZcb0uv4U9 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-B2PtKQEZcb0uv4U9 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-B2PtKQEZcb0uv4U9 .marker.cross{stroke:#333333;}#mermaid-svg-B2PtKQEZcb0uv4U9 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-B2PtKQEZcb0uv4U9 p{margin:0;}#mermaid-svg-B2PtKQEZcb0uv4U9 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-B2PtKQEZcb0uv4U9 .cluster-label text{fill:#333;}#mermaid-svg-B2PtKQEZcb0uv4U9 .cluster-label span{color:#333;}#mermaid-svg-B2PtKQEZcb0uv4U9 .cluster-label span p{background-color:transparent;}#mermaid-svg-B2PtKQEZcb0uv4U9 .label text,#mermaid-svg-B2PtKQEZcb0uv4U9 span{fill:#333;color:#333;}#mermaid-svg-B2PtKQEZcb0uv4U9 .node rect,#mermaid-svg-B2PtKQEZcb0uv4U9 .node circle,#mermaid-svg-B2PtKQEZcb0uv4U9 .node ellipse,#mermaid-svg-B2PtKQEZcb0uv4U9 .node polygon,#mermaid-svg-B2PtKQEZcb0uv4U9 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-B2PtKQEZcb0uv4U9 .rough-node .label text,#mermaid-svg-B2PtKQEZcb0uv4U9 .node .label text,#mermaid-svg-B2PtKQEZcb0uv4U9 .image-shape .label,#mermaid-svg-B2PtKQEZcb0uv4U9 .icon-shape .label{text-anchor:middle;}#mermaid-svg-B2PtKQEZcb0uv4U9 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-B2PtKQEZcb0uv4U9 .rough-node .label,#mermaid-svg-B2PtKQEZcb0uv4U9 .node .label,#mermaid-svg-B2PtKQEZcb0uv4U9 .image-shape .label,#mermaid-svg-B2PtKQEZcb0uv4U9 .icon-shape .label{text-align:center;}#mermaid-svg-B2PtKQEZcb0uv4U9 .node.clickable{cursor:pointer;}#mermaid-svg-B2PtKQEZcb0uv4U9 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-B2PtKQEZcb0uv4U9 .arrowheadPath{fill:#333333;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-B2PtKQEZcb0uv4U9 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-B2PtKQEZcb0uv4U9 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-B2PtKQEZcb0uv4U9 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-B2PtKQEZcb0uv4U9 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-B2PtKQEZcb0uv4U9 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-B2PtKQEZcb0uv4U9 .cluster text{fill:#333;}#mermaid-svg-B2PtKQEZcb0uv4U9 .cluster span{color:#333;}#mermaid-svg-B2PtKQEZcb0uv4U9 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-B2PtKQEZcb0uv4U9 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-B2PtKQEZcb0uv4U9 rect.text{fill:none;stroke-width:0;}#mermaid-svg-B2PtKQEZcb0uv4U9 .icon-shape,#mermaid-svg-B2PtKQEZcb0uv4U9 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-B2PtKQEZcb0uv4U9 .icon-shape p,#mermaid-svg-B2PtKQEZcb0uv4U9 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-B2PtKQEZcb0uv4U9 .icon-shape rect,#mermaid-svg-B2PtKQEZcb0uv4U9 .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-B2PtKQEZcb0uv4U9 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-B2PtKQEZcb0uv4U9 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-B2PtKQEZcb0uv4U9 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} pcall(A)：建立保护边界
A 调用 B
B 调用 C
C 触发 error
错误传播；相关调用帧展开
到达 pcall 的保护边界
pcall 返回 false 和错误对象
外层代码继续执行

这里 pcall() 捕获了错误，因此外层程序能够继续执行。但是，它并没有让出错的 C() 从 error() 后面的语句重新开始执行 ；A()、B()、C() 这次尚未完成的调用已经退出。

3. pcall() 的返回值

如果目标函数成功执行：

local function calc(a, b)
    return a + b, a - b
end

local ok, sum, diff = pcall(calc, 10, 20)
print(ok, sum, diff)  -- true  30  -10

也就是：

执行成功 → true, 目标函数的所有返回值

如果目标函数触发错误：

执行失败 → false, 原始错误对象

可以将 pcall() 理解为：它把一次可能失败的调用，变成一次能够向调用者报告成功或失败的普通函数返回。

不过，这也留下了一个问题：等 pcall() 返回时，原先出错函数的调用栈通常已经展开，此时再去查询当前调用栈，已经无法直接还原原来的完整现场。

---

六、想在调用栈展开前保存现场：xpcall()

1. xpcall() 相比 pcall() 多了什么？

xpcall(f, msgh [, arg1, ...])

这里 f 仍然是受保护的目标函数，msgh 则是错误处理函数（Message Handler）。

为什么需要额外的错误处理函数？

因为我们希望在错误导致原始调用栈展开之前，先读取并保存一些现场信息，例如完整的调用链。

2. 错误处理函数的执行时机

local function C()
    error("玩家不存在")
end

local function B()
    C()
end

local function A()
    B()
end

local function handler(err)
    print("捕获到原始错误：", err)
    return "处理后的错误：" .. err
end

local ok, result = xpcall(A, handler)
print(ok, result)

这里发生错误之后，Lua 会在原始调用栈展开之前执行 handler(err)，把原始错误对象作为参数传入。

错误处理函数返回后，受保护的调用结束，xpcall() 返回：

false, handler 的返回值

需要特别区分：handler() 的返回值不是自动继续向外抛出的新错误，而是 xpcall() 作为普通返回值交给调用者的结果。

如果外层代码希望再次传播错误，就需要显式地重新触发，例如：

local ok, result = xpcall(A, handler)
if not ok then
    error(result, 0)
end

此时才会开始新的一次错误传播。

3. xpcall() 与 pcall() 的关键区别

handler A → B → C xpcall 外层调用者 handler A → B → C xpcall 外层调用者 #mermaid-svg-hGd13XenByIA6kyi{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-hGd13XenByIA6kyi .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-hGd13XenByIA6kyi .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-hGd13XenByIA6kyi .error-icon{fill:#552222;}#mermaid-svg-hGd13XenByIA6kyi .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-hGd13XenByIA6kyi .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-hGd13XenByIA6kyi .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-hGd13XenByIA6kyi .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-hGd13XenByIA6kyi .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-hGd13XenByIA6kyi .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-hGd13XenByIA6kyi .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-hGd13XenByIA6kyi .marker{fill:#333333;stroke:#333333;}#mermaid-svg-hGd13XenByIA6kyi .marker.cross{stroke:#333333;}#mermaid-svg-hGd13XenByIA6kyi svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-hGd13XenByIA6kyi p{margin:0;}#mermaid-svg-hGd13XenByIA6kyi .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-hGd13XenByIA6kyi text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-hGd13XenByIA6kyi .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-hGd13XenByIA6kyi .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-hGd13XenByIA6kyi .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-hGd13XenByIA6kyi .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-hGd13XenByIA6kyi #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-hGd13XenByIA6kyi .sequenceNumber{fill:white;}#mermaid-svg-hGd13XenByIA6kyi #sequencenumber{fill:#333;}#mermaid-svg-hGd13XenByIA6kyi #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-hGd13XenByIA6kyi .messageText{fill:#333;stroke:none;}#mermaid-svg-hGd13XenByIA6kyi .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-hGd13XenByIA6kyi .labelText,#mermaid-svg-hGd13XenByIA6kyi .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-hGd13XenByIA6kyi .loopText,#mermaid-svg-hGd13XenByIA6kyi .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-hGd13XenByIA6kyi .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-hGd13XenByIA6kyi .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-hGd13XenByIA6kyi .noteText,#mermaid-svg-hGd13XenByIA6kyi .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-hGd13XenByIA6kyi .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-hGd13XenByIA6kyi .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-hGd13XenByIA6kyi .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-hGd13XenByIA6kyi .actorPopupMenu{position:absolute;}#mermaid-svg-hGd13XenByIA6kyi .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-hGd13XenByIA6kyi .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-hGd13XenByIA6kyi .actor-man circle,#mermaid-svg-hGd13XenByIA6kyi line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-hGd13XenByIA6kyi :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 原调用栈尚未展开 随后展开相关调用帧 xpcall(A, handler) 执行目标函数 触发运行时错误 handler(原始错误对象) 处理结果 / traceback false, 处理结果

对比	pcall()	xpcall()
建立保护边界	是	是
捕获普通运行时错误	是	是
错误失败时返回	原始错误对象	错误处理函数返回的对象
栈展开前执行自定义处理函数	否	是
常见用途	判断调用是否成功	记录错误上下文与调用栈

需要补充一个例外：错误处理函数并不保证在一切故障下都会被调用。Lua 5.4 中，内存分配错误、终结器执行期间的错误等就有特殊处理规则。

至此我们就得到了一个重要结论：xpcall() 自己不生成调用栈，它只是提供了一个"错误现场尚未展开"的处理时机。 真正负责读取调用栈的，是接下来要学习的调试接口。

---

七、debug.traceback()：把当前调用栈组织成字符串

1. traceback() 的职责

我们前面已经知道，Lua 虚拟机会维护函数调用栈。现在通过 xpcall()，我们又得到了在错误现场仍然存在时执行代码的机会。

那么，接下来的问题就变成：我们该调用什么接口，才能真正读取调用栈？

Lua 5.4 提供：

debug.traceback([thread,] [message [, level]])

它的核心作用是：获取指定 Lua 线程当前的调用栈信息，并生成供人阅读的调用链字符串。

我们不一定需要发生错误才能调用它：

local function C()
    print(debug.traceback("当前调用关系"))
end

local function B()
    C()
end

local function A()
    B()
end

A()

由于此时 A()、B()、C() 都尚未返回，因此生成的 traceback 中可以包含这些活跃调用层次。实际输出格式、名称和行号会随源码及运行环境而变化。

2. message：只是前置描述，不一定是错误消息

例如：

debug.traceback("当前调用关系")

传入的字符串会放到调用栈信息的前面。这个字符串可以是普通说明，也可以是先前得到的错误信息；传递 message 本身不会触发错误。

不传或传入 nil 时，同样可以生成调用栈字符串。

但这里有一个特殊规则：

local err = { code = 1001, message = "玩家不存在" }
local result = debug.traceback(err)
print(result == err)  -- true

如果 message 既不是字符串也不是 nil ，debug.traceback() 会直接返回这个对象，而不生成调用栈字符串；对于 Table，返回的仍然是同一个 Table 引用。

因此，在处理 Table 错误对象时，不能想当然地把它直接交给 debug.traceback(err)，并期望得到调用链字符串。

3. level：决定从哪一层开始输出

当我们在函数 C() 中调用 debug.traceback() 时，可以将栈层级理解为：

层级	对应调用位置
0	debug.traceback() 自身
1（当前线程默认）	调用 traceback 的 C()
2	调用 C() 的 B()
3	调用 B() 的 A()

例如：

debug.traceback("调用栈", 1)  -- 从 C() 开始
debug.traceback("调用栈", 2)  -- 跳过 C()，从 B() 开始

需要注意，level 只是控制输出从哪一层开始，不会修改真实调用栈 。而这里的 level 和 error(message, level) 虽然都使用层级编号，但用途并不相同：一个指定 traceback 的输出起点，另一个决定错误字符串的位置前缀。

4. thread：指定要读取哪个协程的调用栈

这里需要连接我们之前学过的 Lua 协程。

Lua 中：

local co = coroutine.create(function()
    coroutine.yield()
end)

print(type(co))  -- thread

虽然类型名叫 thread，但这里就是协程对象，并不是 C++ std::thread 对应的操作系统线程。

Lua 使用有栈协程。每个协程拥有自己的 Lua 调用栈和执行状态，挂起时相关状态仍然保留，恢复后可以继续执行。

另外，脚本文件本身不是执行流：源码文件被编译为可执行 Chunk，而 Chunk 是由某个 Lua 执行流运行的。调用栈属于 Lua 线程（协程），并不是和脚本文件一一对应。

例如：

local function C()
    coroutine.yield("暂停")
end

local function B()
    C()
end

local function A()
    B()
end

local co = coroutine.create(A)
coroutine.resume(co)

print(coroutine.status(co))             -- suspended
print(debug.traceback(co, "协程调用栈"))

虽然当前是在调用 resume() 的执行流中调用 debug.traceback()，但通过传入 co，仍然能够检查处于挂起状态的协程所保留的调用栈。

这里还有一个特殊情况：Lua 5.4 中，如果协程因为未保护的错误而结束，coroutine.resume() 返回 false 和错误对象时，该协程的栈不会像普通 pcall() 返回前那样展开，因此我们仍有机会通过调试接口检查出错协程的调用栈。

5. 与 xpcall() 组合：生成真正的错误现场记录

local function C()
    error("玩家不存在")
end

local function B()
    C()
end

local function A()
    B()
end

local function handler(err)
    return debug.traceback(err)
end

local ok, result = xpcall(A, handler)
print(ok)
print(result)

在这个例子中，xpcall() 负责在栈展开之前执行 handler()，而 debug.traceback() 负责读取当时的调用栈、生成字符串。等 xpcall() 返回时，即使原调用帧已经退出，生成的 traceback 文本依然可以被记录或输出。

如果错误对象可能是 Table，我们可以保留原始对象与调用栈字符串两个部分：

local function handler(err)
    return {
        original_error = err,
        traceback = debug.traceback()
    }
end

这样可以避免 Table 传入 debug.traceback(err) 后直接原样返回的问题。

---

八、debug.getinfo()：从调用链字符串过渡到函数信息

1. 为什么还需要 getinfo()？

debug.traceback() 已经可以生成调用链文本，但如果我们希望进一步查询：

• 函数定义在哪个源文件？
• 函数定义从哪一行到哪一行？
• 当前执行到了哪一行？
• 固定参数数量、Upvalue 数量是多少？

那么直接解析 traceback 字符串并不合适。Lua 提供了返回结构化信息的接口：

debug.getinfo([thread,] f [, what])

debug.getinfo() 查询成功时返回 Table，其中存放所请求的相关字段。

2. 第一种用法：传入函数值，查询函数自身的信息

local function add(a, b)
    return a + b
end

local info = debug.getinfo(add, "Su")
print(info.source)
print(info.linedefined)
print(info.lastlinedefined)
print(info.nparams)

这里传入的是 add，不是 add()，所以并不会调用 add。

对于 Lua 函数，我们之前已经认识过：函数值关联一个闭包（Closure），闭包所关联的函数原型包含编译生成的字节码和相关信息。通过这些信息，getinfo() 可以获取函数定义位置、参数数量等属性。

但是，函数值并不等于某一次具体的函数调用 。同一个函数可能被多次调用，甚至递归调用，因此直接传入函数值时，没有某一次调用的当前执行位置可以查询。此时 currentline 通常为 -1（若请求了该字段）。

3. 第二种用法：传入栈层级，查询某一次正在进行的调用

local function C()
    local info = debug.getinfo(1, "Sl")
    print(info.source, info.currentline)
end

local function B()
    C()
end

local function A()
    B()
end

A()

在这里，debug.getinfo(1, "Sl") 查询的是调用 getinfo() 的 C() 的调用帧 。我们也可以把层级改为 2，查询上一层调用者 B()；改为 3，查询 A()。

层级	对应调用帧
0	debug.getinfo() 自身
1	C()
2	B()
3	A()

因此：

传函数值 ，关注的是"这个函数是什么"；传栈层级，关注的是"这一次具体调用的当前状态是什么"。

4. what：决定返回 Table 中包含哪些信息

what 是一组可以组合的选项字符。例如：

local info = debug.getinfo(1, "Slnu")

选项	主要信息
S	源码标识、函数定义起止行、Lua/C/main 等类型
l	当前执行行号 currentline
n	可推断的函数名称及名称来源
u	nups、nparams、isvararg
t	istailcall
f	函数对象 func
L	可执行源码行集合 activelines

例如：

local info = debug.getinfo(1, "l")
print(info.currentline)

这个结果主要包含 currentline，并不会因为我们只请求了 l，就自动包含全部 S 类信息。

所以，what 不是查询完成后再过滤已经生成的 Table，而是指定调试接口需要获取哪些信息类别 。如果省略 what，默认尽可能获取常规信息，但不包括 L 对应的有效行集合。

还有一个边界：如果传入的数字层级超过当前有效调用栈范围，debug.getinfo() 返回 nil。

---

九、debug.getlocal()：进一步查看调用帧中的局部变量

1. 从"执行到哪里"过渡到"当前变量是什么值"

通过 debug.getinfo()，我们已经能够查询某次函数调用对应的源文件和当前执行位置。

不过，实际分析运行时问题时，我们还希望知道：这个函数执行到这里的时候，参数与局部变量究竟是什么值？

这就需要：

debug.getlocal([thread,] f, local)

这里 f 可以是调用栈层级，也可以是函数值；local 是要查询的局部变量序号。

2. 查询运行时调用帧：返回变量名称和值

例如：

local function test(playerId)
    local gold = 100
    local level = 20

    local name, value = debug.getlocal(1, 1)
    print(name, value)
end

test(1001)

这里 debug.getlocal(1, 1) 的含义是：

• 第一个 1：查询当前调用 getlocal() 的 test() 对应的调用帧。
• 第二个 1：查询该调用帧中的第一个活跃局部变量。

在这个例子中，第一个活跃局部变量通常是形参 playerId，因此得到：

playerId    1001

注意，参数也属于可查询的局部变量，接口还可能包含某些内部临时值。

这里还要再次强调：Lua 并不是直接把变量名和值保存到一个普通 Table 中供我们查询，而是通过栈槽等运行时结构保存相关值，再借助变量活跃范围和调试信息解释这些值。

3. local 索引对应的是当前活跃变量，而不是源码中所有变量

这是理解 getlocal() 最重要的地方。

例如，我们先封装一个查看调用者局部变量的函数：

local function dumpCallerLocals()
    local i = 1

    while true do
        local name, value = debug.getlocal(2, i)
        if name == nil then
            break
        end

        print(name, value)
        i = i + 1
    end
end

这里为什么使用 level = 2？因为：

level 0：debug.getlocal()
level 1：dumpCallerLocals()
level 2：调用 dumpCallerLocals() 的业务函数

然后编写：

local function test(playerId)
    local gold = 100

    do
        local level = 20
        dumpCallerLocals()  -- 此时 level 仍处于有效作用域
    end

    dumpCallerLocals()      -- 此时 level 的作用域已经结束
end

test(1001)

第一次查询时，playerId、gold、内层的 level 等变量处于当前执行位置的有效作用域内，可以被查询。

第二次查询时，已经离开 do ... end，因此内层 level 不再是该位置的活跃局部变量。

所以并不是 getlocal() 不能读取内层作用域的局部变量，而是它只能读取指定调用帧在当前执行位置上仍然活跃的变量。

这还意味着局部变量索引并不是永久绑定到某个源码变量名上的编号。随着执行位置和作用域变化，同一个索引可能对应不同的活跃变量。

4. 直接传入函数值：只能获取形参名称

local function add(a, b)
    local result = a + b
    return result
end

print(debug.getlocal(add, 1))  -- a
print(debug.getlocal(add, 2))  -- b

这里我们传入的只是函数值 add，并没有指定某一次调用帧。

因此，Lua 可以查询函数的形参名称，却无法读取某次调用中的实际参数值，也不能据此查询函数内部普通局部变量 result 的运行时值。

需要注意，直接传入函数值时，返回的是形参名称，而不是"名称和值"两个有效结果。

十、将这些接口放到同一个调试场景中

现在我们已经掌握了错误触发、保护调用以及读取调用栈的基本方法，可以组合出一个简单的错误记录流程。

-- 保留原始错误对象，同时保存 traceback 字符串
local function errorHandler(err)
    return {
        original_error = err,
        traceback = debug.traceback("业务执行失败")
    }
end

local function checkPlayer(player)
    assert(player ~= nil, {
        code = 1001,
        message = "玩家对象不存在"
    })
end

local function loadPlayer(player)
    checkPlayer(player)
end

local function handleLogin(player)
    loadPlayer(player)
end

local ok, result = xpcall(handleLogin, errorHandler, nil)

if not ok then
    local err = result.original_error
    print("错误码：", err.code)
    print("错误描述：", err.message)
    print(result.traceback)
end

这个例子体现了一条相对完整的链路：

业务入口 handleLogin()
    ↓
调用 loadPlayer() → checkPlayer()
    ↓
assert() 检查失败，触发 Lua 错误
    ↓
xpcall() 在调用栈展开前执行 errorHandler()
    ↓
保存原始 Table 错误对象 + traceback 字符串
    ↓
xpcall() 返回 false 和处理后的结果
    ↓
由外层业务决定如何记录与处理

这里有两个值得特别注意的地方。

首先，errorHandler() 并没有把 Table 错误对象直接传给 debug.traceback(err)，而是单独调用 debug.traceback() 生成调用链，这样才能保证原始错误对象和调用栈都得到保留。

其次，上面只是一个便于学习的示例。对于实际游戏服务端，我们还需要考虑错误对象类型、日志格式、记录开销以及宿主框架已经提供的错误处理机制。不应该在没有分析项目既有调用链之前，就假设每个业务函数都需要自己包装一层 xpcall()。

---

十一、几个容易混淆的地方

容易混淆的认识	更准确的理解
Lua 编译出"执行字节码"和"调试字节码"两部分	字节码指令用于执行，调试辅助信息用于源码映射，它们不是两套字节码
调用栈是为了调试才创建的	虚拟机正常执行函数就需要维护调用帧；调试接口只是利用它
调用栈能够还原所有历史调用	主要反映查询时仍存在的调用关系，不是完整历史记录
error() 就是往终端打印错误	它负责触发和传播错误；如何输出由捕获方或宿主决定
assert() 只返回一个布尔值	断言成功时返回全部参数；失败时触发错误
pcall() 捕获后，出错函数继续执行	出错调用已经退出；只有外层代码从 pcall() 返回处继续
xpcall() 会把 handler 返回值继续抛出	默认不会；它作为 xpcall() 的普通返回值交给调用者
debug.traceback() 自动捕获异常	它只负责读取并格式化调用栈，不负责捕获错误
debug.traceback(table) 会附带调用栈	Lua 5.4 中会直接原样返回 Table，不生成调用栈字符串
thread 就是操作系统线程	debug.traceback() 的 thread 参数是 Lua 协程对象（类型名为 thread）
getinfo(func) 与 getinfo(level) 一样	前者关注函数属性，后者关注一次实际函数调用
getlocal() 能读取源码里全部局部变量	只能读取指定调用帧当前活跃的变量，或在传入函数值时读取形参名称
getlocal() 的变量序号永久不变	活跃集合会随执行位置和词法作用域变化，序号也可能变化

---

十二、总结：从 Lua 执行机制走到调试机制

现在我们可以回到全文最开始的问题：为什么 Lua 能够定位运行时错误发生的位置，还能够还原错误发生时的函数调用关系？

首先，Lua 脚本会被加载、编译，生成虚拟机需要执行的字节码及相关数据。默认情况下，编译结果还保留源码行号、局部变量名称等调试辅助信息。

随后，Lua 虚拟机执行字节码，在函数调用过程中维护调用帧、调用栈及相关运行时状态。这些状态首先服务于程序本身的正常执行，而不是为了调试才出现。

当程序执行发生错误时，错误可能来自程序员主动调用 error()、assert()，也可能来自 Lua 运行时发现非法操作。错误会打断正常执行流程，并沿调用关系向外寻找保护调用边界。

pcall() 可以捕获错误，并将其转化为状态值与错误对象；xpcall() 则进一步提供了原始调用栈展开前的错误处理时机。这使我们能够及时调用 debug.traceback()，把错误现场的调用链组织成字符串。

在此基础上，debug.getinfo() 可以帮助我们进一步查看函数本身或者某次具体调用的信息，而 debug.getlocal() 则能读取指定调用帧当前活跃的局部变量。

所以，到这里，我们对 Lua 调试机制就能够形成一个完整的心智模型：

Lua 调试机制并不是独立于执行系统之外的一套流程，而是通过 Lua 运行时提供的调试接口，结合编译阶段保留的源码信息以及执行阶段维护的调用栈与运行时状态，帮助我们定位错误、分析调用关系和检查变量状态。

理解了这一点，再学习后面的 debug.getupvalue()、debug.sethook()，就不再是孤立地记忆 API，而是在这套模型上继续向闭包变量和执行事件追踪深入。

---