Unity 结合 ILRuntime 打造高效热更新解决方案

1. 为什么我们需要热更新？从痛点说起

做Unity开发的朋友，尤其是做在线教育、工业仿真这类项目，肯定都遇到过这个头疼的问题：项目好不容易上线了，突然发现一个逻辑bug，或者产品经理提了个新需求要加个小功能。按照传统流程，你得改代码、重新打包、提交给各个应用商店审核，光是等苹果App Store审核可能就要好几天。用户那边呢，还得手动去更新应用，很多用户嫌麻烦就不更新了，导致线上永远跑着好几个不同的版本，维护起来简直是噩梦。

热更新，说白了，就是解决这个“发版慢、更新难”的终极方案。它允许你在不重新发布客户端安装包（APK/IPA）的情况下，动态地更新游戏或应用里的业务逻辑、UI界面甚至是一些资源。想象一下，你的App就像一个可以随时更换“内脏”的机器人，外壳（客户端主体）不变，但里面的程序和行为可以随时升级，用户打开App就自动生效，体验丝滑无缝。

在Unity生态里，实现C#脚本热更新的主流技术方案有好几种，比如早期的Lua（通过xLua、ToLua等）、现代的HybridCLR（原huatuo），以及我们今天要深入聊的ILRuntime。我这些年经手过不少项目，从轻量级的手机游戏到复杂的工业数字孪生系统，都实践过这些方案。实话实说，没有哪个方案是完美的银弹，但ILRuntime在平衡性上做得非常出色——它性能不错，对IL2CPP的支持成熟稳定，学习曲线相对平缓，特别适合那些以C#为主要开发语言、又迫切需要热更能力的团队。

2. 初识ILRuntime：它到底是什么，怎么工作的？

你可能听过ILRuntime，但感觉它有点神秘。别担心，我用最直白的话给你解释。ILRuntime本质上是一个运行在Unity环境中的.NET中间语言（IL）解释器。我们都知道，C#代码会被编译成一种叫IL的中间代码，然后.NET运行时（比如Mono或者IL2CPP）再把IL编译或解释成机器码去执行。

ILRuntime干的就是这个“解释执行”的活儿。它自己实现了一套虚拟的执行环境（AppDomain），可以读取并运行由C#编译出来的DLL文件中的IL代码。这意味着什么呢？意味着你可以把需要经常变动的业务逻辑（比如某个教学模块的算法、某个仿真设备的控制流程）单独写在一个C#项目里，编译成DLL。主工程（Unity项目）在启动时，动态加载这个DLL文件，并交给ILRuntime去执行里面的代码。当你要更新逻辑时，只需要替换这个DLL文件，用户重启或重新进入某个模块时，新逻辑就生效了。

和直接使用Lua相比，ILRuntime的最大优势是开发体验无缝衔接。你的热更代码依然是用C#写的，可以用你熟悉的Visual Studio或Rider，享受强类型检查、IDE智能提示、重构工具等所有现代C#开发的好处。团队不需要再去学习一门新的脚本语言（比如Lua），降低了学习和维护成本。当然，它也不是没有代价，毕竟多了一层解释执行，性能上会比原生C#慢一些，但经过良好的优化，在大多数业务逻辑场景下是完全够用的。

3. 动手搭建：从零开始构建你的第一个热更Demo

光说不练假把式，咱们直接上手，用最短的路径跑通一个ILRuntime的热更流程。这个过程我会把每一步都拆开，确保你跟着做一定能成功。

3.1 环境与项目准备

首先，你需要准备好ILRuntime的运行库。最直接的方式是从GitHub上克隆官方仓库（Ourpalm/ILRuntime），或者直接在Asset Store搜索ILRuntime并导入。我建议新手直接用Asset Store版本，省去一些配置麻烦。导入后，你的Assets目录下会有一个ILRuntime文件夹，里面包含了运行所需的所有核心代码。

接下来，我们要建立清晰的项目结构，这是保持工程整洁的关键。我建议你这样组织：

