CHUAN2 DEV ENGINE
996 正版授权研发中心 · 360 授权合作教学中心 · 抖音传奇直播合作授权 · 快手推广运营商授权
OFFICIAL LICENSED ACADEMY 查验官方授权证书 →
// 威海旷世互娱教学基地 · 技术文章
Lua实战

【Lua实战】xpcall 的错误对象:带上下文的错误传递

2026-09-21 16:45 作者:996 技术组 Lua实战

实战应用:用在哪里

触发器函数在运行时炸掉,默认的处理是错误上抛进引擎日志,上下文全丢——哪个玩家、哪个地图、什么参数触发的,全靠猜。xpcall 的错误对象机制让错误带着现场上下文进处理函数,排障的效率从翻日志猜变成一眼定位。

错误对象的构造

lua

---触发器的安全包裹:错误带上下文
local function wrapTrigger(fn, name)
    return function(actor, ...)
        local ok, err = xpcall(fn, function(e)
            return {
                msg = tostring(e),
                trigger = name,
                who = type(actor) == "userdata"
                    and (actor:GetName() or "?") or "?",
                map = type(actor) == "userdata"
                    and tostring(actor.mapId) or "?",
                trace = debug.traceback(e, 2),
            }
        end, actor, ...)
        if not ok then
            ErrReport.push(err)
            sendmsg(actor, 1, "操作异常,已记录反馈")
        end
        return ok
    end
end

attack = wrapTrigger(attack, "attack")
beginmagic = wrapTrigger(beginmagic, "beginmagic")

xpcall 的第二参数是错误处理函数,在错误发生的调用栈上执行,debug.traceback 能拿到完整的堆栈。包裹层把错误整理成结构化对象:错误消息、触发器名、玩家名、地图与堆栈五要素,push 进错误报告的聚合通道。玩家侧的反馈一句“操作异常”足够,技术侧的上下文全在错误对象里,两边的诉求各得其所。

错误的分流

lua

---错误报告:按触发器聚合计数
ErrReport.buckets = {}
function ErrReport.push(err)
    local key = err.trigger .. "|" ..
        (err.msg:match("^[^:]+") or "?")
    local b = ErrReport.buckets[key]
    if not b then
        b = { count = 0, first = err }
        ErrReport.buckets[key] = b
    end
    b.count = b.count + 1
    if b.count == 50 then
        Ops.alert("触发器高频报错: " .. key, err.first)
    end
end

错误对象按触发器加错误类型聚合,50 次的阈值触发告警并附首个完整现场——聚合让高频错误与一次性错误分流,值班的时间花在值得的地方。错误对象的可扩展字段随场景增减:交易触发器的包裹层补双方 ID,攻城触发器补行会名,字段的语义在包裹层各自负责。错误对象不能替代修复,它的价值是让每一次错误都带着足够的现场,修复的定位时间从小时级压到分钟级。

验证与监控

包裹层的自测:构造各类错误(nil 访问、类型错、自定义 error)验证对象字段的完整性;错误聚合的报告与线上日志的抽查比对,漏收率要求为零。

踩坑记录

错误处理函数曾经写复杂逻辑自身再抛错,二次错误的堆栈覆盖原始现场,处理函数保持纯收集不干活。traceback 的层级参数曾经没传,堆栈从包裹层开始,真正的出错帧被裁掉,层级传 2。sendmsg 的安抚文案曾经在 actor 无效时再炸一次,actor 的类型守卫先于一切。

上线要点

全部触发器统一走包裹层注册,裸函数的触发器注册进评审黑名单。错误对象的结构版本化,字段的增减向后兼容。高频错误的处置手册按触发器编写,告警附手册链接。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付,内容以官方知识库与真实项目为出处,按版本持续修订。

作者履历与出处

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付,内容以官方知识库与真实项目为出处,按版本持续修订。

← 返回文章地图返回研学路径

最新技术文章 · 实战干货

LATEST ARTICLES

全站技术干货持续更新:996 引擎 / Lua 实战帖,语法、参数与示例一篇讲透。进入文章地图 · 查看全部 →

玩法策划沙巴克税收

【玩法策划】沙城税务官:税收分配与廉政度的玩法设计

实战应用:用在哪里 沙巴克占领行会坐收税收却只进不出,非占领行会的玩家心里不平衡。税务官玩法把税收做成明账:占领行会对摆摊与…

2026-09-23 01:24 996 技术组
玩法策划比武社交

【玩法策划】比武招亲:比武切磋与社交绑定的玩法设计

实战应用:用在哪里 高端玩家婚姻系统只有仪式没有过程,社交绑定缺一个高光事件。比武招亲做成擂台玩法:擂主设擂摆彩头,攻擂者报…

2026-09-23 01:24 996 技术组
案例复盘限时礼包日期

【案例复盘】限时礼包少发一天的事故复盘

实战应用:用在哪里 开服七日限时礼包发到第六天断了粮,9 月 1 日当天领奖按钮灰的,投诉当天破千。事故根因是一条数字日期循…

2026-09-23 01:24 996 技术组
网络通信心跳假在线

【网络通信】心跳探测:半开连接的主动识别

实战应用:用在哪里 玩家拔线不退游戏,连接半开着,人不在指令也没有,在线数虚高,容量预案被假数据带着跑。心跳探测给每个在线玩…

2026-09-23 01:24 996 技术组
运维发布发布日历

【运维发布】发布日历:全月变更的集中排期

实战应用:用在哪里 周三发了合成系统补丁,周四又改强化概率,两条变更叠加后玩家分不清是哪个改出来的。发布日历把全月变更集中排…

2026-09-23 01:24 996 技术组
Lua实战滑动窗口计数

【Lua实战】时间窗口计数:滑动窗口的环形数组实现

实战应用:用在哪里 容量预案需要知道滚动一小时的副本进入峰值,而不是全天累计。滑动窗口用 60 个槽位每槽记一分钟的进入数,…

2026-09-23 01:24 996 技术组