RevHotUpdate · 使用说明（手把手）

03 分钟跑通（启动时调用一次，就是全部）

前置

1. 框架已经能用（RevResManager.Load* 能加载资源）；
2. 用框架的打包工具打过一次 AB（AssetBundles/<平台>/）；
3. 远端（CDN / 对象存储）上有一个目录，里面是"和打包产物同结构"的资源 + 一份清单。

代码（放在"加载任何业务资源"之前）

RevHotUpdateResult result = await RevHotUpdate.InitializeAsync(
    new RevHotConfig
    {
        RemoteRoot = "https://cdn.example.com/gameA",     // 唯一必填项
    },
    p => loadingBar.Set(p.Percent, p.Text));              // 进度：p.Text 已是一句人话

if (result.Success == false)
{
    // 热更失败不等于"进不去游戏"：旧版本照常能玩，这里按你们的产品策略处理（重试 / 跳过 / 提示）
    tips.Show(result.Error.Message);
}

// 之后照旧写业务，加载 API 完全不变：
RevResManager.LoadAsync<Sprite>(RevResPath.UI_Icon, "Hero_1001", sprite => icon.sprite = sprite, RevResGroup.UI);

关于重复调用与等待

• 重复调用不会跑两遍：热更进行中再次调用 InitializeAsync，会直接等正在跑的那一轮的结果（防止下载两遍、资源策略重装两次）；
• 别处想等它结束（例如首场景的业务要等热更完成才加载）：调 await RevHotUpdate.WaitReadyAsync() —— 它不发起新热更，只是等正在进行的那一轮；
• 取消：传一个 RevCancellationToken（框架自带）即可；已下载的内容会保留，下次继续。

三条必须记住的规矩

1它做什么、不做什么

2装在哪里

Assets/Revolution.HotUpdate/
├── Runtime/    asmdef: Revolution.HotUpdate         （引用 Revolution.Runtime）
└── Editor/     asmdef: Revolution.HotUpdate.Editor  （仅编辑器，引用 Revolution.Runtime / HotUpdate / Editor）

怎么拿到这个包（两种装法）

# ① 分支安装（推荐，与框架本体配对）：每个包各一条命令
git clone -b package   https://github.com/Yokino337088/Revolution.git Assets/Revolution
git clone -b hotupdate https://github.com/Yokino337088/Revolution.git Assets/Revolution.HotUpdate

# 想跑本目录开头提到的那个 demo（示例工程在 demo 分支）：
git clone -b demo      https://github.com/Yokino337088/Revolution.git Assets/Revolution.Demo
# → Assets/Revolution.Demo/RevHotUpdate.Demo/（演示面板 + 场景 + 起本地CDN.cmd 假 CDN）

# ② 或者：直接把仓库里的 RevolutionFrameWork_Unity/Assets/Revolution.HotUpdate 拷进自己工程的 Assets 下

"不导入零影响"靠四条：① 独立程序集，框架不反向引用它；② 零静态构造、零 Update，没人调用就不干活；③ 它给框架加的两个钩子默认是 null，不设置时框架行为与从前逐字节一致；④ 卸载 = 删掉这个目录 + 启动流程里那一行调用。

对框架的改动（就这两处）

这两个钩子怎么用（面向小白，含可照抄示例）

钩子 1：RevABLoader.BundlePathResolver —— "这个包该去哪读？"

契约（先背下来）：

• 参数：包名。就是 ResMap.txt 第二列那个名字，也是 AssetBundles/<平台>/ 下的文件名（没有扩展名，比如 hero）。
• 返回：这个包的完整本地文件路径（D:/.../hero）或 URL（https://cdn.../hero，WebGL / 小游戏用）。
• 返回 null（或空串）= "我不管，按框架默认来" → 框架走 {StreamingAssets}/<平台名>/<包名>。
• 调用时机：每次要加载某个包时都会被问一次（包已缓存在内存里就不会再问）。它只回答"从哪读"：不负责下载，也不负责卸载。

示例 1：自研"持久化优先 + 回退内置"（≈ 官方那套的最小版，可直接抄）：

using System.IO;
using Revolution;
using UnityEngine;

/// <summary>自研包路径解析：下过更新就用更新，没下过就回退出包自带的那份。</summary>
public static class MyCdnPaths
{
    /// <summary>更新下来的包放哪：{persistentDataPath}/MyCdn/<平台>/bundles/</summary>
    public static string LocalBundleDir
    {
        get
        {
            // ★ 平台名必须与打包产物的目录名一致（Standalone 一律是 "PC"）—— 对不上就会一直找不到文件
#if UNITY_ANDROID && !UNITY_EDITOR
            const string platform = "Android";
#elif UNITY_IOS && !UNITY_EDITOR
            const string platform = "iOS";
#else
            const string platform = "PC";
#endif
            return Path.Combine(Application.persistentDataPath, "MyCdn", platform, "bundles");
        }
    }