YourUnityProject/
├── Assets/
│   ├── ILRuntime/           # 导入的ILRuntime运行库
│   ├── Scripts/
│   │   ├── ILRuntimeLoader.cs # 主工程加载器
│   │   └── GameManager.cs     # 主工程逻辑示例
│   └── StreamingAssets/     # 存放热更DLL的目录
└── HotFixProject/          # （独立文件夹）热更代码的C#类库项目

注意，HotFixProject是一个完全独立的Visual Studio C#类库项目，不要把它放在Unity的Assets目录里。这是为了严格区分“主工程代码”和“热更代码”。主工程代码打包后就不能动了，而热更代码则是我们后期可以随意替换的。

3.2 创建并编译热更DLL

打开Visual Studio，新建一个“类库（.NET Standard 2.0）”项目，名字就叫HotFixProject。为什么是.NET Standard 2.0？因为这是Unity的IL2CPP和Mono后端都广泛支持的一个标准版本，兼容性最好。

在这个项目里，我们写一个最简单的热更逻辑。首先，你需要引用UnityEngine相关的DLL，以便在热更代码里使用Debug.Log、GameObject这些API。这些DLL通常可以在你的Unity安装目录下的Editor\Data\Managed文件夹里找到（比如UnityEngine.dll， UnityEngine.CoreModule.dll）。把它们添加到项目的引用中。

然后，创建一个测试类：

using UnityEngine;

namespace HotFix
{
    public class HelloILRuntime
    {
        public static void Start()
        {
            Debug.Log("[热更代码] 你好，世界！这条消息来自热更DLL！");
            // 尝试调用主工程的方法
            if (MainProjectBridge.Instance != null)
            {
                MainProjectBridge.Instance.ShowMessage("热更代码调用成功！");
            }
        }

        public static int Add(int a, int b)
        {
            return a + b;
        }
    }
}

写完代码后，编译这个项目。你会在输出目录（通常是bin\Debug\netstandard2.0\）下得到编译产物：HotFixProject.dll（就是我们需要的热更DLL）以及可能有的HotFixProject.pdb（符号文件，调试用）。把这个HotFixProject.dll复制到Unity项目的Assets/StreamingAssets/目录下。记住，每次修改热更代码后，都需要重新编译并复制这个DLL文件。

3.3 在Unity中加载与执行

现在回到Unity，我们需要一个加载器脚本来读取并运行这个DLL。在Assets/Scripts/下创建ILRuntimeLoader.cs。

using System;
using System.IO;
using UnityEngine;
using ILRuntime.Runtime.Enviorment;
using ILRuntime.Runtime.Generated;

public class ILRuntimeLoader : MonoBehaviour
{
    private AppDomain _appDomain; // ILRuntime的运行时环境

    IEnumerator Start()
    {
        // 初始化ILRuntime AppDomain
        _appDomain = new AppDomain();

        // 1. 加载热更DLL
        string dllPath = Path.Combine(Application.streamingAssetsPath, "HotFixProject.dll");
        byte[] dllBytes;

        // 注意：不同平台下StreamingAssets的读取方式不同
        // 在Editor和部分平台可以直接用File.ReadAllBytes，但在Android上，StreamingAssets在压缩包里，需要用UnityWebRequest
#if UNITY_ANDROID && !UNITY_EDITOR
        UnityEngine.Networking.UnityWebRequest www = UnityEngine.Networking.UnityWebRequest.Get(dllPath);
        yield return www.SendWebRequest();
        dllBytes = www.downloadHandler.data;
#else
        dllBytes = File.ReadAllBytes(dllPath);
#endif

        using (MemoryStream fs = new MemoryStream(dllBytes))
        {
            _appDomain.LoadAssembly(fs);
            // 如果有PDB文件，可以一起加载以便调试
            // string pdbPath = Path.ChangeExtension(dllPath, ".pdb");
            // if(File.Exists(pdbPath)) {...}
        }

        // 2. 注册适配器和委托（非常重要！）
        InitializeILRuntime();

        // 3. 调用热更DLL里的方法
        InvokeHotfixMethod();
    }

