资源加载系统 · 架构解析

源设计起源 · 为什么要做这个模块

• 没它会怎样：编辑器会骗人：真机上资源在包里、加载本身是异步的，用同步方式取根本拿不到；而编辑器里因为直读工程，同步反而好使 —— 于是"编辑器能跑、真机拿不到"成了这类系统的经典错觉。
• 绕过它就等于放弃一整套能力：直接去读 StreamingAssets 或工程目录，等于没有缓存、没有引用计数、平台分支要自己写、还没法热更 —— 所以"统一走资源系统"是一条纪律，不是偏好。
• 加载了没人还，内存就悄悄涨：系统把"加载几次就要归还几次"变成纪律，引用归零后才进入待释放。分组没传对的后果也不会崩，而是"切了场景内存没降下来" —— 这类问题最难查。
• 错误必须能被看见：漏标的资源在编辑器里照常能加载，到真机才找不到，所以打包工具在打包前就把它拦下来；运行时加载失败也不抛异常、不打日志，把原因留在句柄上等你去查。

本篇只讲为什么；怎么用见同目录《使用说明》。

0三句话速览（完整用法见《使用说明》）

① 资源放到      「资源根目录」下（先在打包窗口里指定，如 Assets/GameRes；目录随便分，嵌套多少级都行）
② 给文件夹设 AB 名（Inspector 右下角）→ 菜单 Revolution.Tools/资源/RevAB 打包工具
                →「检查」页签确认没有"漏标"资源 →「打包」页签点「打包」
③ 加载          Sprite icon = RevResManager.Load<Sprite>(RevResPath.UI_Icon, "Hero_1001", RevResGroup.UI);

就这三步，剩下的都是这三步的细节。

1一行代码加载资源

1.1 同步：一行（编辑器直读 / 已经缓存过）

Sprite icon = RevResManager.Load<Sprite>(RevResPath.UI_Icon, "Hero_1001", RevResGroup.UI);

• 第一个参数是根目录段（用生成的 RevResPath 常量，见 1.4；资源就在资源根目录下时传 ""）；
• 第二个参数是资源名（不带扩展名；也可以再带子目录，见第 2 章的多级嵌套）；
• 第三个参数是资源分组（决定切场景时会不会被整组卸掉，见第五章）；
• 两段会被拼成完整逻辑路径 UI/Icon/Hero_1001 —— 拼这一步业务不用管，也不需要自己写 /；
• 失败返回 null；想拿失败原因就用 LoadHandle<T>（同样用泛型，不用写 typeof）：

RevResHandle handle = RevResManager.LoadHandle<Sprite>(RevResPath.UI_Icon, "Hero_1001", RevResGroup.UI);
if (!handle.IsLoaded) Debug.LogError($"加载失败：{handle.ErrorReason}");

1.2 异步：真机首次加载必须用这个

系统提供的异步接口用泛型就行，不需要写 typeof：

RevResManager.LoadAsync<Sprite>(RevResPath.UI_Icon, "Hero_1001", sprite =>
{
    if (sprite == null) return;          // 失败：回调收到的就是 null
    image.sprite = sprite;
}, RevResGroup.UI);

RevResHandle h = RevResManager.LoadAsync<Sprite>(RevResPath.UI_Icon, "Hero_1001", s => image.sprite = s, RevResGroup.UI);
if (!h.IsLoaded) Debug.LogError($"失败：{h.ErrorReason}");

1.3 想要"一行"的异步写法？在业务侧包一层

系统自带自研 RevTask（Runtime\RevTask\），包一层就能 await：

/// <summary>业务侧封装：把回调式异步变成 await 式（放在你自己的 ResExt.cs 里）</summary>
public static RevTask<T> LoadAsync<T>(string rootPath, string resName, RevResGroup group = RevResGroup.Unknown)
    where T : UnityEngine.Object
{
    var source = RevTask<T>.CreateSource();
    RevResManager.LoadAsync<T>(rootPath, resName, obj =>
    {
        if (obj != null) { source.SetResult(obj); return; }
        // 失败原因从资源系统缓存里的句柄上取（查询同样是两参数）
        RevResLoadErrorReason reason = RevResManager.Get(rootPath, resName).ErrorReason;
        // 要打日志时把两段拼成完整路径
        source.SetException(new System.Exception(
            $"[Res] {RevResPathUtil.Join(rootPath, resName)} 加载失败：{reason}"));
    }, group);
    return source.Task;
}

