【HybridCLR小白教程④】热更UI系统实战（UGUI动态加载）

🎯 本篇目标

在前三篇基础上，完成一个可在运行时热更新的 UI 系统：

1. 主工程提供 UI 框架基础设施（Canvas、EventSystem、面板管理器接口）
2. 热更代码实现具体面板逻辑（登录界面、公告弹窗）
3. 通过 Addressables 同时热更 UI Prefab 和 C# 脚本
4. 编辑器 + 真机验证完整流程

💡 核心原则：UI 框架在主工程（AOT），面板内容在热更代码。这样框架稳定不频繁更新，业务面板随时可热修。

---

🏗️ 第一步：主工程搭建 UI 框架

创建 UI 管理器接口

在 Assets/Scripts/Framework/ 下创建 IUIManager.cs（主工程 AOT 侧）：

using UnityEngine;
using System.Threading.Tasks;

namespace GameFramework.UI
{
    /// <summary>
    /// UI管理器接口 - 主工程定义，热更代码调用
    /// </summary>
    public interface IUIManager
    {
        Task<GameObject> OpenPanel(string panelName);
        void ClosePanel(string panelName);
        void CloseAllPanels();
    }
}

实现 UI 管理器

创建 UIManager.cs（主工程 AOT 侧）：

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace GameFramework.UI
{
    public class UIManager : MonoBehaviour, IUIManager
    {
        private Transform _panelRoot;
        private Dictionary<string, GameObject> _openedPanels = new();

        void Awake()
        {
            // 自动创建面板根节点
            var canvas = GetComponentInChildren<Canvas>();
            if (canvas == null)
            {
                var go = new GameObject("UICanvas");
                go.transform.SetParent(transform);
                var c = go.AddComponent<Canvas>();
                c.renderMode = RenderMode.ScreenSpaceOverlay;
                c.sortingOrder = 100;
                go.AddComponent<UnityEngine.UI.CanvasScaler>();
                go.AddComponent<UnityEngine.UI.GraphicRaycaster>();
                _panelRoot = go.transform;
            }
            else
            {
                _panelRoot = canvas.transform;
            }
        }

        public async Task<GameObject> OpenPanel(string panelName)
        {
            if (_openedPanels.TryGetValue(panelName, out var existing))
            {
                existing.SetActive(true);
                return existing;
            }

            var handle = Addressables.InstantiateAsync(panelName, _panelRoot);
            await handle.Task;

            if (handle.Status == AsyncOperationStatus.Succeeded)
            {
                var panel = handle.Result;
                panel.name = panelName;
                _openedPanels[panelName] = panel;
                Debug.Log($"[UIManager] ✅ Panel opened: {panelName}");
                return panel;
            }
            else
            {
                Debug.LogError($"[UIManager] ❌ Failed to open: {panelName}, {handle.OperationException?.Message}");
                return null;
            }
        }

        public void ClosePanel(string panelName)
        {
            if (_openedPanels.TryGetValue(panelName, out var panel))
            {
                Addressables.ReleaseInstance(panel);
                _openedPanels.Remove(panelName);
                Debug.Log($"[UIManager] Panel closed: {panelName}");
            }
        }

        public void CloseAllPanels()
        {
            foreach (var kvp in _openedPanels)
                Addressables.ReleaseInstance(kvp.Value);
            _openedPanels.Clear();
        }
    }
}

注册全局服务定位器

创建 GameServiceLocator.cs（主工程 AOT 侧）：

using GameFramework.UI;
using UnityEngine;

public static class GameServiceLocator
{
    private static IUIManager _uiManager;

    public static void Register(IUIManager uiManager) => _uiManager = uiManager;
    public static IUIManager UI => _uiManager;
}

---

🔥 第二步：热更代码实现面板逻辑

创建面板基类

在 Assets/HotUpdate/UI/ 下创建 HotUpdatePanelBase.cs：

using UnityEngine;
using UnityEngine.UI;

namespace HotUpdate.UI
{
    /// <summary>
    /// 热更面板基类 - 所有热更UI面板继承此类
    /// </summary>
    public abstract class HotUpdatePanelBase : MonoBehaviour
    {
        protected T Get<T>(string path) where T : Component
        {
            var t = transform.Find(path)?.GetComponent<T>();
            if (t == null)
                Debug.LogWarning($"[HotPanel] Component not found: {path} ({typeof(T).Name})");
            return t;
        }

        protected void BindClick(string buttonPath, UnityEngine.Events.UnityAction action)
        {
            var btn = Get<Button>(buttonPath);
            if (btn != null)
                btn.onClick.AddListener(action);
        }

        public virtual void OnOpen() { }
        public virtual void OnClose() { }
    }
}

实现登录面板

创建 LoginPanel.cs（热更代码）：

using UnityEngine;
using UnityEngine.UI;

namespace HotUpdate.UI
{
    public class LoginPanel : HotUpdatePanelBase
    {
        private Text _titleText;
        private InputField _usernameInput;
        private Button _loginButton;
        private Text _statusText;

        public override void OnOpen()
        {
            _titleText = Get<Text>("Title");
            _usernameInput = Get<InputField>("UsernameInput");
            _loginButton = Get<Button>("LoginButton");
            _statusText = Get<Text>("StatusText");

            if (_titleText != null)
                _titleText.text = "🎮 游戏登录 v2.0 (热更版本)";

            BindClick("LoginButton", OnLoginClick);
            Debug.Log("[LoginPanel] ✅ 热更登录面板已打开");
        }

        private void OnLoginClick()
        {
            string username = _usernameInput?.text ?? "Player";
            if (_statusText != null)
                _statusText.text = $"欢迎回来, {username}! (热更逻辑v2.0)";

            Debug.Log($"[LoginPanel] Login attempt: {username}");
        }