    void InitializeILRuntime()
    {
        // 这里注册跨域继承适配器，比如让热更里的类可以继承MonoBehaviour
        _appDomain.RegisterCrossBindingAdaptor(new MonoBehaviourAdapter());
        _appDomain.RegisterCrossBindingAdaptor(new CoroutineAdapter());

        // 注册常用的委托类型，否则在热更代码里使用Action、Func可能会报错
        _appDomain.DelegateManager.RegisterDelegateConvertor<UnityEngine.Events.UnityAction>((act) =>
        {
            return new UnityEngine.Events.UnityAction(() =>
            {
                ((Action)act)();
            });
        });

        // CLR绑定：提前生成主工程类型的绑定代码，提升性能
        // 这一步比较复杂，我们后面会详细讲，初期可以先用反射模式
        // ILRuntime.Runtime.Generated.CLRBindings.Initialize(_appDomain);
    }

    void InvokeHotfixMethod()
    {
        try
        {
            // 调用热更DLL里HelloILRuntime类的Start静态方法
            _appDomain.Invoke("HotFix.HelloILRuntime", "Start", null, null);

            // 调用带返回值的方法
            int result = (int)_appDomain.Invoke("HotFix.HelloILRuntime", "Add", null, 10, 20);
            Debug.Log($"热更方法计算10+20的结果是：{result}");
        }
        catch (Exception e)
        {
            Debug.LogError($"调用热更方法失败: {e}");
        }
    }
}

把这个脚本挂到一个空的GameObject上，运行Unity。如果一切顺利，你会在Console里看到来自热更DLL打印的日志，以及计算的结果。恭喜你，你已经完成了热更新最核心的“加载-执行”流程！

4. 打通桥梁：主工程与热更代码如何互相调用？

刚才的Demo只是热更代码单向执行。真实项目里，主工程（比如管理UI框架、网络模块）和热更代码（具体业务逻辑）必须频繁交互。这是ILRuntime入门后第一个要啃的硬骨头，也是很多新手卡住的地方。

4.1 主工程公开接口给热更代码调用

热更代码不能直接引用主工程的类（因为编译时主工程DLL不在它的引用列表里）。我们需要通过一种间接的方式。通常的做法是，在主工程定义一个“桥接”类或接口，然后将这个类的实例“注册”到ILRuntime的AppDomain中。

首先，在主工程定义一个接口和它的实现：

// 在主工程中
public interface IMainService
{
    void ShowUI(string uiName);
    void PlaySound(string soundId);
    int GetPlayerLevel();
}

public class MainService : IMainService
{
    public static MainService Instance = new MainService();

    public void ShowUI(string uiName) { /* 实际打开UI的逻辑 */ }
    public void PlaySound(string soundId) { /* 播放音效 */ }
    public int GetPlayerLevel() { return 1; }
}

然后，在ILRuntimeLoader的InitializeILRuntime方法中，将这个实例注册给热更域：

void InitializeILRuntime()
{
    // ... 其他注册代码 ...

    // 将主工程的实例注册到热更域，热更代码可以通过这个“服务”调用主工程功能
    _appDomain.RegisterService<IMainService>(MainService.Instance);
}

在热更代码中，你就可以这样获取并使用这个服务：

// 在热更DLL中
public class GameLogic
{
    public void StartGame()
    {
        // 通过AppDomain获取主工程注册的服务
        var mainService = ILRuntimeService.GetService<IMainService>();
        mainService.ShowUI("MainMenu");
        int level = mainService.GetPlayerLevel();
        Debug.Log($"玩家当前等级（来自主工程）: {level}");
    }
}

这里的ILRuntimeService是一个你需要自己在热更项目中定义的辅助类，它内部通过ILRuntime的API去获取注册的服务实例。这需要一点反射技巧，但封装好后对业务代码是透明的。

