前言

前面十篇我们系统学习了 HybridCLR 的各个知识点。本篇将它们全部串联，以一个真实可运行的卡牌对战小游戏为例，手把手演示从项目初始化、架构设计、热更模块开发、CI/CD 打包到灰度上线的完整商业级流程。读完这篇，你就能独立搭建一个生产可用的 HybridCLR 热更新项目。

一、项目概述与技术选型

1.1 项目需求

模块 是否热更 原因
登录/注册流程 ✅ 频繁调整 UI 和合规文案
主界面/大厅 ✅ 运营活动入口频繁变更
卡牌战斗逻辑 ✅ 平衡性调整、新卡技能
商城/支付 ❌ 安全敏感，走 AOT
网络协议层 ❌ 底层稳定，不需热更
资源管理框架 ❌ Addressables 封装，AOT
新手引导 ✅ 内容迭代最频繁的模块

1.2 技术栈确认

1
2
3
4
5
6
Unity 2022.3.x LTS + HybridCLR 6.x + Addressables 1.21+
IDE: Rider 2024.1
CI: GitHub Actions / Jenkins
CDN: 阿里云 OSS + CDN
服务端: Go + protobuf (版本校验接口)
混淆: ConfuserEx2

二、工程目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
CardGame/
├── Assets/
│   ├── _AOT/                    # AOT 主工程代码
│   │   ├── Core/                # 框架层(网络/资源/日志)
│   │   ├── Launcher/            # 启动器+热更加载器
│   │   └── Payment/             # 支付模块
│   ├── _Hotfix/                 # 热更新代码(独立 asmdef)
│   │   ├── Login/
│   │   ├── Lobby/
│   │   ├── Battle/
│   │   ├── Guide/
│   │   └── Hotfix.asmdef        # 引用 HybridCLR.Runtime
│   ├── _Shared/                 # AOT与热更共享接口
│   │   └── IModule.cs
│   └── HybridCLRData/           # 自动生成的元数据
├── BuildScripts/
│   ├── build_hotfix.sh          # 热更DLL构建脚本
│   ├── obfuscate.sh             # 混淆脚本
│   └── upload_cdn.py            # CDN上传脚本
└── ProjectSettings/
    └── HybridCLRSettings.asset

💡 核心原则：_AOT 和 _Hotfix 通过 _Shared 中的接口通信，禁止热更 DLL 直接引用 AOT 内部类。

三、热更加载器实现

这是整个项目的枢纽，放在 AOT 主工程中：

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
// Assets/_AOT/Launcher/HotfixLoader.cs
public class HotfixLoader : MonoBehaviour
{
    [SerializeField] private TextMeshProUGUI _progressText;
    
    async void Start()
    {
        try
        {
            // Step 1: 检查并下载热更资源
            await CheckAndUpdateResources();
            
            // Step 2: 加载热更 DLL
            var dllAsset = await Addressables.LoadAssetAsync<TextAsset>("hotfix.dll").Task;
            
            // Step 3: 完整性校验
            if (!IntegrityChecker.Verify(dllAsset.bytes))
            {
                ShowError("热更文件校验失败，请重新下载");
                return;
            }
            
            // Step 4: 加载补充元数据
            await LoadSupplementaryMetadata();
            
            // Step 5: 加载热更程序集
            Assembly hotfixAssembly = Assembly.Load(dllAsset.bytes);
            
            // Step 6: 反射调用热更入口
            Type entryType = hotfixAssembly.GetType("Hotfix.EntryPoint");
            MethodInfo initMethod = entryType.GetMethod("Initialize");
            initMethod.Invoke(null, new object[] { this.gameObject });
            
            Debug.Log("[Launcher] Hotfix loaded successfully!");
        }
        catch (Exception e)
        {
            Debug.LogError($"[Launcher] Hotfix load failed: {e}");
            ShowError($"热更新加载失败: {e.Message}");
        }
    }
    
    private async Task LoadSupplementaryMetadata()
    {
        var metadataAsset = await Addressables.LoadAssetAsync<TextAsset>(
            "hybridclr_metadata.bytes").Task;
        
        RuntimeApi.LoadMetadataForAOTAssemblies(
            metadataAsset.bytes, 
            HomologousImageMode.SuperSet);
    }
}

四、热更入口点设计

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Assets/_Hotfix/EntryPoint.cs
namespace Hotfix
{
    public static class EntryPoint
    {
        public static void Initialize(GameObject root)
        {
            Debug.Log("[Hotfix] Entry point initialized");
            
            // 注册模块管理器
            var moduleManager = root.AddComponent<ModuleManager>();
            moduleManager.RegisterModule(new LoginModule());
            moduleManager.RegisterModule(new LobbyModule());
            moduleManager.RegisterModule(new BattleModule());
            moduleManager.RegisterModule(new GuideModule());
            
            // 启动第一个模块
            moduleManager.StartModule<LoginModule>();
        }
    }
}

五、CI/CD 自动化构建流水线

5.1 热更 DLL 构建脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#!/bin/bash
# BuildScripts/build_hotfix.sh

UNITY_PATH="/Applications/Unity/Hub/Editor/2022.3.40f1/Unity.app/Contents/MacOS/Unity"
PROJECT_PATH="$(dirname "$0")/.."
OUTPUT_DIR="${PROJECT_PATH}/BuildOutput/Hotfix"