// 用起来就是一行：
Sprite icon = await LoadAsync<Sprite>(RevResPath.UI_Icon, "Hero_1001", RevResGroup.UI);

1.4 更推荐：生成的 RevResPath 目录常量 + 两参数 API

打包工具会扫描「资源根目录」下的所有文件夹（含多级嵌套），生成 Assets/Revolution/Generation/RevResPath.cs， 每个文件夹一条常量（值都带结尾 /）：

// ❌ 手写整条逻辑路径：资源名那一段写错，要等运行时才知道"资源找不到"
RevResManager.Load<Sprite>("UI/Icon/Hero_1001", RevResGroup.UI);          // ← 旧写法，现在的 API 参数对不上

// ✅ 目录段用常量（编译期保护 + IDE 补全），资源名单独一个参数
RevResManager.Load<Sprite>(RevResPath.UI_Icon, "Hero_1001", RevResGroup.UI);

生成物长这样（节选）：

public static class RevResPath
{
    public const string UI                      = "UI/";
    public const string UI_Icon                 = "UI/Icon/";
    public const string UI_UIPanel              = "UI/UIPanel/";
    public const string UI_UIPanel_LobbyPanel    = "UI/UIPanel/LobbyPanel/";
    // ...
}

为什么是"目录常量 + 资源名"两个参数，而不是一条完整路径字符串？

代价也很明确：资源名那一段仍然是普通字符串，写错不会编译报错，只会在运行时加载失败（建议从 Project 窗口复制名字）。 换来的是"加资源不用等生成"，这个交换在迭代期更划算。

1.5 常用 API 速查

优先级（排队顺序）：Background(0) 预加载 < Normal(100) 默认 < Urgent(300) 紧急资源。

2资源应该放到哪个路径下面

Assets/GameRes/                     ← 资源根目录（resRoot）
├── UI/
│   ├── Icon/
│   │   └── Hero_1001.png          →  逻辑路径 "UI/Icon/Hero_1001"
│   └── HeroPanel.prefab           →  逻辑路径 "UI/HeroPanel"
├── Hero/
│   └── 1001.prefab                →  逻辑路径 "Hero/1001"
├── Sound/
│   └── Skill_1001.ogg             →  逻辑路径 "Sound/Skill_1001"
└── Config/
    └── Data/
        └── Hero.txt               →  逻辑路径 "Config/Data/Hero"

RevResManager.Load<Sprite>(RevResPath.UI_Icon, "Hero_1001", RevResGroup.UI);
RevResManager.Load<GameObject>(RevResPath.Hero, "1001", RevResGroup.Battle);

多级嵌套随便用，而且"在哪一段切开"是等价的 —— 内部拼出来的完整路径完全一样：

RevResManager.Load<GameObject>(RevResPath.UI_UIPanel_LobbyPanel, "MailPanel", RevResGroup.UI);  // 常量用最深层
RevResManager.Load<GameObject>(RevResPath.UI_UIPanel, "LobbyPanel/MailPanel", RevResGroup.UI);  // 常量到中层
RevResManager.Load<GameObject>(RevResPath.UI, "UIPanel/LobbyPanel/MailPanel", RevResGroup.UI);  // 只用顶层常量
// 三者等价：逻辑路径都是 "UI/UIPanel/LobbyPanel/MailPanel"

所以常量名太长、或者嫌目录太深时，只把稳定的前缀做成常量、剩下的层级写进资源名就行，缓存键不受影响。

2.1 两种边角情况

2.2 三条必须记住的纪律

1. 逻辑路径不带扩展名。带扩展名会被当成另一条路径 —— 所以用生成的 RevResPath 目录常量 + 资源名的两参数写法最稳（RevResPath.UI_Icon, "Hero_1001"）。
2. 不要手写 Assets/... 开头的路径，那是把"资源怎么组织"泄漏进业务代码。
3. 不要直接读 StreamingAssets / Application.dataPath。绕开资源系统 = 没有缓存、没有引用计数、平台分支自己写、还没法热更。
   数据表系统就是靠这条纪律统一走资源系统的。

