HybridCLR 教程（六）：完整热更新流程与版本管理

前置要求：已完成前5篇教程，项目中 HybridCLR + Addressables 环境可正常进入热更场景。
本篇目标：掌握「改代码 → 打包 → 上传 → 客户端自动拉取」的工业级热更新闭环。

一、为什么需要版本管理？

问题 没有版本管理的后果 版本管理的作用
玩家已缓存旧 dll 新逻辑不生效 通过版本号强制刷新
CDN 文件被浏览器缓存 下载到旧资源 URL 带版本哈希绕过缓存
回滚需求 无法定位历史版本 保留多版本快照
A/B 测试 所有用户看到相同内容 按版本号灰度分发

二、整体流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
[开发者修改代码]
       ↓
[HybridCLR Generate/All] → 生成热更 dll
       ↓
[Addressables Build] → 产出 bundle + catalog.json
       ↓
[版本号写入 version.txt] ← 格式: 1.0.3|20250713|a1b2c3d4
       ↓
[上传至 CDN/OSS]
       ↓
[客户端启动时请求 version.txt]
       ↓
[比对本地版本 → 下载差异资源 → 加载新 dll]

三、Step-by-Step 实现

3.1 定义版本配置文件

在 Assets 下创建 HotUpdateVersion.asset（ScriptableObject）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
using UnityEngine;

[CreateAssetMenu(fileName = "HotUpdateVersion", menuName = "HybridCLR/HotUpdateVersion")]
public class HotUpdateVersion : ScriptableObject
{
    [Tooltip("语义化版本号，如 1.0.3")]
    public string version = "1.0.0";
    
    [Tooltip("构建时间戳，自动生成")]
    public long buildTimestamp;
    
    [Tooltip("Git commit hash（可选）")]
    public string gitCommit;
}

💡 小白提示：右键 Project 窗口 → Create → HybridCLR → HotUpdateVersion 即可创建。

3.2 编辑器脚本：一键构建+写版本

创建 Editor/HybridCLRBuildTool.cs：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
using UnityEditor;
using UnityEngine;
using System.IO;
using System.Diagnostics;
using HybridCLR.Editor.Commands;

public static class HybridCLRBuildTool
{
    [MenuItem("HybridCLR/Build & Version _F9")]
    public static void BuildAndVersion()
    {
        // 1. 生成热更 dll
        CompileDllCommand.CompileDll(BuildTarget.Android);
        
        // 2. 构建 Addressables
        UnityEditor.AddressableAssets.AddressableAssetSettingsDefaultObject
            .Settings.BuildPlayerContent();
        
        // 3. 读取版本配置
        var verAsset = AssetDatabase.LoadAssetAtPath<HotUpdateVersion>(
            "Assets/Resources/HotUpdateVersion.asset");
        if (verAsset == null)
        {
            Debug.LogError("未找到 HotUpdateVersion.asset！");
            return;
        }
        
        // 4. 写入 version.txt
        string outputDir = Path.Combine(Application.streamingAssetsPath, "HotUpdate");
        Directory.CreateDirectory(outputDir);
        
        string versionLine = $"{verAsset.version}|{System.DateTimeOffset.UtcNow.ToUnixTimeSeconds()}|{GetGitHash()}";
        File.WriteAllText(Path.Combine(outputDir, "version.txt"), versionLine);
        
        Debug.Log($"✅ 热更构建完成，版本: {versionLine}");
        AssetDatabase.Refresh();
    }
    
    private static string GetGitHash()
    {
        try
        {
            var psi = new ProcessStartInfo("git", "rev-parse --short HEAD")
            {
                RedirectStandardOutput = true,
                UseShellExecute = false
            };
            using var p = Process.Start(psi);
            return p.StandardOutput.ReadToEnd().Trim();
        }
        catch { return "unknown"; }
    }
}

⚠️ 注意：首次使用前需在 Unity 菜单栏执行一次 HybridCLR → Generate → All。

3.3 客户端更新检测器

创建 Runtime/HotUpdateChecker.cs：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
using UnityEngine;
using UnityEngine.Networking;
using System.Collections;
using System.IO;

public class HotUpdateChecker : MonoBehaviour
{
    [SerializeField] private string remoteVersionUrl = 
        "https://your-cdn.com/hotupdate/version.txt";
    
    private void Start()
    {
        StartCoroutine(CheckUpdate());
    }
    
