RevHotUpdate · 架构解析

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

• 没有它，包里的资源就是"编译期写死"的：框架的加载根是编译期写死的、映射表在包体的 Resources 里（运行时只读）。所以热更不去换框架的策略与加载器，而是在框架里塞两个默认为 null 的静态钩子（RevABLoader.BundlePathResolver / RevResBootstrap.ResMapOverride）：不装钩子，热更下来的包永远读不到、"新增资源"也永远加载不到。
• 为什么不自己写一个加载器：因为包的生命周期绑在框架内部：RevResHandle 的 BundleLoader / BundleName / BundleAcquired 是 internal、BundleLoader 是具体类 RevABLoader，外部加载器收不到"这个包没人用了"的通知，只能反向扫缓存去猜存活集合 —— 那是语义退化，不是等价实现。
• 热更最怕两件事：半成品和版本指针损坏：所以下载先写 .part、校验通过才改名；版本目录全部就位才打 .stamp；current.txt 用"临时文件 + 替换"写；保留 N 个历史版本当回滚逃生门；切换前先 ShutdownAll。这套原子性就是不让玩家加载到"半新半旧"的资源。
• 换来了什么：业务改造量 0 行（仍然是 RevResManager.Load*）；只下 hash 变化的包（差量）；Android 首包自动落地；小游戏走 URL 模式；以及"一轮热更只允许跑一次"（重复调用直接等同一轮，避免静默卡死）。

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

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

启动（在加载任何业务资源之前）
 └─ await RevHotUpdate.InitializeAsync(config, onProgress)
      ├─ ① 装钩子（幂等）               → 框架的加载路径与映射表从此"可被热更改写"
      ├─ ② Android：首包落地             → 把 APK 里的内置包拷到持久化目录（幂等，大小一致跳过）
      ├─ ③ 拉远端清单 + 大版本校验        → @appVersion 不匹配 → 拒绝更新并回调强更
      ├─ ④ 版本比对（远端 vs 本地基线）    → 只下 hash 变化的包（差量）
      ├─ ⑤ 下载 → 校验 → 原子落地        → .part 半成品 → 尺寸/SHA-256 → 改名到版本目录
      ├─ ⑥ 打完成标记 → 原子切版本指针    → .stamp 先于 current.txt（顺序反了会加载到半成品）
      ├─ ⑦ 清理旧版本（保留 N 份）        → 回滚能力就来自这里
      └─ ⑧ 重装资源策略（ShutdownAll → Init）→ 重读热更映射表，路径钩子按新版本解析
之后照旧：RevResManager.Load*（业务代码零改动）

分层（谁负责什么）：

Facade         RevHotUpdate          状态机 + 三个动作 + 安装（业务只碰这一层）
Core           配置 / 清单 / 版本 / 计划 / 结果 / 进度 / 错误 / 平台能力表（纯逻辑，可工程外断言）
Download       下载引擎（并发 / 重试 / 多源 / 续传）+ URL 拼装 + 源列表
Pipeline       存储管家（目录 / 原子落盘 / 首包落地）+ 校验（尺寸 + SHA-256）+ 版本比对
Integration    与框架的唯一接缝（两个钩子 + 重装资源策略）
Support        进 Play 复位内存状态（不动磁盘数据）
Editor         清单生成 + 自检 + 工具窗口

1文件职责表

运行时（18 个文件 / 3309 行）

编辑器（2 个文件 / 427 行）

2与框架的接缝：为什么是这两个钩子

结论

热更包不换框架的策略与加载器，只往框架里塞两个"默认为 null"的静态钩子：

为什么不自己写一个加载器（自研 IRevResPolicy + IRevResLoader）

因为包的生命周期绑在框架内部，外部拿不到：

• 资源释放时，框架调的是 handle.BundleLoader.ReleaseBundle(handle.BundleName)；
• 而 RevResHandle.BundleLoader / BundleName / BundleAcquired 三个字段是 internal，且 BundleLoader 的类型是具体类 RevABLoader；
• 于是自研加载器无法被通知"这个包没人用了"，只能反向扫描缓存去猜存活集合 —— 那是语义退化，不是等价实现（热更包会把"包什么时候能卸"这件事重新变成谜）。

用钩子只有 2 处、十几行，且两个平台形态（文件型 / URL 型）都只需要"换一个根"。

钩子的两条契约（写在框架侧注释里，也是断言守护的内容）

1. 不设置时（默认 null）行为与从前逐字节一致 —— 对不装热更包的工程零影响；
2. 返回 null / 空串 = "我不接这个包"，框架走默认逻辑 —— 覆盖式降级的实现方式就是"该我接的返回路径，不该我接的返回 null"。

装配时序（错了会出问题）

Install()（设钩子，幂等）
   ↓
CheckAsync（读配置、装存储、读本地基线、拉远端清单、比对）
   ↓
UpdateAsync（下载 → 校验 → 落地 → .stamp → 切指针 → 清理旧版本）
   ↓