echo "=== Building Hotfix DLL ==="
${UNITY_PATH} -batchmode -nographics   -projectPath "${PROJECT_PATH}"   -executeMethod HybridCLR.Editor.Commands.PrebuildCommand.GenerateAll   -logFile ./logs/hybridclr_prebuild.log

${UNITY_PATH} -batchmode -nographics   -projectPath "${PROJECT_PATH}"   -executeMethod BuildScript.BuildHotfixDll   -outputDir "${OUTPUT_DIR}"   -logFile ./logs/hotfix_build.log

echo "=== Obfuscating ==="
dotnet confuser ./BuildScripts/confuser.crproj

echo "=== Calculating Hash ==="
sha256sum "${OUTPUT_DIR}/Hotfix_obfuscated.dll" > "${OUTPUT_DIR}/hotfix.sha256"

echo "=== Build Complete ==="
ls -la "${OUTPUT_DIR}/"

5.2 GitHub Actions 示例

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
name: Build Hotfix
on:
  push:
    branches: [release/*]
    paths: ['Assets/_Hotfix/**']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Cache Unity
        uses: game-ci/unity-builder@v4
        with:
          targetPlatform: Android
          buildMethod: BuildScript.BuildHotfixDll
          
      - name: Obfuscate
        run: dotnet tool install -g Confuser.CLI && confuser ./BuildScripts/confuser.crproj
        
      - name: Upload to CDN
        run: python3 BuildScripts/upload_cdn.py --version ${{ github.sha }}
        
      - name: Notify Server
        run: |
          curl -X POST https://api.cardgame.com/admin/hotfix/version             -H "Authorization: Bearer ${{ secrets.ADMIN_TOKEN }}"             -d '{"version":"${{ github.sha }}","hash":"$(cat BuildOutput/Hotfix/hotfix.sha256)"}'

六、灰度发布策略

6.1 版本配置下发

服务端返回的版本配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "latest_version": "20240929_abc123",
  "min_version": "20240901_def456",
  "gray_scale": {
    "enabled": true,
    "percentage": 5,
    "whitelist_uids": [10001, 10002, 10086],
    "device_models": ["iPhone15,3"]
  },
  "cdn_base_url": "https://cdn.cardgame.com/hotfix/20240929_abc123/",
  "dll_hash": "a1b2c3d4e5f6..."
}

6.2 客户端灰度判断

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
public class GrayScaleManager
{
    public static bool ShouldUseNewVersion(HotfixVersionConfig config, string uid, string deviceModel)
    {
        // 白名单优先
        if (config.GrayScale.WhitelistUids.Contains(uid))
            return true;
        
        // 指定机型测试
        if (config.GrayScale.DeviceModels.Contains(deviceModel))
            return true;
        
        // 百分比灰度（基于 UID hash 保证同一用户结果一致）
        if (config.GrayScale.Enabled)
        {
            int hash = Math.Abs(uid.GetHashCode()) % 100;
            return hash < config.GrayScale.Percentage;
        }
        
        return false;
    }
}

6.3 回滚预案

1
2
3
4
5
6
7
8
9
10
触发条件（任一满足即回滚）：
  - 崩溃率 > 基线 × 3
  - 热更加载失败率 > 1%
  - 客服工单激增 > 日均 × 5

回滚操作：
  1. 服务端将 latest_version 切回上一稳定版
  2. CDN 保留旧版本资源至少 7 天
  3. 推送强制更新通知给已拉取新版本的用户
  4. 监控回滚后指标恢复情况

七、上线前验收清单

类别 检查项 状态
功能 所有热更模块在 Editor 下正常运行 ☐
功能 Android/iOS 真机热更加载成功 ☐
性能 热更模块首帧加载 < 2秒 (中端机) ☐
性能 战斗中帧率 ≥ 30fps (低端机) ☐
安全 DLL 已混淆，dnSpy 无法还原逻辑 ☐
安全 SHA256 校验通过 ☐
安全 篡改 DLL 后正确拒绝加载 ☐
兼容 从上一版本热更升级无异常 ☐
兼容 首次安装无热更时正常进入 AOT 兜底 ☐
回滚 模拟回滚流程验证可用 ☐
监控 崩溃上报通道验证 ☐
监控 热更加载成功率埋点验证 ☐

八、常见问题应急手册

线上问题 快速定位 应急措施
热更加载白屏 检查 logcat 中 [Launcher] 日志 服务端切回旧版本
战斗数值异常 对比热更 DLL 哈希是否被篡改 强制更新 + 排查 CDN 缓存
特定机型崩溃 按 device_model 聚合崩溃日志 该机型加入灰度黑名单
内存溢出 Profiler 抓热更模块内存快照 临时禁用非核心热更模块
元数据不匹配 检查 LoadMetadataForAOTAssemblies 返回值 重新生成元数据并紧急发版

总结

一个生产级 HybridCLR 项目的核心要素：清晰的 AOT/热更边界 + 可靠的加载器 + 自动化 CI/CD + 灰度发布 + 回滚预案 + 安全分层防护。这些不是锦上添花，而是缺一不可的工程基础设施。

下一篇是本系列的终章，我们将回顾整个知识体系，给出进阶学习路线图和社区资源推荐，帮助你在 HybridCLR 的道路上持续成长。

系列导航
← 第10篇：热更新安全与代码保护
第12篇：系列总结与进阶路线图 →

说些什么吧！

waline