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

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 从黑箱变成你手里的模块总线。

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

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)

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

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

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

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

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

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

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