【工具链】debug.sethook 采样剖析器：60 行代码定位 Lua 热点函数

实战应用：用在哪里

M2 高峰卡顿，怀疑某段 Lua 逻辑过重但说不清是哪一行。外部 IDE 式剖析器接不进引擎环境，采样式剖析器是唯一选择：用 debug.sethook 按指令数触发采样，统计命中函数的频次分布，跑 10 分钟就能拿到热点排行榜。适用于触发器优化、活动脚本压测、掉帧排查。

采样器实现

local samples, running = {}, true

local function hook()
    if not running then return end
    local info = debug.getinfo(2, "Sln")
    if info and info.source then
        local key = info.source .. ":" .. tostring(info.currentline) .. ":" .. tostring(info.name)
        samples[key] = (samples[key] or 0) + 1
    end
end

debug.sethook(hook, "", 100000)   -- 每 10 万条指令采样一次

采样 10 分钟后 debug.sethook() 关闭，把 samples 表按次数倒序输出到文本文件。每 10 万条指令采一次的开销约 3~5%，业务可接受；探针密度调到 1000 条则开销暴涨 10 倍，只适合短时精测。

解读与优化闭环

热点排行榜的读法：同一函数命中次数占比超过 15% 就是优化目标。配合行号信息定位到具体行，常见三类改法——循环内全局变量换局部（省 GETTABUP 指令）、循环内拼接换 table.concat、高频表查询提循环外缓存。每改一处复测一轮，用数字确认收益。

两个使用注意

采样探针在协程间不自动跟随，协程内跑的逻辑需要单独 sethook；剖析期间避免同时开其他 debug 钩子（互相覆盖）。这套采样器与 PRINTUSETIME（引擎微秒打点）互补：打点回答"这段多久"，采样回答"这段里面哪一行最贵"。两者结合使用，某 996 服务端把登录触发的耗时从 44ms 压到 9ms，热点前三名全部来自一次字符串拼接循环。

采样数据要区分触发场景：登录触发与战斗触发的热点分布差异很大，分开各采一份。输出文件加时间戳命名，每次压测存档一份，跨版本对比能直接看到新功能把哪些函数顶进了排行榜。剖析结束后 debug.sethook() 必须成对关闭，常驻钩子会让 M2 整体性能下降一截。

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