【框架设计】模块化加载：package.searchers 定制与依赖治理

完整课程入口：996 全套课程体系 ｜ Lua 学习路径 ｜ 幂尔框架 mirs.cn

require 的黑箱

几乎所有 Lua 项目都在用 require 加载模块，但少有人打开过黑箱：require 拿到模块名后，按 package.searchers 里的查找器列表依次尝试，默认四个——预加载表、Lua 文件查找器、C 库查找器、以及 5.4 里的 all-in-one 查找器。第一个返回"加载器函数"的查找器胜出，require 调用它得到模块值，并按 package.loaded 缓存。

理解了这个机制，三件工程利器就顺手了：路径注入、加载拦截、模块替换。

利器一：自定义搜索路径与热更沙盒

引擎环境里脚本目录五花八门（脚本根目录、活动目录、补丁目录），用 package.path 追加自定义模板即可统一：package.path = package.path .. "./patch/?.lua;./patch/?/init.lua"。补丁目录放前面，同名模块优先加载补丁版——这是"整文件级热更"的最简实现：改 patch 下的文件、清除 package.loaded 对应项、require 回来就是新逻辑。

-- 强制重新加载某模块（热更常用）
package.loaded["business.activity"] = nil
local fresh = require("business.activity")

利器二：加载拦截器

往 package.searchers 头部插一个自定义查找器，可以做三件事：统计每个模块的加载耗时（性能排查）；按环境决定返回真模块还是桩模块（客户端在服务器环境加载 UI 模块时返回空壳）；实现模块别名（老模块名映射到新路径，平滑重构）。

table.insert(package.searchers, 2, function(name)
    local t0 = os.clock()
    -- 返回一个包装加载器，加载完打印耗时
    return function(...)
        local ok, mod = xpcall(requireReal, debug.traceback, name)
        log(("load %s: %.1fms"):format(name, (os.clock() - t0) * 1000))
        return mod
    end
end)

利器三：依赖治理

模块互相 require 形成的依赖图要有人管。两条纪律：单向依赖——业务层允许依赖基础层，反之禁止，用静态扫描脚本（遍历 require 语句建图查环）在构建期拦截循环依赖；禁止 require 副作用——模块返回纯 table，凡"被加载即联网/写文件/改全局"的模块都是热更与测试的定时炸弹。

把这三件利器用起来，加载耗时看得见、补丁走专用目录、依赖图机器可查——require 从黑箱变成你手里的模块总线。

加载入口

require(path)

加载文件，package.searchers 定制后仍从这里触发，先摸清既有调用点

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

函数级调用

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

调用其他NPC的lua函数（注意：如果开启多线程，会导致执行失败），跨模块调用的既有通道，定制加载时要保持兼容

callscript(actor, filename, label)

调用TXT脚本命令，老脚本命令与新模块混用的边界

callscriptex(actor, scriptname, arr)

调用传奇脚本命令，同上，注意参数类型与返回值差异

触发调用

gotolabel(actor,type,label,range)

调用触发，模块对外暴露能力的另一条通道

调试

release_print(msg)

打印消息到控制台，加载失败时把搜索路径打出来，比猜快得多