【工具链】资源校验：贴图缺失与引用悬空扫描

实战应用：用在哪里

客户端的黑屏贴图与紫色方块是资源悬空的典型症状：界面代码引用了一张已被删除或改名的贴图，打包时没人发现，玩家加载到才炸。资源校验在构建期扫描全部引用——贴图缺失、引用悬空、循环依赖，三类问题在打包前清零。

引用的扫描

---扫描界面代码里的资源引用
function ResScan.collect(srcDir)
    local refs = {}
    for _, f in ipairs(ResScan.luaFiles(srcDir)) do
        local src = ResScan.read(f)
        for path in src:gmatch("[\"']([%w_/]+%.png)[\"']") do
            refs[#refs + 1] = { file = f, res = path }
        end
        for path in src:gmatch("[\"']([%w_/]+%.anim)[\"']") do
            refs[#refs + 1] = { file = f, res = path }
        end
    end
    return refs
end

扫描器遍历全部界面脚本，正则抽取贴图与动画的资源路径，形成引用清单。客户端上千张贴图的引用关系一目了然，技能特效、界面皮肤、装备外观（裁决之杖的贴图引用）全部在册。扫描的规则集中维护，新资源类型（粒子、骨骼动画）登记新的抽取模式即可，扫描器本身不感知业务。

悬空的判定

---引用悬空：引用了不存在的资源
setontimerex(54, 0)   -- 构建期单次执行
function ResScan.verify(refs, resDir)
    local missing = {}
    for _, r in ipairs(refs) do
        if not ResScan.exists(resDir .. "/" .. r.res) then
            missing[#missing + 1] = r
            Ops.log("悬空引用: " .. r.res .. " <- " .. r.file)
        end
    end
    return missing
end

引用清单与资源目录做差集：引用了但文件不存在即悬空。反向的检查同样有价值：存在但没人引用的孤儿资源，打包时排除可瘦身安装包，上一轮的孤儿扫描清出 120 MB。构建的门槛：悬空引用数大于零即阻断打包，修复的责任在引入者——扫描报告带引用方的文件与行号，定位的成本趋近于零。白名单机制兜底动态拼接的路径：运行时才确定的资源名进白名单人工核对，扫描的误报不误伤开发。

验证与监控

校验的拦截记录周报，悬空的引入频率反映开发习惯；打包产物的资源完整性抽检，安装包里缺件的投诉应当为零。

踩坑记录

扫描的正则曾经漏了拼接路径，字符串拼出来的贴图名逃过扫描，动态路径白名单补位。大小写的差异在 Windows 开发机上不报错、Linux 打包机上文件找不到，路径比较统一转小写。孤儿清理曾经误删了预留资源，下个版本要用时重新画，孤儿清单标记保留期。

上线要点

资源校验挂进 CI 门禁，与语法检查同层级阻断。资源目录的命名规范与扫描规则同步演进，规范的松散是扫描失效的开端。校验报告进团队频道，悬空与孤儿的双清单每周公示，资源卫生成为全员的共识。

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