4.2 热更代码公开接口给主工程调用（回调/事件）

反过来，主工程也可能需要调用热更代码里的方法，比如一个热更新的教学模块完成后，通知主工程进入下一关。这通常通过委托（Delegate）或事件（Event）来实现。

在热更代码中定义委托类型和方法：

// 在热更DLL中
namespace HotFix
{
    // 定义在热更中的委托
    public delegate void OnLessonFinishedCallback(string lessonId, bool success);

    public class LessonManager
    {
        public static OnLessonFinishedCallback OnLessonFinished;

        public static void CompleteLesson(string id)
        {
            // ... 课程完成逻辑 ...
            // 触发回调，通知主工程
            OnLessonFinished?.Invoke(id, true);
        }
    }
}

在主工程中，你需要先注册这个委托类型，然后才能将主工程的方法绑定上去：

// 在主工程的ILRuntimeLoader中
void InitializeILRuntime()
{
    // ... 其他注册代码 ...

    // 注册热更代码中的委托类型
    _appDomain.DelegateManager.RegisterDelegateConvertor<HotFix.OnLessonFinishedCallback>((action) =>
    {
        // 这里将ILRuntime内部的委托转换成一个实际的C#委托
        return new HotFix.OnLessonFinishedCallback((lessonId, success) =>
        {
            // 这个lambda表达式就是主工程实际处理回调的地方
            Debug.Log($"收到热更回调：课程{lessonId}完成，状态{success}");
            // 可以在这里更新主工程UI、保存进度等
        });
    });

    // 然后，需要调用热更代码里的某个初始化方法，将上面这个委托实例设置过去
    // 这通常需要在热更代码里暴露一个SetupCallbacks方法
}

这个过程稍显繁琐，但它是实现双向调用的基石。我建议你把常用的交互模式（如服务注册、回调绑定）封装成一套简单的工具类，这样业务开发人员就不用每次都关心底层细节了。

5. 性能优化实战：让热更代码跑得更快

用了ILRuntime，大家最关心的就是性能。解释执行毕竟有开销，但通过一系列优化手段，我们可以把开销降到最低，满足绝大多数应用场景。

5.1 CLR绑定：告别反射，性能飞跃

默认情况下，ILRuntime通过反射机制来访问主工程的类型和方法，这是性能的主要瓶颈。CLR绑定是解决这个问题的杀手锏。它的原理是：通过一个代码生成工具，提前为你的主工程中需要被热更代码频繁访问的类、方法、字段生成静态的“绑定代码”。运行时，热更代码直接调用这些生成的绑定方法，避免了昂贵的反射操作，性能可以提升几十甚至上百倍。

如何生成CLR绑定代码呢？ILRuntime官方提供了一个编辑器工具。大致步骤如下：

1. 在你的Unity编辑器里，通常会有一个ILRuntime/Generate CLR Binding Code的菜单项。
2. 点击后，它会分析你的项目，并让你选择哪些类需要生成绑定。你应该优先选择那些会被热更代码高频调用的类，比如GameManager、UIManager、NetworkManager等。
3. 点击生成，会在项目里（通常是Assets/ILRuntime/Generated目录）创建一堆CLRBindingxxx.cs文件。
4. 最后，记得在ILRuntimeLoader的初始化代码里调用生成的绑定初始化方法：CLRBindings.Initialize(_appDomain);。

做完CLR绑定后，你会发现热更代码调用主工程API的速度有了质的提升。这是上线项目必须做的一步。

5.2 减少跨域调用

每一次热更代码与主工程代码的交互（比如访问一个主工程的属性、调用一个方法）都是一次“跨域调用”，都有开销。一个重要的优化原则是：尽量减少跨域调用的次数和频率。

