【HybridCLR小白教程③】Addressables 资源集成与热更DLL加载

🎯 本篇目标

完成以下闭环：

1. 使用 Addressables 管理热更程序集生成的 DLL
2. 运行时从 Addressables 加载热更 DLL 并注入 HybridCLR
3. 编辑器下一键验证 + 真机远程更新流程打通

💡 前置条件：已完成第二篇环境搭建，HybridCLR Installer 已成功执行。

---

📦 第一步：安装 Addressables

1. Window → Package Manager → Unity Registry
2. 搜索 Addressables → 点击 Install
3. 等待安装完成，菜单栏出现 Window → Asset Management → Addressables

初始化 Addressables 设置

1. Window → Asset Management → Addressables → Settings
2. 首次打开会提示创建默认设置，点击 Create Addressables Settings
3. 确认 Assets/AddressableAssetsData 目录已生成

---

🔧 第二步：配置热更程序集

创建热更 Assembly Definition

1. 在 Assets 下新建文件夹 HotUpdate
2. 右键 → Create → Assembly Definition，命名为 HotUpdate
3. 选中该 asmdef，Inspector 中设置：

属性	值	说明
Name	HotUpdate	程序集名称
Root Namespace	HotUpdate	命名空间
References	留空或按需添加	不要引用其他热更程序集以外的 asmdef
Override References	❌ 不勾选	使用默认引用即可

注册到 HybridCLR

1. HybridCLR → Settings
2. 在 Hot Update Assemblies 列表中点击 +
3. 输入 HotUpdate（必须与 asmdef 的 Name 完全一致）
4. 点击 Save

⚠️ 关键：此步骤告诉 HybridCLR 哪些程序集需要被热更。遗漏会导致 DLL 不被处理。

---

🏗️ 第三步：编写第一个热更脚本

在 Assets/HotUpdate/ 下创建 HelloHotUpdate.cs：

using UnityEngine;

namespace HotUpdate
{
    public static class HelloHotUpdate
    {
        public static void Run()
        {
            Debug.Log("[HotUpdate] 热更代码执行成功！版本: v1.0");
        }
    }
}

在主工程（非 HotUpdate 文件夹）创建一个入口脚本 GameEntry.cs：

using UnityEngine;
using HybridCLR.RuntimeApi;

public class GameEntry : MonoBehaviour
{
    void Start()
    {
        // 先加载热更 DLL，再调用热更代码
        LoadAndRunHotUpdate();
    }

    async void LoadAndRunHotUpdate()
    {
        // 从 Addressables 加载热更 DLL
        var handle = Addressables.LoadAssetAsync<TextAsset>("HotUpdate.dll.bytes");
        await handle.Task;

        if (handle.Status == AsyncOperationStatus.Succeeded)
        {
            byte[] dllBytes = handle.Result.bytes;
            // 注入 HybridCLR 运行时
            RuntimeApi.LoadMetadataForAOTAssembly(dllBytes, HomologousImageMode.SuperSet);
            
            // 通过反射调用热更代码
            var type = System.Type.GetType("HotUpdate.HelloHotUpdate, HotUpdate");
            var method = type.GetMethod("Run");
            method.Invoke(null, null);

            Debug.Log("[Main] 热更 DLL 加载并执行完毕");
        }
        else
        {
            Debug.LogError($"[Main] 加载热更 DLL 失败: {handle.OperationException}");
        }
    }
}

⚠️ 注意：LoadMetadataForAOTAssembly 仅用于补充 AOT 元数据。实际热更 DLL 的执行由 HybridCLR 解释器自动接管，无需手动 LoadAssembly。上面示例为简化演示，实际项目中 DLL 加载逻辑见第四步。

---

📂 第四步：将热更 DLL 接入 Addressables

构建热更 DLL

1. 菜单栏 HybridCLR → Build → Build Assets
2. 选择目标平台（先用 Windows Standalone 验证）
3. 构建完成后，DLL 输出到 HybridCLRBuild/HotUpdateDlls/<Platform>/HotUpdate.dll

复制到 Addressables 可识别路径

# 创建资源目录
mkdir -p Assets/HotUpdateResources

# 复制 DLL 并重命名为 .bytes（Addressables 要求二进制资源用 .bytes 后缀）
cp HybridCLRBuild/HotUpdateDlls/StandaloneWindows64/HotUpdate.dll \
   Assets/HotUpdateResources/HotUpdate.dll.bytes

标记为 Addressable

1. 在 Project 窗口选中 HotUpdate.dll.bytes
2. Inspector 中勾选 Addressable ✅
3. 将 Addressable Name 改为 HotUpdate.dll.bytes（保持与代码中 LoadAssetAsync 的参数一致）
4. 将该资源分配到 Remote Group（非 Local），确保走远程更新通道

修改主工程入口代码（正式版）

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using HybridCLR.RuntimeApi;
using System.Reflection;