    /// <summary>★ 这个函数就是钩子本体：框架每要加载一个包，就来问一次"它从哪读"。</summary>
    public static string ResolveBundlePath(string bundleName)
    {
        // ① 更新目录里有 → 用它（"热更生效"就是这一步）
        string local = Path.Combine(LocalBundleDir, bundleName);
        if (File.Exists(local))
        {
            return local;
        }

        // ② 没有 → 返回 null = 交还框架默认（StreamingAssets/<平台名>/<包名>）
        //    ★ 新手最容易写错的地方：返回值只能是"完整路径 / URL / null"三种。
        //      随便拼一个不存在的路径返回，框架会直接去读它并失败 —— 连"回退内置"的机会都没有。
        return null;
    }
}

装配（必须在资源系统 Init() 之前，时机说明见示例 3）：

// 启动流程里、RevResBootstrap.Instance.Init() 之前：
RevABLoader.BundlePathResolver = MyCdnPaths.ResolveBundlePath;   // ★ 用方法组，不要写 lambda（见坑 4）

钩子 2：RevResBootstrap.ResMapOverride —— "逻辑名 → 包名|资源名 的表从哪来？"

契约：

• 返回：Dictionary<string, string>；键 = 逻辑名（如 Hero/1001），值 = 包名|资源名（如 hero|1001，中间是半角竖线）。
• 返回 null = 不覆盖（框架只用内置表）。
• 语义是"覆盖合并"：你返回的表里同名键覆盖内置表，内置表独有的键保留 —— 所以"新资源能热更、老资源仍有兜底"。
• 调用时机：每次资源系统初始化（RevResBootstrap.Init()）时调一次，结果被拿去合并成最终表。

示例 2：读一张自己下发的表（格式与框架 ResMap.txt 完全一致：逻辑名|包名|资源名）：

using System.Collections.Generic;
using System.IO;
using Revolution;

/// <summary>自研映射表覆盖：把"更新下来的表"交给框架合并。</summary>
public static class MyCdnResMap
{
    /// <summary>★ 钩子本体：返回 null = 不覆盖；返回表 = 覆盖合并到内置表上。</summary>
    public static Dictionary<string, string> LoadOverrideResMap()
    {
        string path = Path.Combine(MyCdnPaths.LocalBundleDir, "..", "ResMap.txt");
        if (File.Exists(path) == false)
        {
            return null;                     // ★ 没有"更新表"就什么都不做，让框架用自己的内置表
        }

        var map = new Dictionary<string, string>(512);
        foreach (string raw in File.ReadAllLines(path))
        {
            string line = raw.Trim();
            if (line.Length == 0 || line.StartsWith("#")) { continue; }   // 空行与 # 注释跳过

            string[] parts = line.Split('|');
            if (parts.Length != 3) { continue; }                          // 列数不对就跳过（容错，别让一行坏数据炸掉整张表）

            map[parts[0]] = parts[1] + "|" + parts[2];                    // 逻辑名 → 包名|资源名
        }

        return map.Count > 0 ? map : null;   // 空表也没必要覆盖
    }
}

// 装配（同样要在 RevResBootstrap.Instance.Init() 之前）：
RevResBootstrap.ResMapOverride = MyCdnResMap.LoadOverrideResMap;

示例 3：装配时机 + 还原（顺序错了整套不生效）

/// <summary>自己接管资源系统初始化时的标准写法；用官方热更包则不需要（InitializeAsync 内部已处理）。</summary>
public static class MyCdnBootstrap
{
    public static void Install()
    {
        // ① 先装钩子：必须在资源系统 Init 之前 —— Init 时会读映射表、注册策略
        RevABLoader.BundlePathResolver = MyCdnPaths.ResolveBundlePath;
        RevResBootstrap.ResMapOverride = MyCdnResMap.LoadOverrideResMap;

        // ② 再让资源系统按新钩子重装一次（Init 是幂等的；已经 Init 过就先卸干净）
        RevResBootstrap.Instance.ShutdownAll();
        RevResBootstrap.Instance.Init();
    }

    /// <summary>还原：钩子置回 null = 回到框架默认行为（"临时关掉自研热更"最省事的办法）。</summary>
    public static void Uninstall()
    {
        RevABLoader.BundlePathResolver = null;
        RevResBootstrap.ResMapOverride = null;
        RevResBootstrap.Instance.ShutdownAll();
        RevResBootstrap.Instance.Init();
    }
}

五个坑（新手必读）