2.3 关于 Resources 兜底

RevResourcesResPolicy 是策略链的最后一环，接两类请求：业务显式写 "Res/xxx" 前缀的、以及 AB 加载失败后允许兜底的。

3AB 包怎么划分

3.1 先说结论：按"一起用、一起卸"的粒度分包

分包的唯一目的是控制"下载/更新的粒度"和"加载/卸载的粒度"。所以判断标准只有两条：

• 生命周期一致：会同时加载、同时卸载的资源放一个包（比如进战斗用的英雄模型 + 技能特效）。
• 业务域一致：和 RevResGroup 的划分对齐（UI / Battle / Sound / Scene），这样卸载能整组回收。

3.2 怎么设 AB 名：给文件夹设（推荐）

Unity 的规则是"资源自己身上写着属于哪个包"，标记存在 .meta 里。最省事的方式是给文件夹设 AB 名，子文件自动继承：

Assets/GameRes/UI/Icon/          ← 选中这个文件夹，Inspector 右下角 AssetBundle 填 "ui"
                                       下面所有图（含以后新增的）自动进 ui 包

Assets/GameRes/Hero/             ← 填 "hero"
Assets/GameRes/Sound/            ← 填 "sound"

好处：新加资源不用手动标记，也不会漏。ResMap 里会长成：

UI/Icon/Hero_1001|ui|Hero_1001
Hero/1001|hero|1001

3.3 两种分包模式

两个排除列表的作用范围（容易记混，这里说清）：

3.4 六条分包实践

1. 一个包别太大：改一张图要重下整个包，热更成本直接等于包体积。
2. 一个包别太碎：单个资源的包会被校验器警告（"单资源包"），且 IO 次数多。
3. 共享资源单独一个包（如 common）：被多个包依赖的图集、Shader、通用字体放进公共包。否则依赖分析会报"共享资源被复制多份，体积膨胀"。
4. 不要形成循环依赖：校验器会直接报 循环依赖 错误，打包中止。
5. 依赖会被自动递归加载：加载 hero 时，系统会先按 Manifest 把它依赖的包全部加载好，业务不用管。
6. 命名只用 [A-Za-z0-9_-/.]：中文、空格会被校验拦下；文件名建议全小写（Linux/Android 区分大小写，Windows 不区分）。

4打包流程与注意事项

4.1 流程（一键）

菜单 Revolution.Tools/资源/RevAB 打包工具：

六个页签：打包 · 分包 · 依赖 · 体积 · 检查 · 快照（「检查」的标题上直接带问题数，不用点进去就知道现在能不能打包）。「打包」页签从上到下：

• 顶部操作栏　目标平台（默认跟随当前平台，可不切平台直接打别的平台）· 输出目录（「打开」直达）· 「打包」主按钮 ·「仅生成映射」·「仅校验」
• 资源目录　资源根目录（必填，可拖拽）+ 音效目录 / BGM 目录
• 分包方式　使用已有标记（推荐）/ 按目录自动分包（切过去会先确认：它会清空全部手动分包）+ 排除目录 / 后缀 + 漏标检查
• 打包选项　压缩方式（LZ4 / LZMA / 不压缩）· 强制重打 · 打包前清空输出 · 拷到 StreamingAssets · 版本号
• 代码生成　手动生成 / 打开 RevResPath.cs、RevSoundPath.cs（默认折叠：打包和生成映射都会顺带生成）
• 校验结果　红色 = 必须修（阻止打包），黄色 = 建议修；过期会提示「重新校验」；一键跳到「检查」页签
  ★「漏标」（资源没设 AB 名）也在红色里 —— 它会直接中止打包，见 4.4
• 打包结果　平台 · 包数 · 产物体积 · 用时；「打开输出目录」「复制路径」「看产物清单」；共享资源 / 循环依赖提示

「分包」页签（也可以从菜单 Revolution.Tools/资源/RevAB 分包浏览 直接打开；对标 Unity 官方 AssetBundle Browser 的 Configure 页）