        public override void OnClose()
        {
            Debug.Log("[LoginPanel] Panel closed");
        }
    }
}

实现公告弹窗

创建 NoticePanel.cs（热更代码）：

using UnityEngine;
using UnityEngine.UI;

namespace HotUpdate.UI
{
    public class NoticePanel : HotUpdatePanelBase
    {
        public override void OnOpen()
        {
            var title = Get<Text>("Title");
            var content = Get<Text>("Content");
            
            if (title != null) title.text = "📢 热更公告";
            if (content != null) content.text = "这是一条通过热更新推送的公告内容。\n无需重新下载即可修改！";

            BindClick("CloseButton", () =>
            {
                GameServiceLocator.UI.ClosePanel("NoticePanel");
            });

            Debug.Log("[NoticePanel] ✅ 热更公告面板已打开");
        }
    }
}

---

🎨 第三步：创建 UI Prefab 并接入 Addressables

制作登录面板 Prefab

1. 在场景中创建 Canvas → Panel，命名为 LoginPanel
2. 添加子对象：Title(Text)、UsernameInput(InputField)、LoginButton(Button)、StatusText(Text)
3. 挂载 LoginPanel 脚本（来自 HotUpdate 程序集）
4. 拖入 Assets/HotUpdateResources/Prefabs/ 保存为 Prefab
5. 删除场景中的实例

制作公告面板 Prefab

同上步骤，创建 NoticePanel Prefab。

标记为 Addressable

1. 选中两个 Prefab → Inspector 勾选 Addressable ✅
2. Addressable Name 分别设为 LoginPanel 和 NoticePanel
3. 分配到 Remote Group

⚠️ 关键：Prefab 上挂载的脚本必须来自 HotUpdate 程序集，否则热更后无法替换逻辑。

---

🔗 第四步：热更入口串联 UI 流程

更新 Assets/HotUpdate/GameHotEntry.cs：

using UnityEngine;
using GameFramework.UI;
using HotUpdate.UI;

namespace HotUpdate
{
    /// <summary>
    /// 热更代码入口 - 由主工程在DLL加载完成后调用
    /// </summary>
    public static class GameHotEntry
    {
        public static async void Initialize()
        {
            Debug.Log("[HotEntry] 🚀 热更代码初始化开始");

            // 打开登录面板
            var loginPanel = await GameServiceLocator.UI.OpenPanel("LoginPanel");
            if (loginPanel != null)
            {
                var panelScript = loginPanel.GetComponent<LoginPanel>();
                panelScript?.OnOpen();
            }

            // 延迟2秒打开公告（模拟运营推送）
            await System.Threading.Tasks.Task.Delay(2000);
            var noticePanel = await GameServiceLocator.UI.OpenPanel("NoticePanel");
            if (noticePanel != null)
            {
                var panelScript = noticePanel.GetComponent<NoticePanel>();
                panelScript?.OnOpen();
            }

            Debug.Log("[HotEntry] ✅ 热更UI系统初始化完成");
        }
    }
}

主工程调用热更入口

更新主工程的 GameEntry.cs，在 DLL 加载完成后调用：

// 在 Assembly.Load(dllBytes) 之后追加：
var entryType = hotUpdateAssembly.GetType("HotUpdate.GameHotEntry");
var initMethod = entryType.GetMethod("Initialize", 
    System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static);
initMethod.Invoke(null, null);

---

▶️ 第五步：编辑器验证

1. 确保 Addressables Play Mode Script 设为 Use Existing Build
2. 执行 Addressables → Build → New Build
3. 执行 HybridCLR → Build → Build Assets
4. 将生成的 DLL 复制到 Assets/HotUpdateResources/ 并刷新 Addressables
5. 运行场景，Console 应输出：

   [HotEntry] 🚀 热更代码初始化开始
   [UIManager] ✅ Panel opened: LoginPanel
   [LoginPanel] ✅ 热更登录面板已打开
   [UIManager] ✅ Panel opened: NoticePanel
   [NoticePanel] ✅ 热更公告面板已打开
   [HotEntry] ✅ 热更UI系统初始化完成

---

🌐 第六步：真机热更验证

模拟热修流程

1. 修改 LoginPanel.cs 中的标题文字为 "🎮 紧急修复版 v2.1"
2. 重新执行 HybridCLR → Build → Build Assets
3. 复制新 DLL 到 Addressables Remote 构建目录
4. 执行 Addressables → Build → Update Previous Build
5. 上传更新后的 ServerData 到服务器 /var/www/hotupdate/
6. 真机重启游戏 → 自动拉取新 DLL → 登录面板显示新标题

💡 这就是热更新的核心价值：改一行文案，玩家下次启动自动生效，无需商店审核。

---

❓ 常见问题

问题	原因	解决
面板打开但脚本不执行	Prefab 挂载的不是 HotUpdate 程序集的脚本	检查脚本命名空间和 asmdef 引用
GetComponent 返回 null	热更 DLL 未加载就调用了 UI	确保 DLL 加载完成后再 OpenPanel
按钮点击无响应	BindClick 路径错误	用 Hierarchy 确认子对象路径完全匹配
热更后面板还是旧逻辑	DLL 未被正确替换	检查 Addressables Catalog 是否更新
跨程序集类型找不到	AOT 元数据缺失	LoadMetadataForAOTAssembly 补充

---

🗺️ 系列导航

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

下一篇预告：汇总 HybridCLR 上线前必踩的坑——AOT 泛型补充、代码裁剪防护、打包报错排查、性能分析、iOS 审核注意事项，帮你平稳投产。