• 批处理数据：不要在主工程和热更代码之间一个字段一个字段地传递。尽量设计成数据对象（Data Object）或结构体（struct）来一次性传递。
• 缓存引用：如果热更代码需要频繁访问某个主工程对象（比如玩家数据），不要每次都通过服务去获取。可以在热更模块初始化时获取一次并缓存起来。
• 逻辑下沉：考虑将一些紧密相关的逻辑尽量放在同一侧。如果一段逻辑既涉及主工程资源加载，又涉及热更业务计算，频繁交互会很慢。可以评估是否能把整个功能模块都做到热更DLL里，或者把相关计算逻辑移到主工程。

5.3 值类型与泛型的注意事项

ILRuntime对C#的某些高级特性支持需要特别注意，处理不好会影响性能和稳定性。

• 值类型（struct）：默认情况下，热更代码中的值类型在与主工程交互时，可能会发生装箱（boxing）拆箱（unboxing）操作，带来额外开销。对于简单的值类型（如Vector2, Vector3），ILRuntime有内置优化。但对于自定义的复杂结构体，性能可能不佳，需要谨慎使用。
• 泛型：ILRuntime支持泛型，但热更代码中的泛型类/方法如果使用主工程的类型作为泛型参数（比如List<MainProjectType>），需要提前通过CLR绑定生成对应的实例化类型，否则会回退到反射，性能很差。在绑定生成列表中，记得把常用的泛型实例（如List<GameObject>, Dictionary<string, Sprite>）也勾选上。

6. 跨平台兼容性：搞定IL2CPP与Mono

Unity有两个脚本后端：Mono和IL2CPP。IL2CPP因为更好的性能和安全性，尤其是对于需要发布到iOS平台的项目，几乎是必选。ILRuntime对两者的支持都很好，但配置上有些差异。

在Mono后端下，事情比较简单。因为Mono本身就是一个JIT（即时编译）环境，ILRuntime可以与其较好地共存。你上面Demo的代码在Mono下通常能直接运行。

在IL2CPP后端下，情况复杂一些。IL2CPP是一个AOT（预先编译）编译器，它会把所有IL代码在编译时就转换成C++代码。而ILRuntime是动态加载IL并解释执行的，这与AOT的理念有冲突。为了解决这个问题，你需要告诉IL2CPP：“请不要优化或裁剪掉ILRuntime运行时需要的一些特定类型和方法”。

具体操作是在你的Unity项目中创建一个名为link.xml的文件，放在Assets目录下。这个文件用于指导IL2CPP的代码裁剪（Code Stripping）行为。

<?xml version="1.0" encoding="utf-8"?>
<linker>
  <assembly fullname="ILRuntime" preserve="all"/>
  <assembly fullname="ILRuntime.Test" preserve="all"/>
  <!-- 保留你的热更项目中可能会用到的系统程序集 -->
  <assembly fullname="mscorlib">
    <type fullname="System.Action" preserve="all"/>
    <type fullname="System.Func" preserve="all"/>
    <!-- 保留更多可能用到的类型... -->
  </assembly>
  <assembly fullname="System">
    <type fullname="System.Collections.Generic.Dictionary" preserve="all"/>
  </assembly>
  <!-- 保留你自己的主工程程序集中，需要被热更代码反射访问的类型 -->
  <assembly fullname="Assembly-CSharp">
    <type fullname="YourNamespace.GameManager" preserve="all"/>
    <type fullname="YourNamespace.IMainService" preserve="all"/>
  </assembly>
</linker>

这个文件的作用是“保留”指定的程序集和类型，防止被IL2CPP裁剪掉。刚开始配置时，如果你不确定哪些类型需要保留，可以先将整个程序集preserve="all"，等稳定后再逐步细化，以减小最终包体。

另一个常见问题是，在IL2CPP下，反射的使用受到更多限制。ILRuntime内部大量使用反射，所以link.xml的配置至关重要。如果配置不当，在打包后运行可能会遇到MethodNotFoundException或TypeNotFoundException。我的经验是，每当在热更代码中添加了新的与主工程交互的方式（尤其是通过反射或接口调用的），最好都更新一下link.xml文件，并重新进行真机测试。