    IEnumerator CheckUpdate()
    {
        // 1. 下载远程版本文件
        using var req = UnityWebRequest.Get(remoteVersionUrl);
        yield return req.SendWebRequest();
        
        if (req.result != UnityWebRequest.Result.Success)
        {
            Debug.LogWarning($"版本检查失败: {req.error}，使用本地资源");
            LoadLocalHotUpdate();
            yield break;
        }
        
        string[] remoteParts = req.downloadHandler.text.Trim().Split('|');
        string remoteVer = remoteParts[0];
        
        // 2. 读取本地版本
        string localVer = "0.0.0";
        string localPath = Path.Combine(Application.persistentDataPath, "HotUpdate/version.txt");
        if (File.Exists(localPath))
        {
            localVer = File.ReadAllText(localPath).Split('|')[0];
        }
        
        // 3. 比较版本
        if (IsNewer(remoteVer, localVer))
        {
            Debug.Log($"发现新版本 {remoteVer}（当前 {localVer}），开始下载...");
            yield return DownloadHotUpdate(remoteParts[2]); // 传入 commit hash 作为子目录
        }
        else
        {
            Debug.Log("已是最新版本");
            LoadLocalHotUpdate();
        }
    }
    
    bool IsNewer(string remote, string local)
    {
        var r = System.Version.Parse(remote);
        var l = System.Version.Parse(local);
        return r > l;
    }
    
    IEnumerator DownloadHotUpdate(string commitHash)
    {
        // 实际项目中应使用 Addressables.UpdateCatalogs + DownloadDependenciesAsync
        // 此处简化演示核心逻辑
        
        string baseUrl = $"https://your-cdn.com/hotupdate/{commitHash}/";
        string saveDir = Path.Combine(Application.persistentDataPath, "HotUpdate");
        Directory.CreateDirectory(saveDir);
        
        // 下载关键文件列表（实际应由服务端提供 manifest）
        string[] files = { "HotUpdate.dll.bytes", "catalog.json" };
        foreach (var file in files)
        {
            using var req = UnityWebRequest.Get(baseUrl + file);
            yield return req.SendWebRequest();
            if (req.result == UnityWebRequest.Result.Success)
            {
                File.WriteAllBytes(Path.Combine(saveDir, file), req.downloadHandler.data);
            }
        }
        
        // 保存新版本号
        File.WriteAllText(Path.Combine(saveDir, "version.txt"), 
            $"{remoteVer}|{System.DateTimeOffset.UtcNow.ToUnixTimeSeconds()}|{commitHash}");
        
        Debug.Log("热更资源下载完成");
        LoadLocalHotUpdate();
    }
    
    void LoadLocalHotUpdate()
    {
        // 调用 HybridCLR 加载热更程序集
        // 参考第4篇 UI 加载逻辑
        Debug.Log("加载热更程序集...");
        // HybridCLR.RuntimeApi.LoadMetadataForAOTAssembly(...)
        // Assembly.Load(File.ReadAllBytes(...))
    }
}

🔧 生产环境建议：使用 Addressables 的 UpdateCatalogs() API 替代手动下载，它会自动处理依赖和增量更新。

四、CDN / OSS 部署规范

目录结构示例

1
2
3
4
5
6
7
8
hotupdate/
├── version.txt              # 始终覆盖更新
├── 1.0.2/                   # 历史版本（用于回滚）
│   ├── HotUpdate.dll.bytes
│   └── catalog.json
└── a1b2c3d4/                # 本次 commit hash 目录
    ├── HotUpdate.dll.bytes
    └── catalog.json

Nginx 配置要点

1
2
3
4
5
6
7
8
9
10
location /hotupdate/ {
    alias /data/hotupdate/;
    add_header Cache-Control "no-cache";      # version.txt 永不缓存
    add_header Access-Control-Allow-Origin *; # 允许跨域
    
    # dll 文件设置强缓存（URL 含 hash 故安全）
    location ~* \.(dll\.bytes|bundle)$ {
        expires 30d;
    }
}

五、常见踩坑与解决方案

现象 原因 解决
客户端仍用旧 dll CDN 缓存了旧 version.txt 给 version.txt 加 ?t=timestamp 或设 no-cache
下载后崩溃 dll 与主工程 API 不兼容 确保 Generate/All 在每次主工程变更后重新执行
iOS 审核被拒 热更 dll 被视为动态代码 使用 HybridCLR 官方推荐的 App Store 合规方案
版本比对错误 字符串比较 “1.10.0” < “1.9.0” 必须用 System.Version.Parse()

六、验证清单

  • 修改热更代码后 F9 构建，version.txt 版本号递增
  • 上传至 CDN 后，浏览器直接访问 version.txt 显示最新内容
  • 客户端清除缓存后启动，日志显示”发现新版本”
  • 第二次启动无网络时，能正常使用上次下载的资源
  • 回滚到旧版本目录，客户端正确降级

七、下一篇预告

第7篇：HybridCLR 性能优化与内存管理
我们将深入分析热更代码的 GC 行为、IL2CPP 元数据裁剪策略，以及如何避免热更模块导致的帧率抖动。

系列导航
← 第5篇：常见陷阱与调试技巧
第7篇：性能优化与内存管理 →（待更新）

说些什么吧！

waline