Miku-LuaProfiler 实战指南：轻松定位 Lua 性能瓶颈的完整攻略

【免费下载链接】Miku-LuaProfiler项目地址: https://gitcode.com/gh_mirrors/mi/Miku-LuaProfiler

Miku-LuaProfiler 是一款面向 Unity 的 Lua 性能分析工具，主打函数级深度采样、Lua 与 Mono 内存统计和内存泄漏定位，支持 Windows、Android 与 MAC。这篇文章用一条任务线带你把它跑起来，并讲清每一步背后的原理，读完即可动手。

从一次线上卡顿说起

游戏上线后玩家反馈越来越卡，Lua 侧 GC 频繁触发，内存曲线一路爬升。你想知道到底是哪个函数在分配内存、哪段逻辑拖慢了帧率，却只能在堆栈里大海捞针。这种"知道有问题、找不到元凶"的时刻，正是性能分析工具该出场的地方。

它到底是什么

简单说，Miku-LuaProfiler 通过在 Lua 虚拟机层做 hook 注入，为每个函数自动加上采样点，从而拿到函数级的调用次数、耗时和 GC 数据。它不挑 Lua 框架，xlua、tolua、slua 都能接，核心价值就三个词：深度采样、内存统计、泄漏定位。

五分钟快速上手

先拿到代码：

git clone https://gitcode.com/gh_mirrors/mi/Miku-LuaProfiler # 克隆完成后，把 LuaProfiler 目录整体拷贝到项目的 Assets 下

Unity 2019 及以上也可以用 PackageManager 直接添加 git 路径，但国内网络环境下，clone 后手动拷贝通常更稳。拷贝完成后，编辑器菜单栏出现 LuaProfiler 入口，安装即成功。

打开 LuaProfiler 窗口，确认处于local mode，直接运行游戏就能看到实时数据：顶部是 Fps、Lua/Mono 内存的趋势图，下方表格列出了每个函数的内存与耗时。

编辑器的 local 模式默认关掉了深度采样开关，是最快的验证路径。到这里你已经能看到第一个结果了。

深入配置：真机与多环境适配

编辑器里看到数据只是热身，真正要排查线上问题必须上真机。Android 端的接入分三步：打包时加上宏USE_LUA_PROFILER；在应用的持久化目录下创建标记文件；然后用 remote mode 连接。

adb shell cd /sdcard/Android/data/{package_name}/files touch need_hook_miku_lua # 创建标记，分析完会自动删除，下次需重新创建

在 Profiler 窗口切到remote mode，填手机 IP 和端口 2333 即可。如果公司网络不允许直连，用 USB 线做端口转发，然后在 IP 栏填127.0.0.1：

adb forward tcp:2333 tcp:2333

MAC 平台与 Windows 同理，插件以 bundle 或 DLL 形式随包携带，接入流程与 Android 一致，只是少了 adb 这一步。值得注意的一个坑：工具通过 hookdlopen来定位 Lua 的 native 库，而系统库的 hook 可能引发闪退。更稳妥的做法是显式指定库，在CSharp-Assembly.dll所在程序集放一个自定义类：

public class CustomLua : ILuaCustomSetting { public IntPtr GetPtr() { // 只需把 libxlua.so 换成你项目实际的库名 return miku_dlopen("libxlua.so", 2); } }

另外，工具支持埋自定义采样点，方便你针对特定逻辑块做精细统计：

local LuaProfiler = MikuLuaProfiler.LuaProfiler LuaProfiler.BeginSampleCustom("profiler name") -- your code LuaProfiler.EndSampleCustom()

报告结果这样解读

表格里列很多，抓住几个关键列就够了：totalLuaMemory是该函数累计产生的 Lua GC，self是函数自身产生的部分；totalTime是总耗时，averageTime是单次平均耗时；LuaGC与MonoGC反映当帧的分配压力。

数据一多就需要排序。在搜索框输入[lua]过滤出 Lua 函数，点右上角的merge合并同名函数，再点击各数据列标签即可按内存或耗时排序。

想定位"内存暴涨"的具体位置，用 Record 模式录制一段游戏过程，用键盘左右键在曲线上框选内存明显上升的区间，工具会采样出该区间内的函数明细，逐个对照即可锁定元凶。

排查内存泄漏则要用到快照对比：打开 UI 前MarkStaticRecord存一份快照，打开后再MarkLuaRecord，最后在释放 UI 的地方点DiffRecord，两边都持有的对象基本就是泄漏源，还能顺着引用链一路查下去。

高频问题避坑指南

• 真机只有 resume 或协程数据：多半是代码被 luac 加密了，工具需要明码字符串才能注入采样点，请直接使用明码。
• 接入后偶发闪退：dlopen hook 碰到系统库所致，按上文自定义CustomLua指定 Lua 库即可绕开。
• totalLuaMemory 出现负数：底层按虚拟机总量差值统计，函数执行中途触发 GC 就会得到负数，关闭自动 GC 后再统计。
• 运行后调用 luaGC 无效：这是正常现象，工具接管了 GC 接口，内存增长到上次 GC 的 1.2 倍左右会自动触发。
• 打开 Deep Lua 后空异常变多：工具插桩会打乱debug.getupvalue的取用顺序，按变量名封装getupvalue_byname即可规避。

下一步

先把 local mode 跑通拿到第一份报告，再按"真机接入 → Record 采样 → 快照对比"的路径推进。想了解每个字段的精确统计口径，可直接翻阅仓库根目录的 README；想深入原理，建议从LuaProfiler/Runtime/Core/Driver/LuaProfiler.cs看起，hook 与插桩逻辑都在LuaProfiler~的源码目录里。跑通一次，你就能真正掌握这套排查链路。

【免费下载链接】Miku-LuaProfiler项目地址: https://gitcode.com/gh_mirrors/mi/Miku-LuaProfiler