9.4 热更新实战：收官

9.4 热更新实战：收官

本节摘要：热更新是不停机换逻辑——寄宿的终极回报。完整方案四步：触发与校验（新代码进来前先验合法）、模块重载（清 require 缓存重新加载）、函数替换（登记表重绑到新函数）、状态迁移（旧数据嫁接新代码），失败回滚兜底。本节在纯 Lua 层实现一套可用的热更管理器，讲透 upvalue 迁移与协程处理的深水区，对比游戏与网关两种现场形态，最后回望全册主轴收束。

不停机的手术

先把"热更新到底在换什么"想清楚。宿主进程活着，C 侧的引擎、连接、队列都不能动；要换的是 Lua 侧的行为——一段技能公式、一个限流策略、一页 UI 逻辑。第 6.1 节已经埋下机制：模块即表、require 有缓存、缓存可摘。于是热更新的朴素形态就是"摘缓存、重新 require"：

package.loaded["game.skill"] = nil
local new = require("game.skill")     -- 新代码的表
​

但这一摘一装之间藏着三个问题，它们构成热更新的全部难点：

其一，旧表的引用还在别人手里。上周加载时，战斗系统把 skill.cast 存进了自己的局部变量——现在新表加载了，那个局部还指着旧函数。摘缓存只换了"下次 require 的结果"，没换已经分发出去的引用。

其二，状态住在哪里。模块级的计数器、回调里的 upvalue、正在跑的协程局部变量——它们属于旧代码的世界。新代码期待的数据形状若与旧的不同（字段改名、结构重组），嫁接就要搬家。

其三，正在执行的旧函数怎么办。一个协程正睡在旧代码的 yield 点上，醒来后继续跑的是旧指令流（字节码已加载进协程栈，换不掉）——新逻辑只能等它退出后再进。

一套可用的热更管理器

纯 Lua 层的四步实现（可直接跑的骨架）：

-- hot.lua：热更管理器
local Hot = { slots = {} }          -- slots[模块名] = { new = 新表, old = 旧表 }

-- 第一步的校验：语法与接口形状
local function validate(name)
    -- load 试编译由 require 自身完成（失败抛错），这里做接口形状检查
    local ok, mod = pcall(require, name)
    return ok, mod
end

function Hot.reload(name)
    local old = package.loaded[name]
    if old then Hot.slots[name] = { old = old } end

    package.loaded[name] = nil
    local ok, new = validate(name)               -- 试加载即校验
    if not ok then
        package.loaded[name] = old               -- 回滚缓存
        return false, new                        -- new 是错误信息
    end
    Hot.slots[name].new = new

    -- 第三步：登记表重绑（谁登记过这个模块的回调，就指到新函数）
    for _, reg in pairs(Hot.callbacks or {}) do
        if reg.module == name then
            reg.fn = new[reg.handler] or reg.fn
        end
    end
    return true, new
end

-- 模块侧的自检与迁移钩子约定：新模块可提供 migrate(old_state) -> new_state
function Hot.migrate(name, state)
    local slot = Hot.slots[name]
    if slot and slot.new and type(slot.new.migrate) == "function" then
        return slot.new.migrate(state, slot.old)
    end
    return state                                   -- 无钩子：原样透传
end

return Hot
​

配合使用方的纪律（这些约定比代码更重要）：