7. 工程化实践：构建稳健的热更新框架

当Demo跑通，基本交互和性能问题都解决后，我们要考虑如何把它用到真实的、可能非常复杂的大型项目中。这就需要一些工程化的设计。

7.1 模块化与分层设计

不要把所有的热更逻辑都塞进一个巨大的DLL里。应该根据功能模块进行拆分，比如Logic.dll（核心玩法）、UI.dll（界面逻辑）、Config.dll（配置表读取）等。这样做的好处一是更新灵活，可以只更新某个模块；二是加载时可以按需加载，减少内存占用和启动时间。

你需要设计一个简单的热更模块管理器（HotFixModuleManager），负责记录各个模块的版本、下载地址、依赖关系，并按顺序加载和初始化它们。

7.2 与AssetBundle资源热更结合

真正的热更新不仅仅是代码，还包括图片、预制体、配置表等资源。ILRuntime负责代码热更，而Unity的AssetBundle系统负责资源热更。两者需要协同工作。

一个典型的流程是：

1. 启动游戏，主工程检查服务器上的热更清单（包含代码DLL和资源AssetBundle的版本信息）。
2. 如果需要更新代码，则下载新的DLL文件到本地可读写目录（如Application.persistentDataPath）。
3. 如果需要更新资源，则下载新的AssetBundle文件。
4. 用ILRuntime加载新的DLL。
5. 新的热更代码中，会包含对新版本资源AssetBundle的加载逻辑。热更代码通过主工程提供的资源加载接口（见4.1节），去加载新的AssetBundle并实例化其中的资源。

这样，就实现了代码和资源的联动热更。比如你更新了一个教学关卡的逻辑（代码DLL），同时这个关卡用到的新的3D模型和UI贴图（AssetBundle）也一起被更新了。

7.3 版本管理与回滚机制

热更新给了我们快速迭代的能力，但也带来了风险：万一新版本DLL有严重bug怎么办？必须要有回滚机制。

• 版本号管理：为每个热更DLL和AssetBundle定义清晰的版本号（如1.0.2.15）。
• 本地备份：在更新新版本前，将当前正在运行的旧版本DLL和关键资源备份到另一个目录。
• 快速回滚：如果检测到新版本加载后崩溃或关键功能异常（可以通过心跳、异常捕获机制判断），则主动触发回滚流程：关闭当前AppDomain，重新加载备份的旧版本DLL和资源，并提示用户更新失败。同时将错误信息上报服务器，方便排查。

7.4 调试与日志

调试热更代码比调试主工程代码要麻烦一些，但并非不可为。

• 日志系统：建立一个统一的日志系统，无论是主工程还是热更代码，都通过这个系统打印日志。这个系统可以附加文件输出、网络上报等功能，方便在真机上排查问题。
• IDE调试：ILRuntime支持与Visual Studio或Visual Studio Code进行调试连接。你需要开启ILRuntime的调试服务器，并在IDE中附加到进程。配置过程有些步骤，但一旦配好，就可以像调试普通C#代码一样给热更代码打断点、查看变量，效率提升巨大。对于复杂bug的排查，这几乎是必备技能。
• 性能剖析：Unity Profiler可以监控到ILRuntime内部的函数调用开销。关注AppDomain.Invoke和跨域调用的耗时，找到性能热点，针对性地进行优化（比如增加CLR绑定、减少调用次数）。

在我经历的一个工业仿真项目中，我们就是通过模块化设计，将不同的设备仿真逻辑做到不同的热更DLL里。当客户需要更新某台机床的模拟程序时，我们只需要更新一个很小的DLL文件（可能就几十KB），用户完全无感。同时，我们建立了完善的版本管理和监控后台，任何一次热更的成功率、性能数据都一目了然，确保了线上系统的稳定。这套框架运行了两年多，经历了上百次热更新，真正做到了“快速迭代，稳定交付”。