public class GameEntry : MonoBehaviour
{
    async void Start()
    {
        // 1. 初始化 Addressables
        await Addressables.InitializeAsync().Task;

        // 2. 检查并下载远程更新
        var checkHandle = Addressables.CheckForCatalogUpdates();
        await checkHandle.Task;
        if (checkHandle.Result.Count > 0)
        {
            var downloadHandle = Addressables.DownloadDependenciesAsync(checkHandle.Result);
            await downloadHandle.Task;
            Debug.Log($"[Main] 已更新 {checkHandle.Result.Count} 个目录");
        }

        // 3. 加载热更 DLL
        var dllHandle = Addressables.LoadAssetAsync<TextAsset>("HotUpdate.dll.bytes");
        await dllHandle.Task;

        if (dllHandle.Status == AsyncOperationStatus.Succeeded)
        {
            byte[] dllBytes = dllHandle.Result.bytes;

            // 补充 AOT 泛型元数据（防止泛型实例化失败）
            RuntimeApi.LoadMetadataForAOTAssembly(dllBytes, HomologousImageMode.SuperSet);

            // 加载程序集
            Assembly hotUpdateAssembly = Assembly.Load(dllBytes);

            // 调用热更入口
            var entryType = hotUpdateAssembly.GetType("HotUpdate.HelloHotUpdate");
            var runMethod = entryType.GetMethod("Run", BindingFlags.Public | BindingFlags.Static);
            runMethod.Invoke(null, null);

            Debug.Log("[Main] ✅ 热更流程完整执行成功");
        }
        else
        {
            Debug.LogError($"[Main] ❌ DLL 加载失败: {dllHandle.OperationException?.Message}");
        }
    }
}

---

▶️ 第五步：编辑器验证

使用 Addressables Play Mode Script

1. Window → Asset Management → Addressables → Profiles
2. 当前 Profile 切换为 Default
3. Window → Asset Management → Addressables → Settings
4. 找到 Play Mode Script → 选择 Use Existing Build (requires built groups)

构建 Addressables Content

1. Window → Asset Management → Addressables → Groups
2. 菜单 Build → New Build → Default Build Script
3. 等待构建完成

运行验证

1. 将 GameEntry 挂载到场景中的空 GameObject
2. 点击 Play
3. Console 应依次输出：

   [Main] ✅ 热更流程完整执行成功
   [HotUpdate] 热更代码执行成功！版本: v1.0

⚠️ **如果报错 “Unable to load assembly”**：确认 HybridCLR Settings 中已添加 HotUpdate，且重新执行了 HybridCLR → Installer。

---

🌐 第六步：真机远程更新流程

服务器准备

# 在服务器上创建资源目录
sudo mkdir -p /var/www/hotupdate
sudo chown admin:admin /var/www/hotupdate

# 将 Addressables 构建产物上传
# 本地路径: Library/com.unity.addressables/aa/<Platform>/
scp -r Library/com.unity.addressables/aa/StandaloneWindows64/* admin@server:/var/www/hotupdate/

Nginx 配置静态资源服务

location /hotupdate/ {
    alias /var/www/hotupdate/;
    add_header Cache-Control "no-cache";
    add_header Access-Control-Allow-Origin "*";
}

Addressables Remote Catalog 配置

1. Window → Asset Management → Addressables → Profiles
2. 编辑当前 Profile，修改 Remote.BuildPath 和 Remote.LoadPath：
   • Remote.BuildPath: ServerData/StandaloneWindows64
   • Remote.LoadPath: http://你的服务器IP/hotupdate/ServerData/StandaloneWindows64
3. 重新执行 Build → New Build → Default Build Script
4. 打包真机 Player，运行后会自动从远程拉取最新 DLL

---

❓ 常见问题速查

问题	原因	解决方案
LoadAssetAsync 返回 null	Addressable Name 不匹配	检查 Inspector 中的 Addressable Name 是否与代码参数完全一致
Assembly.Load 报 BadImageFormatException	DLL 未正确构建或被裁剪	重新执行 HybridCLR → Build → Build Assets
泛型方法调用报 MissingMethodException	AOT 元数据未补充	确认调用了 LoadMetadataForAOTAssembly
真机无法下载远程资源	LoadPath 配置错误或服务器未开放	用浏览器直接访问 Remote.LoadPath 验证可达性
编辑器正常但真机崩溃	IL2CPP 裁剪了热更引用的类型	HybridCLR Settings 中开启 Preserve Type Reference

---

🗺️ 系列导航

篇目	状态
① 概念篇	✅ 已发布
② 环境篇	✅ 已发布
③ Addressables 集成（本篇）	✅ 已发布
④ UI 实战篇	🔜 下一篇
⑤ 避坑与优化篇	📋 规划中

下一篇预告：使用 HybridCLR + Addressables 实现一个完整的热更 UI 系统，包括动态加载面板、资源异步管理、以及热更代码中操作 UGUI 的最佳实践。