左边是包树、右上是资源表、右下是详情，两条分隔条都能拖；列宽、排序、选中、展开都会记住：

另外四个页签：「依赖」「体积」「检查」「快照」

它们和「分包」共用同一份扫描结果（改完分包会自动失效重算；每个页签也都有「刷新」）。包名都能点：点了跳到「分包」页签并选中它。

改完分包记得回「打包」页签点一次「仅生成映射」：映射表（ResMap.txt）和 RevResPath 才会跟着更新，同时会自动留一份「上次打包」快照给「快照」页签做对比。

「打包」按钮实际做了六步：

收集 AB 标记 → 校验（有 error 就中止）→ BuildPipeline.BuildAssetBundles
→ 依赖分析 → 写 ResMap.txt + BuildManifest.json → 生成路径常量 →（可选）拷到 StreamingAssets

4.2 产物都在哪

AssetBundles/PC/                  ← 打包输出（OutputRoot/平台名）
├── PC                            ← ★ 主包（名字 = 输出目录名，Unity 的规则）
├── PC.manifest                   ← 依赖清单（运行时靠它查依赖）
├── ui / ui.manifest              ← 你分的包
├── hero / hero.manifest
└── BuildManifest.json            ← 给人/CI 看：版本、平台、时间、每个包大小

Assets/Revolution/Resources/ResourceSystem/ResMap.txt  ← 逻辑名|包名|资源名（框架自己的 Resources）
                                                          运行时 Resources.Load("ResourceSystem/ResMap") 读它
Assets/Revolution/Generation/RevResPath.cs     ← 自动生成的目录前缀常量（扫描资源根目录下的文件夹）
Assets/StreamingAssets/PC/                  ← 拷进来的运行时产物

运行时的查找路径是 StreamingAssets/<平台名>/<包名>，平台名 = 产物目录名 = 主包名：

4.3 打包注意事项（按踩坑概率排序）

1. 命名非法会直接中止打包：只允许 [A-Za-z0-9_-/.]。中文、空格、括号都不行。
2. 逻辑路径冲突会中止：Hero/1001.prefab 和 Hero/1001.png 都会算成 Hero/1001，必须改名。
3. 同一包内资源重名会中止：A/Icon.png 与 B/Icon.png 都在 ui 包里 → LoadAsset("Icon") 取到哪个不确定。改名或拆包。
4. 漏标会中止：资源在资源根目录下、却没有任何 AB 标记 → 不进任何包，真机必然 FileNotExist。这是手动分包模式最常犯的错，工具会拦（详见 4.4）。
5. 空包会中止：标了 AB 名但一个资源都没有（资源删了/改名了的残留），去把标记清掉。
6. 换平台必须重新打包：AB 不跨平台。把 Android 的包放到 PC 的目录里，加载会 BundleLoadFail。
7. 压缩方式：默认 LZ4（块压缩，加载快、体积中等，推荐）；首包/下载包可换 LZMA（更小、首次加载更慢）；None 只用于调试。
8. 增量是自动的：forceRebuild 关闭时，Unity 按内容 Hash 跳过没变的包；只有怀疑产物脏了才勾它。
9. 编辑器默认不走 AB：开发期 RevEditorResPolicy 直读工程（所有资源一律 AssetDatabase 读，不打包也能跑）。要验证 AB 链路，用菜单 Revolution.Tools/资源/AB 加载模式（编辑器） 切换，或直接出真机包验证。
   ⚠️ "编辑器能跑"不代表"真机能跑"，AB 链路一定要在真机上验一次。
10. copyToStreamingAssets 打开后是"整目录覆盖"：目标目录会被先删再拷，别往里放手写的东西。
11. 任何 Resources 文件夹里的东西都会被无条件打进包体：框架的 ResMap.txt 就放在它自己的 Assets/Revolution/Resources/ResourceSystem/ 里（很小）。别把大资源往任何 Resources 文件夹里放 —— 包括框架这个：它存在的唯一目的就是让 Resources.Load 能读到这张小表。

4.4 漏标检测：手动分包最该防的一件事

漏标 = 资源在「资源根目录」下，却没有被任何 AB 包收走（自己没设 AB 名，父文件夹也没设）。

它的可怕之处在于隐形：