1. 返回值只能是"完整文件路径 / URL / null"：返回一个不存在的路径 = 框架会直接去读它然后失败，连回退内置的机会都没有。想"我不管"就返回 null。
2. 别在钩子里做重活：它会被每个包问一次（首屏几十个包 = 几十次调用），别在里面解析大文件、发网络请求或拼一堆字符串。
3. 路径不含扩展名：AB 在磁盘上就叫 <包名>（没有 .bundle / .ab 后缀），加后缀会读不到。
4. 用方法组，不要写捕获实例的 lambda：= MyCdnPaths.ResolveBundlePath; ✓；写成 = name => new MyCdn(name).Resolve(name) 会持有闭包 —— 关闭 Domain Reload 的工程第二次进 Play 可能拿到失效对象。
5. 必须在 RevResBootstrap.Init() 之前设置。判断法：Init 之后再设 = 本次不生效；要生效就 ShutdownAll() → 设钩子 → Init()（示例 3 就是这个顺序）。

想知道"到底生效了哪一份"？

• 用官方热更包：看 RevHotUpdate.LocalResVersion 与 RevHotUpdate.Dump()；
• 自研：在 ResolveBundlePath 里每个包第一次返回时打一条日志 —— RevLog.Info($"包 {bundleName} 来自 {local}", "MyCdn")。「到底读的是哪一份」这类问题，靠这一行日志最容易定位。

3入口 API 与进度

分步用法（UI 自己掌控）

// ① 只检查：拿到"有没有更新 / 要下多少"
RevHotCheckResult check = await RevHotUpdate.CheckAsync(config);
if (check.Success == false) { /* 失败：旧版本照常可用 */ }
if (check.ForceUpdateRequired) { /* 大版本不匹配：走你们的强更流程（跳商店 / 公告） */ }
if (check.HasUpdate == false) { return; }

// ② 玩家确认（弱网/大包策略都在这层做）
if (check.TotalBytes > 50 * 1024 * 1024 && IsWifi() == false) { showTips(check.TotalBytesText); return; }

// ③ 下载 + 校验 + 落地（可取消：token 用框架的 RevCancellationTokenSource）
RevHotUpdateResult result = await RevHotUpdate.UpdateAsync(check, p => bar.Set(p.Percent, p.Text), tokenSource.Token);

可观察的状态

4配置字段表

只需要填 RemoteRoot 就能跑；下表是"什么时候该改哪一项"。

5出包与发布流程

1. 打 AB：框架打包工具 → AssetBundles/<平台>/（开"拷贝到 StreamingAssets"把首包放进包体）；
2. 生成清单：菜单 Revolution.Tools / 热更新 / 热更清单窗口 → 填大版本 / 资源版本 → 点「生成清单」；
3. 自检：同一窗口点「自检」——缺包、大小不符、依赖不闭环、清单没带映射表，都会当场列出来；
4. 上传内容：把产物目录里的包 + ResMap.txt 传到 {RemoteRoot}/{环境?}/{平台}/{大版本}/{渠道?}/{资源版本}/bundles|ResMap.txt；
5. 最后上传清单：把 RevHotManifest.txt 传到 {RemoteRoot}/{环境?}/{平台}/{大版本}/{渠道?}/（不带资源版本的那一层）；
6. 交给客户端：客户端下次启动就会自己发现并更新。

配置侧的三条：

6本地目录长什么样 / 怎么回滚

{persistentDataPath}/RevHotUpdate/
├── current.txt                              ← 当前生效的资源版本（原子替换；删掉它 = 回到出包状态）
├── _builtin/{平台}/<包名>                    ← 首包落地（Android 从 APK 拷出来的那份）
└── {平台}/{大版本}/{资源版本}/
    ├── .stamp                               ← 完成标记（有它才允许被加载）
    ├── RevHotManifest.txt                   ← 该版本清单副本（下次差量计算的基线）
    ├── ResMap.txt                           ← 热更映射表
    └── bundles/<包名>

回滚（同一大版本内）：把 current.txt 改成上一个版本号（或让业务加个"回滚"按钮调你们的落地逻辑）→ 下次启动就加载旧版本。旧版本目录由 KeepVersions 保留。

最坏兜底：直接删掉整个 RevHotUpdate 目录 → 下次启动按"出包状态"跑（内置资源），Android 会重新落地首包。

7平台差异

8常见问题（FAQ）

9错误码表

10接入自查清单

1. 远端 RemoteRoot 拼出来的清单 URL，浏览器能直接打开；
2. 清单里 @appVersion == 包体 Application.version；
3. Android 用默认 CopyToLocal（别改成直读）；
4. InitializeAsync 在加载任何业务资源之前；
5. 清单路径 no-cache、资源路径长缓存；
6. 上传顺序"内容先、清单后"；
7. 弱网/大包提示用的是 check.TotalBytesText（别自己算）；
8. 失败分支有 UI 提示 + 允许重试（用 result.Error.Message，它已经是人话）。