-- 战斗系统：登记回调走模块，不存裸函数引用
local Hot = require("hot")
Hot.callbacks = Hot.callbacks or {}
Hot.callbacks[#Hot.callbacks + 1] =
    { module = "game.skill", handler = "on_hit", fn = nil }

-- 状态全部收进显式的 state 表（不放 upvalue、不放模块顶层可变字段）
local skill_state = { cooldowns = {}, version = 3 }

-- 热更执行
local ok, err = Hot.reload("game.skill")
if ok then
    skill_state = Hot.migrate("game.skill", skill_state) or skill_state
    print("hot reloaded, state version", skill_state.version)
else
    print("reload rejected:", err)
end
​

三条纪律展开。回调经登记表分发——这是解决"旧引用还活着"的正解：所有人从登记表取函数（3.2 节的分发模式），热更只需重绑登记表。状态收进显式表——upvalue 与模块顶层字段都是热更的盲区（换函数即换 upvalue），显式 state 表让迁移有明确的交接物。新模块提供 migrate 钩子——字段改名、结构重组的搬家逻辑由新代码自己写（它最清楚新形状），管理器只负责调用。

深水区：upvalue 与协程

upvalue 迁移。旧函数的计数器住在 upvalue 里，新函数的 upvalue 是全新的。默认策略：不迁——计数器类状态重置可接受（或本就该进显式 state 表）。确需延续时，debug 库提供手术刀：debug.getupvalue 读旧值、debug.upvaluejoin 把新函数的 upvalue 接到旧盒子上。这属于精细手术，两个函数名对了还要对位置（第几个 upvalue），能用显式状态表解决的，永远别用 debug 刀。

协程处理。睡在 yield 点的协程醒来跑的是旧指令流，换不掉。工程策略三选一：优雅退出（给旧协程发终止信号，让它跑完当前事务自然死亡——最常用）；让它跑完（短命协程等几秒自然清空——限流、请求类的常态）；硬杀（close 协程，5.4 起支持，但资源清理不可靠，最后手段）。核心心法一句话：新逻辑等新请求，不在旧执行流里换脑。

一次完整的热更推演

把四步走一遍具体的例子。场景：线上游戏的 game.skill 模块要修一个倍率 bug 并加一个新字段。当前线上状态：登记表里 tick 回调指向旧模块的 on_frame、若干实体持有旧模块造出的冷却表（{ [skill_id] = expire_at } 形状）。

第一步，校验。新文件到 staging：local f, err = load(new_src, "game.skill") 试编译过；接口形状检查确认 cast、on_frame、migrate 三个函数都在、版本号从 3 升到 4。缺 migrate 直接拒收——这次要动数据形状。

第二步，重载。备份 local old = package.loaded["game.skill"]；摘缓存、require 新文件；新模块顶部的"单次初始化区"重新跑了一遍（重建了它的常量表）。

第三步，替换。遍历登记表，把 module == "game.skill" 的条目 fn 指到 new.on_frame。下一帧驱动循环（9.2 节注册表那套）自动调新函数——正在执行中的旧 on_frame 不受影响，它跑完这一帧自然退出。

第四步，迁移。旧冷却表的形状是 [skill_id] = expire_at（秒级时间戳），新代码想用 { expire = t, charges = n }。新模块的 migrate 钩子做转换：

-- 新模块内部
function M.migrate(old_state, old_mod)
    local migrated = { version = 4, cooldowns = {} }
    for sid, expire_at in pairs(old_state.cooldowns or {}) do
        migrated.cooldowns[sid] = { expire = expire_at, charges = 1 }
    end
    return migrated
end
​

验证与提交。迁移后抽查几个实体的冷却数据、灰度组观察错误率半小时、指标正常即全量。若中途任何一步失败：恢复 package.loaded 指向 old、登记表指回旧函数、staging 文件标记作废——线上回到热更前状态，等于什么都没发生。

整场手术的关键认知：每一步都是可逆的，因为状态始终有明确的交接物（备份的旧表、显式的 state、登记表的重绑）。热更的可靠性不是靠小心翼翼，是靠结构上"随时可退"。

热更的验收清单

方案落地前逐条自问：

• 新代码在进生产前有没有经过 load 试编译与接口形状检查（拒在门外最便宜）？
• 旧模块有没有备份，失败路径有没有演练过（真回滚过一次才算有）？
• 状态是否有显式的交接物与版本号（migrate 按 version 逐级升）？
• 灰度观察的指标与时长是否事先写明（错误率、延迟、业务指标）？
• 热更窗口内新旧代码并存的兼容性是否确认（旧协程读新字段、新代码读旧字段都要活着）？
• 有没有一键禁用热更通道的开关（出问题时先冻结再排查）？

六问都是流程问题而非技术问题——热更的失败案例里，技术原因占三成，流程缺失占七成。这份清单值得贴在发布手册的第一页。

两种现场形态

游戏现场的热更是运营节奏：晚间低峰执行、先灰度一组服务器、观察一小时、全量铺开。热更单位常是"技能包""活动逻辑"这类高内聚模块；状态迁移有策划参与（数值表版本化，migrate 钩子按表版本逐级升级——v3 到 v5 的老号要跑两跳迁移链）。8.1 节的雏形加上本节的四步壳，就是一套能上岗的游戏热更。

网关现场（OpenResty 生态）的热更更谨慎：worker 是多进程的，热更要滚动重启 worker（master 不动，逐个替换进程，连接无损）配合模块预加载验证——"进程级热更"比"函数级热更"粗，但网关脚本短命（每请求一套上下文），粗粒度反而干净。纯 Lua 层的热更更多用于常驻对象（连接池配置、路由表）。粒度选择的原则：状态越短命，热更越容易——请求级状态天然免迁移，全局状态才需要手术。

收官：回望寄宿之道

全册九章走完，把主轴最后串一遍。Lua 是为嵌入而生的语言：八种值让数据能塞进定长槽位（第 1 章），函数与闭包让行为能当数据流转（第 2 章），表是宿主与脚本唯一的复合公约（第 3 章），模式匹配让文本接口开箱即用（第 4 章），元表把行为的定义权外挂给宿主（第 5 章），模块与沙箱画清行李与产权的边界（第 6 章），协程让脚本自愿让出时间片（第 7 章）。四大现场验收了这套设计（第 8 章），C API 的栈礼数与工程习惯把它落到实现（第 9 章前三节）。

而热更新是这条线的终点站：宿主提供长寿命的能力与状态，脚本提供随时可换的行为——这句话就是"寄宿之道"的全部。三十年前巴西实验室里那门为配置界面造的小语言，今天仍在游戏的热修里、网关的策略里、数据库的原子窗里、路由器的页面上值班。学会 Lua 的语法用了你几周，看懂它为什么这样设计用了这本册子——往后你嵌任何脚本引擎、设计任何插件系统时，这张账单都会再派上用场。

💡 最后一句话送给要去实装的读者：热更新的可靠性与平时的纪律成正比——回调走登记、状态进显式表、模块无副作用、错误有壳。这四条在第 2、3、6 章都出现过，它们本来就该那么写；热更新只是让"本来就该"变成了"必须"。

本节要点回顾

• 热更三难：旧引用还在别人手里（登记表重绑解）、状态形状要搬家（migrate 钩子解）、旧执行流换不掉（新请求走新代码解）；
• 四步一兜底：校验拒收、备份重载、引用替换、状态迁移，失败回滚加灰度铺开；
• 纪律重于代码：回调经登记表、状态进显式表、migrate 由新模块自带、模块无副作用；
• 深水区：upvalue 默认不迁（显式表优先，debug 刀最后），协程优雅退出（新逻辑等新请求，不原地换脑）；
• 粒度原则：状态越短命热更越容易——请求级免迁移，全局状态才动手术；网关用进程滚动，游戏走灰度模块；
• 全册主轴：宿主出长寿命能力，脚本出可替换行为——不停机换逻辑，是寄宿的终极回报。