编辑器里：AssetDatabase 直读，照常能加载 —— 一切正常
真机上：  ResMap 里查不到它 → PathNotMapped → 兜底 Resources 也没有 → FileNotExist

所以工具在打包前就把它拦下来：

• 走的是反向扫描：从资源根目录枚举所有资源，逐个查 AssetDatabase.GetImplicitAssetBundleName （用 Implicit 版本，所以"只给文件夹设了标记、子文件自动继承"的资源不会被误报）；
• .meta、excludeExtensions、excludeFolders 里的一律跳过（它们本来就不该进包，报出来只会淹掉真问题）；
• 发现漏标 → 校验报错、中止打包（CI 打包同样会因此失败退出），并在「检查」页签 ① 列出完整清单，每条都能「定位」，也可以「全部加入一个包…」一步补上。

5运行时生命周期（别让资源泄漏）

5.1 引用计数

Load / LoadAsync        → RefCount +1（缓存命中也 +1）
Release(rootPath,resName) → RefCount -1
RefCount 归零           → 进入"待释放表"（不会立刻卸，防抖动）
FlushUnused / 自动卸载  → 冷却期过后真正卸载 + Resources.UnloadUnusedAssets

5.2 分组：切界面 / 切场景整组回收

RevResManager.Load<Sprite>(RevResPath.UI_Icon, "Hero_1001", RevResGroup.UI);

// 关界面时：连同"还在被引用"的一起清账（force = true）
RevResBootstrap.Instance.Shutdown(RevResGroup.UI);

// 只想清引用已归零的（更安全）
RevResBootstrap.Instance.Shutdown(RevResGroup.UI, force: false);

跨域共享的资源（公共图集被 UI 和 Battle 同时用）要打 RevResInstanceFlag.Resident 标志 —— 它永不参与分组卸载，连 force 也不会误伤。

分组三连问：可选吗 / 要传吗 / 能自定义吗

① 是可选参数吗？　是。签名是 group = RevResGroup.Unknown，不传就是 Unknown。

② 到底有没有必要传？　取决于"这个资源将来要不要被整组回收"：

⚠️ 另外记住：归属"首次确定，之后不再变更"。同一个资源被 A 域先加载、B 域后加载，它算 A 域的。跨域共享的资源请打 RevResInstanceFlag.Resident。

③ 能自定义分组吗？　能，两条路：静态分组加枚举值、动态分组用 RevResGroupUtil.Custom(n)。 （框架故意不做"字符串注册接口"，原因见本段末尾。）

路线 1：加枚举值 —— 静态分组（推荐）

适用：分组数量固定、编译期就知道（背包 / 商店 / 邮件…）。在 RevResDefine.cs 的 RevResGroup 里往后追加：

public enum RevResGroup
{
    Unknown,    // 0
    Battle,     // 1
    UI,         // 2
    Sound,      // 3
    Config,     // 4
    Scene,      // 5
    Bag,        // 6  ← 新加的，只能追加在末尾
    Shop,       // 7
}

业务侧立刻可用：

RevResManager.LoadAsync<Sprite>(bagIconPath, s => { }, RevResGroup.Bag);
RevResBootstrap.Instance.Shutdown(RevResGroup.Bag);       // 关背包 → 该组资源整组回收

为什么加值是零风险的（已核对全工程）：

路线 2：RevResGroupUtil.Custom(n) —— 动态分组

适用：分组运行时才知道（活动 ID、副本 ID、房间号…），代码里没法写死一个枚举名。

RevResGroup g = RevResGroupUtil.Custom(activityId);      // 映射到 CustomBase(1000) 之后的区间，不和内置值撞车

RevResManager.LoadAsync<Sprite>(iconPath, s => { }, g);
RevResBootstrap.Instance.Shutdown(g);                 // 活动结束 → 该活动的资源整组卸掉

RevResGroupUtil 的三个成员（都在 RevResDefine.cs）：

两条路怎么选

不想碰框架文件时，把自定义分组集中声明在一处，别让 Custom(1) / Custom(2) 散落各地（回头记不住几号是几号）：

