【高端操作】Lua 热更新方案：函数替换与状态保留

热更的目标与边界

热更新的理想效果：不停服、不踢人，把修好的逻辑换进正在运行的 M2 里。Lua 是动态语言，函数只是存在 table 里的值，所以"换函数"天然可行；真正难的是边界——数据不能丢、正在执行的旧调用不能崩、换完不需要每个玩家重登。设计热更方案前先划清：能换的是函数逻辑，不能换的是已被对象持有的数据结构和已序列化的存档。

最小可用方案：按路径替换函数

核心思路是把所有逻辑函数都挂在统一的命名空间表上（模块化是前提），热更时加载新文件得到新表，然后按原路径把函数逐个拷进旧表：

-- 热更入口（示意）
local old = MyModule                 -- 正在运行的旧模块表
local new = dofile("patch/MyModule.lua")
for k, v in pairs(new) do
    old[k] = v                       -- 按路径覆盖函数
end

这样所有通过 MyModule.func(...) 访问的调用点立刻生效。要注意引用陷阱：如果某处提前写了 local f = MyModule.func，它手里还攥着旧函数。规范是全项目禁止"先存函数再调用"，一律走表访问。

保留状态：upvalue 迁移

新函数的 upvalue 是全新的，旧函数里积累的计数、缓存会丢。两种处理：其一，升级时把旧函数的 upvalue 用 debug.getupvalue/setupvalue 枚举出来，名字对得上的搬进新函数；其二，也是更推荐的架构——状态进表、函数无状态，把所有可变状态集中在 MyModule.state 里，函数只是纯逻辑，替换函数自然不碰状态。

防坑清单

第一，协程与回调中正在执行的旧函数不受影响，它们还会把旧逻辑跑完；涉及配对的开启/关闭逻辑（比如活动开关）热更后要人工核对一遍现场。第二，元表方法替换后，已创建对象的元表指向旧表，如果改动的是元表里的方法，要么直接改旧表内容（原地覆盖正是上面的做法），要么遍历刷新所有对象的 setmetatable。第三，热更文件本身也要走版本号，patch/日期_序号.lua，并在日志里记录每次替换了哪些函数——没有记录的热更等于埋雷。

先把模块化和"状态逻辑分离"做好，热更方案才有落地的地基；反过来，一个设计良好的热更入口，也会倒逼团队写出更干净的模块代码。

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

require(path)

加载文件，函数替换的核心是让新 chunk 覆盖旧注册项

ssrNetMsgCfg = require("Envir/QuestDiary/net/NetMsgCfg.lua")

qfloadbegin(sysobj)

QFunction-0重载前触发，重载前先把需要保留的状态导出

qfloadend(sysobj)

QFunction-0重载后触发，重载后把状态回填，这一步漏了就是典型的状态丢失

callfunbynpc(actor, npcidx, delaytime, func, sParam)

调用其他NPC的lua函数（注意：如果开启多线程，会导致执行失败），替换后仍要保证既有调用点能取到新函数

maintongfile(serverID, model, path)

增加创建文件，热更内容的落盘

updatemaintongfile(serverID,filePath,path)

同步文件 将本地文件路径同步到服务器路径，多区同步时用引擎的同步口，别自己复制

【框架设计】宠物进阶：进化材料链与形态切换

【框架设计】坐骑系统：碎片合成与品质保底

【网络通信】动作与表情：社交广播的轻量协议

【性能调优】延迟结算：非紧急任务的队列消化

【安全加密】数据脱敏：日志与取证导出的隐私处理

【界面UI】BUFF 图标栏：增益排列与剩余时间