RevResBootstrap.Instance.ShutdownAll()   ← ① 先卸载：避免"替换正在被加载的包"
RevResBootstrap.Instance.Init()          ← ② 再初始化：重读热更映射表、按新版本解析路径

3核心机制（清单 / 差量 / 原子性 / 首包落地 / URL 模式 / 挂起与等待）

1. 清单：为什么是行式文本

清单里三类信息：

@appVersion|1.2.0        ← 大版本锚点：不匹配 → 拒绝更新（跨大版本必须重出包）
@resVersion|1.2.0.37     ← 资源版本：玩家看到的就是它
@resmap|ResMap.txt|hash|size          ← 映射表也是热更文件
@bundle|hero|hash|字节数|依赖|标签|unityHash|unityCrc

大版本锚定带来的简化：资源层不需要考虑"新资源配老代码"——那是"被禁止发生"的情况，于是清单不必支持兼容区间、灰度矩阵与多版本在线查询。

2. 差量：只认 hash

远端有、本地没有            → 新增
两边都有、hash 不同          → 变更（重下）
两边都有、hash 相同          → 跳过（不下、不校验、不落盘）
本地有、远端没有              → 记下来，切完版本随旧版本目录清理
映射表 hash 变了             → 必须下（否则新增资源加载不到）

为什么不看文件大小：大小相同但内容变了（改了图但压缩后恰好同长）必须重下，只比大小会直接把错版发给玩家。

为什么不做二进制差量：LZ4 包本身就是块压缩，改一张图会波及多个块，bsdiff 类方案收益不稳定；包级差量已经拿走绝大部分带宽收益。

3. 原子性：五条纪律（每条都在防一个真实故障）

为什么不是"逐包直接覆盖"：逐包覆盖看起来更简单，但会出现"新 A + 旧 B"的窗口期——如果 A 用到 B 的新资源，玩家就会在那一瞬间报错；而且一旦玩家在覆盖到一半退出，磁盘上就是一份自相矛盾的资源。版本目录 + 完成标记让"生效"变成一个原子动作。

4. 首包落地：Android 的物理现实

• 桌面 / iOS：StreamingAssets 是真实文件目录 → AssetBundle.LoadFromFile 直接能读，不必落地；
• Android：streamingAssetsPath 是 jar:file:///…apk!/assets，不是文件路径；压缩过的 AB 用 LoadFromFile 读不了 → 必须先把内置包拷到 persistentDataPath；
• 落地是幂等的：目标已存在且大小一致就跳过（首启中断、二次启动都能续上）；整包来自自家 APK，默认只比大小（VerifyBuiltinCopy 可打开哈希校验）。

5. URL 模式：小游戏没有文件系统

也就是说：小游戏上"热更"= 把 URL 换成新版本的 URL；其余交给引擎。（清单里那两列 unityHash / unityCrc 就是为它准备的。）

6. 挂起与等待：一轮热更只允许跑一次

"一轮热更"是异步长任务（要过网络、要落盘），必须回答两个问题：

① 重复调用怎么办？（业务在两处都调了 InitializeAsync，或玩家手快点了两下）
→ 第二次调用不会跑第二遍：门面把"进行中的一轮"登记成挂起源（_pending），后来的调用直接等它 —— 两边拿到同一次更新的结果，不会下载两遍、不会把资源策略重装两次。

② 别处的代码想等它结束怎么办？（首场景业务要等热更完成才加载资源）
→ WaitReadyAsync()：不发起新热更，只等"正在进行的那一轮"；一轮结束时把结果回填给所有等待者。

4下载与容错

三层结构（从里到外）：

TryDownloadOnceAsync   一次尝试 = 断点续传下载 → 校验 → 原子提交
   · 半成品比目标还大 → 删掉重来（内容已经没救了）
   · 服务器不支持 Range（返回 200 而不是 206）→ 删掉 .part 并回退为整包重下
   · 校验失败 → 删掉 .part 并标记"可重试"（重试即从头下载）

DownloadOneAsync       一个文件 = 换源（外层）× 重试退避（内层）
   · 失败按 500ms → 1s → 2s → 4s 指数退避
   · 换源前删 .part：不同源内容不保证一致，拼接必然校验失败

DownloadPlanAsync      整批 = N 个工人从共享游标领任务
   · 任何失败 → 停止领新任务，等在跑的收尾后统一上抛（第一个错误最有诊断价值）

其它容错点：

5性能与内存

6边界：明确不做的六件事

7验证方式

8与 YooAsset 的对照

结论：不是替代关系。已经用 Revolution 的工程想加一条热更链路，用它最省；要重做资源层、需要加密/灰度，再考虑 YooAsset。

9后续可加（不做也能用）

对应代码版本：运行时 Assets/Revolution.HotUpdate/Runtime/（18 个 .cs / 3309 行）· 编辑器 Assets/Revolution.HotUpdate/Editor/（2 个 .cs / 427 行）· 框架侧钩子 RevABLoader.BundlePathResolver 与 RevResBootstrap.ResMapOverride（各十几行，默认 null）。