// 业务侧：自定义分组集中声明
public static class MyGroups
{
    public static readonly RevResGroup Bag  = RevResGroupUtil.Custom(1);
    public static readonly RevResGroup Shop = RevResGroupUtil.Custom(2);
    public static readonly RevResGroup Mail = RevResGroupUtil.Custom(3);
}

为什么不做成"字符串分组 / 注册接口"？

字符串分组要分配、要比内容，而且拼错一个字母不会报错 —— 只会在卸载时"点名不到"，等于把错误从编译期推迟到运行时，还是静默的。数值 ID 零成本、可断言、可比较，所以扩展方式就只有"编译期加枚举值 + 运行期数值映射"这两条。

真需要"名字 → 分组"时（比如策划表里写 "Bag"），应该在业务层做一次映射（读表时把字符串转成 RevResGroup），而不是把字符串语义下沉进资源系统 —— 这样资源系统保持零成本，字符串的容错与报错留在它该在的地方。

5.3 资源域：using 自动回收（最省心）

using (var scope = RevResManager.OpenScope())
{
    var prefab = scope.Load<GameObject>(RevResPath.UI_MainForm, "MainForm", RevResGroup.UI);
    var icon   = scope.Load<Sprite>(RevResPath.UI_Icon, "Hero_1001", RevResGroup.UI);
}   // ← 出大括号自动 Release，中途 return 也保证执行

5.4 自动卸载门卫（不用管，但要会调）

RevResBootstrap.Init() 时会启动 RevResAutoUnloader，5 个触发源：定时检查 / 内存告急 / 缓存超阈值(LRU) / 空闲时才动手 / 切场景。

5.5 预加载：进战斗前把资源铺好

RevResPreloader.Preload(
    new[] { (RevResPath.Hero, "1001"), (RevResPath.Skill, "1001_Effect") },  // 一批可跨多个目录
    group: RevResGroup.Battle,
    priority: RevResLoadPriority.Background,          // 不抢前台
    onProgress: task => bar.value = task.Progress, // 0~1 进度
    onCompleted: task => Debug.Log($"预加载完成：{task.Finished}/{task.Total}，失败 {task.Failed}"));

// 同一目录下批量（简写）：
RevResPreloader.Preload(RevResPath.UI_Icon, new[] { "Hero_1001", "Hero_1002" }, RevResGroup.UI);

// 只预加载一个：
RevResPreloader.Preload(RevResPath.Hero, "1001", RevResGroup.Battle);

// 归还预加载持有的引用（不影响业务自己持有的引用）
RevResPreloader.Release(RevResGroup.Battle);

预加载会保留一份引用 —— 否则加载完没人引用，下一次自动卸载就把它清掉了，等于白做。

RevResPreloadTask 上还有 IsDone / IsCancelled / Cancel()，以及 OnProgress / OnCompleted 两个事件。

6加载失败排查表

失败一律不抛异常、不打日志，原因记在 handle.ErrorReason 上：

7完整示例：一个界面从打开到关闭

public class HeroPanel : MonoBehaviour
{
    [SerializeField] private Image _icon;

    private RevResScope _scope;

    private void OnEnable()
    {
        // ① 开一个资源域：这次界面加载的所有资源都挂在它身上
        _scope = RevResManager.OpenScope();

        // ② 加载（编辑器直读；真机走 AB，第一次加载请用异步版）
        _icon.sprite = _scope.Load<Sprite>(RevResPath.UI_Icon, "Hero_1001", RevResGroup.UI);

        // ③ 预加载下一个界面要用的资源（后台，不抢前台）
        RevResPreloader.Preload(RevResPath.UI_Icon, new[] { "Skin_1001" }, RevResGroup.UI);
    }

    private void OnDisable()
    {
        // ④ 出域即回收：该界面独占的资源引用全部归还
        _scope?.Dispose();
        _scope = null;
    }
}

切场景时统一收口：

RevResBootstrap.Instance.Shutdown(RevResGroup.UI);   // 归还预加载引用 + 按组卸载 + 真正释放
RevResBootstrap.Instance.ShutdownAll();           // 回登录界面：全清 + 释放所有 AB 包

8附：关键文件索引

RevAB 打包工具的目录划分（Editor\RevResourceSystem\ABTool\，原名 LiteAB）：