我到现在都记得第一次线上事故的场景一个已经过审上架的手游运营活动发奖励的数值公式少取了一次随机数玩家领到的奖励高了两倍。服务端立刻封住漏洞但已经安装的客户端代码是死的发新版要走渠道审核少则一天多则一周那几天项目组每个人脸上都写着焦虑。那次之后我们整个团队把“代码热更新”从“以后再说”提到了“下周必须验证”的优先级。最后选型、验证、接入的方案就是今天这篇要聊的 Unity HybridCLR 热更新。如果只用一句话介绍HybridCLR 是一个基于 IL2CPP 的 C# 热更新方案它能让你的 Unity 项目在不重新打包上架、玩家不重新下载安装包的情况下通过加载一段新的 C# 程序集来更新游戏逻辑。这篇文章是我自己从零把一个 Demo 工程接入 HybridCLR再逐步推进到真实项目的完整记录。重点不是重复官方文档而是告诉你接入顺序、依赖方向、AOT 泛型问题这些文档里不容易一次讲透的东西以及我踩过的坑长什么样。如果你是想评估热更新方案的技术负责人、正在给老项目接热更的 Unity 客户端同学或者刚被分配要验证 HybridCLR 可行性的新手这篇应该能帮你省下不少试错时间。读完你应该能知道它和 Lua 热更、和 IDE 里的热重载到底什么关系接入前工程要做什么体检真机上跑通一个最小热更工程需要哪几步以及第一轮真机崩溃该怎么查。1. 为什么是 HybridCLR而不是 Lua 或者热重载1.1 IL2CPP 把代码焊死在哪里要理解 HybridCLR 的价值先得知道 Unity 的 IL2CPP 到底做了什么。在没有 IL2CPP 的 Mono 时代C# 代码会被编译成 IL运行时由 Mono 虚拟机解释或 JIT 编译执行。那个年代想在 iOS 上做热更新很麻烦因为苹果明确禁止应用在自己的沙盒里动态生成可执行代码JIT 这条路在 iOS 上基本是堵死的。IL2CPP 是把 C# 先编译成 IL再在构建阶段把 IL 转成 C最后随原生工程一起编译成目标平台的机器码。好处是启动快、性能好、代码不容易被直接反编译成原始 C#坏处也藏在这里所有 C# 逻辑都在编译期被翻译并“焊死”进了原生二进制运行时已经没有一套能把新 IL 编译成机器码的机制了。这就好比你把菜谱都刻成了石碑读者只能照着石碑做菜现在你拿到一张新菜谱却没有火源也没有翻译想按新菜谱做菜根本无从下手。HybridCLR 做的是在 IL2CPP 旁边补了一个“解释执行器”让新拿到的 C# 程序集也就是热更 dll里的 IL 字节码不经过 JIT 也能被逐条解释执行。1.2 它和 xLua、ILRuntime 的本质差异很多团队第一次聊热更新听到的往往是 xLua、tolua或者纯 C# 的 ILRuntime。这里我直接按实际感受做个比较。Lua 方案的核心是“换语言”业务逻辑不写在 C# 里而是写 Lua运行时由 C# 侧的虚拟机解释执行。好处是生态成熟、很多老项目都在用代价是整个项目的核心玩法可能要从 C# 平移成 Lua维护一套双语言逻辑团队里每个人都要会 Lua出问题时要跨语言查堆栈代码补全和重构也不够舒服。ILRuntime 是纯 C# 的解释器方案不需要换语言但它和 Unity 的 AOT 世界之间隔了一层自己的运行时对某些 C# 特性的支持以及对 Unity 引擎调用、泛型、值类型结构的处理需要开发者额外注意。性能和兼容性一直在进步但遇到冷门边界总有“为什么这里不行”的疑惑。HybridCLR 选择的是另一条路线尽可能贴近原生 CLR 的实现方式在 IL2CPP 的 AOT 基础上加一个解释器模块并且用“补充元数据”的方式解决 AOT 泛型缺失的经典问题。用下来最直观的感受是它不是让你把逻辑翻译成另一种语言而是让热更 dll 里的 C# 代码自己跑起来和主工程的 C# 代码写法差别不大。对比项Lua 系方案ILRuntimeHybridCLR业务语言Lua C#C#C#与 IL2CPP 关系独立虚拟机独立解释器基于 IL2CPP 补充解释能力学习成本需要掌握 Lua较低但边界概念多较低重点是理解 AOT 与热更分界泛型等边界问题不受 IL2CPP 泛型影响有自己的处理通过补充元数据解决大多数社区活跃度高但偏向旧项目中高近几年增长很快需要客观说的是HybridCLR 本质上是修改了 Unity 的 IL2CPP 构建链路Unity 版本升级、IL2CPP 内部实现调整都有可能影响它。所以它不是一个“装一次永远不用管”的方案每次 Unity 升级或 HybridCLR 升级都要做回归验证。这点后面章节会细说。1.3 先理清“热更新”和“热重载”不是一回事热搜词里出现了不少和热更新相关的词比如 Flutter 热重载、IDEA 修改代码热更新、Nacos 配置热更新。这些词经常被混在一起但它们解决的问题完全不同。Flutter 的热重载本质是开发期工具改完代码按一下 R开发进程把新的 widget 树推给正在运行的调试 App帮开发者快速看 UI 效果。它不面向线上玩家代码改动只在开发环境里生效。IDEA 里修改 Java 代码后的热更新是让本地开发服务器不用重启就能加载新类属于开发效率工具的范围。Nacos 配置热更新更新的是配置项不是程序逻辑本身。而 Unity 项目里说的“代码热更新”指的是已经安装到玩家手机上的 App在不发新包的前提下从服务器拉取新的 C# 程序集并在本地执行新逻辑。这是玩家可见的能力直接关系到线上事故的处理速度和上面那些开发期工具完全不是一个维度。所以有些同学问“我项目里用 IDE 热重载很顺是不是就不用 HybridCLR 了”答案显然是否定的。2. 接入前先给工程“体检”程序集、依赖方向、泛型用法2.1 依赖方向热更代码能引用什么不能引用什么接入 HybridCLR 最容易犯的错是直接拿一个已经写了两三年的老工程把所有代码都扫进热更程序集然后开始打包。正确的第一步是给工程划分程序集边界。Unity 项目里用 asmdef 把代码分成多个程序集主工程里有一套专门给热更代码用的接口和公共代码热更代码所在的程序集可以引用主工程的公共程序集但主工程的 AOT 代码绝对不能反过来引用热更程序集里的类型。一旦主工程静态引用了热更代码里的类打 IL2CPP 包时就会把热更代码一起编进去后续想替换逻辑就会非常别扭。我在项目里习惯的分层是这样的AOT 主程序集启动流程、SDK 对接、资源管理、渲染相关、游戏的底层框架。AOT 公共接口层纯接口和 DTO 定义比如战斗结算接口、活动模板接口供热更代码实现或调用。热更程序集赛季玩法、活动界面、数值表现、任务系统这类需要频繁调整的逻辑。依赖方向是热更层可以引用 AOT 公共接口层AOT 公共接口层不能引用热更层。因为热更层是运行时才被加载的AOT 侧的代码在编译期根本不知道它的存在两者之间只能靠接口或反射沟通。2.2 重点检查一遍泛型使用习惯体检时另一个重点是泛型。C# 泛型在 AOT 编译下有个天然矛盾IL2CPP 编译器在打包时只会为主工程代码里“显式出现过的泛型实例化”生成机器码。如果热更代码运行时突然出现一个 AOT 模块里从未实例化过的泛型组合比如DictionaryMyStruct, intIL2CPP 那边并没有对应的目标代码运行时就会报类似AOT generic method can not be instantiated的错误。HybridCLR 的解法是“补充元数据 解释器兜底”。打包时项目会带上 AOT 必需 dll比如 mscorlib、System、UnityEngine.CoreModule 这些的元数据运行时先加载这些元数据让解释器能够自己解析泛型方法的 IL 并执行而不是必须依赖 IL2CPP 现成的机器码。这并不代表你可以完全无视泛型。我建议在接入前把项目里“值类型 泛型容器混用”的地方扫一遍。比如大量使用Listint、Dictionaryint, MyEnum、Dictionarylong, MyStruct尤其是这些结构体是活动逻辑里临时定义的时候要格外留意。这里不是说不能用而是你要意识到这类代码会触发 AOT 泛型补充机制线上报错后排查成本会高一些。2.3 确认版本兼容与目标平台体检还包括两个基础问题项目用的 Unity 版本以及 Scripting Backend 是否已经是 IL2CPP。HybridCLR 只支持 IL2CPPMono 后端不在讨论范围内。Android 项目由于现在 Google Play 和国内渠道对 Target API Level 的要求越来越高很多项目把target API level提到了 33、34、35这个过程中只要正常使用 IL2CPP 并勾选 ARM64不会和 HybridCLR 产生直接冲突。但如果是很老的项目一直跑在 ARMv7 或 Mono 上最好先把构建链路切干净再谈热更。Unity 版本建议尽量用 LTS比如 2021.3 LTS、2022.3 LTS 或官方文档当前明确支持的版本。HybridCLR 的发布节奏通常能跟上主流 LTS用非 LTS 版本容易遭遇兼容性盲区。安装时下载的是focus-creative-games/hybridclr_unity这份 Unity 侧工程代码版本要和项目 Unity 版本匹配别随手拉最新版就往老项目里塞。3. 真机跑通全流程一个最小可热更工程的搭建记录3.1 安装包和 Installer 到底做了什么接入时首先通过 Unity Package Manager 用 Git URL 把 HybridCLR 的 Unity 包加到工程里。拉取成功后菜单栏会出现 HybridCLR 相关的入口。接下来执行的是 HybridCLR - Installer这一步会往工程里写一些必要的代码更关键的是它会修改本地的 IL2CPP把解释器相关模块合入 il2cpp 的构建链。也就是说它不只是往 Assets 里加几个脚本还动到了 Unity 编辑器安装目录下的 il2cpp 相关文件。这里有两个容易踩的点。第一Installer 执行时如果 Unity 正在占用相关文件或者杀毒软件拦截了对安装目录的修改安装可能“假成功”。我遇到过安装后 Generate 时各种诡异报错重装一次 HybridCLR 就好了。建议执行完 Installer 后先做一次简单的生成操作验证而不是直接开始打大包。第二升级 Unity 小版本后最好重新执行 Installer。IL2CPP 内部文件结构会随版本变化旧的补丁不一定还能用。我们项目从 Unity 2021.3.16 升到 2021.3.31 时因为漏了这一步打出来的包初始化阶段直接崩溃排查了半天才发现是 installer 没重跑。3.2 创建热更程序集并在 Settings 里登记HybridCLR 需要知道哪些程序集要被当作热更程序集处理。官方推荐用 asmdef 组织但不是把文件夹命名为 HotUpdate 就行而是在工程里建一个真正的 Assembly Definition。我的做法是在 Assets 下建两个目录Assets/Scripts/Main主工程逻辑里面放Main.asmdef。Assets/Scripts/HotUpdate热更逻辑里面放HotUpdate.asmdef。由于 HotUpdate 需要引用 Main 里定义的类型和接口在HotUpdate.asmdef的 Assembly Definition References 里加上 Main反之 Main 里不要引用 HotUpdate。这样主工程干净热更程序集可以随意引用它依赖的 AOT 库。创建好 asmdef 后打开菜单HybridCLR - Settings把 HotUpdate 加进热更新程序集列表。Install 时官方脚本会自动生成一套默认配置里面通常已经预设了 compile 用的 AOT 程序集列表和补充元数据列表。新工程用默认配置其实就能跑通不需要一开始就手动维护一堆列表。3.3 初始化的核心代码补充元数据再加载热更程序集接入代码最核心的只有两步先补充 AOT 元数据再Assembly.Load热更 dll。补充元数据这一步是用HybridCLR.RuntimeApi.LoadMetadataForAOTAssembly把 AOT dll 的元数据喂给解释器。注意每个 dll 要单独调用一次不能把多个 dll 拼成一个 byte 数组一次性传进去。这里直接放一份可运行的初始化思路using System; using System.Reflection; using HybridCLR; using UnityEngine; public static class HotfixBootstrap { // 假设这些 dll 都已经被打进同一个 AssetBundle // 并且以 TextAsset 形式加载 private static readonly string[] AotDllNames { mscorlib.dll, System.dll, System.Core.dll, UnityEngine.CoreModule.dll, Main.dll, }; private const string HotUpdateDllName HotUpdate.dll; public static void Start() { try { LoadAotMetadata(); LoadHotUpdateAssembly(); } catch (Exception e) { Debug.LogError($[Hotfix] 热更启动失败走 AOT 兜底逻辑. {e}); FallbackToAOT(); } } private static void LoadAotMetadata() { AssetBundle ab AssetBundle.LoadFromFile(GetBundlePath()); foreach (string dllName in AotDllNames) { TextAsset ta ab.LoadAssetTextAsset(dllName); if (ta null) { Debug.LogError($[Hotfix] 缺少 AOT 元数据: {dllName}); continue; } // 补充元数据必须发生在热更代码调用相关 AOT 泛型之前 RuntimeApi.LoadMetadataForAOTAssembly(ta.bytes, HomologousImageMode.SuperSet); } ab.Unload(false); } private static void LoadHotUpdateAssembly() { AssetBundle ab AssetBundle.LoadFromFile(GetBundlePath()); TextAsset dll ab.LoadAssetTextAsset(HotUpdateDllName); Assembly hotUpdateAssembly Assembly.Load(dll.bytes); Type entry hotUpdateAssembly.GetType(HotUpdate.GameMain); if (entry null) { Debug.LogError([Hotfix] 热更入口类型不存在); return; } MethodInfo start entry.GetMethod(StartEntry); start?.Invoke(null, null); ab.Unload(false); } private static string GetBundlePath() { // 首包资源在 StreamingAssets后续更新资源在 persistentDataPath // 这里根据项目策略自行切换 return Application.streamingAssetsPath /hotupdate; } private static void FallbackToAOT() { // 你原有的启动逻辑 AOTMain.Start(); } }有几个细节需要说明。HomologousImageMode.SuperSet是官方示例里很常用的模式意思是用包含超集信息的方式加载元数据对裁剪后的 dll 兼容性更好。如果你的 dll 完全没裁剪可以用 Consistent 模式但项目一旦开了 Strip Engine Code经常会出现某些类型被裁掉的情况所以用 SuperSet 在实际项目里更省心。补充元数据的顺序一定要在加载热更 dll 之前。你在热更 dll 里写的代码可能用到了主工程的泛型方法解释器在执行时如果 AOT 侧没有现成函数实现就需要通过补充元数据去解析对应 IL。这个动作发生得越晚越容易在诡异的位置抛出异常。不要直接在主工程里静态调用热更程序集里的类。上面代码用反射拿HotUpdate.GameMain再调方法是我推荐的最小实现。真实项目里可以把这个入口抽象成一个接口放到 AOT 公共层热更代码提供一个实现这样主工程只需要按需求反射加载热更程序集再转换成约定接口去调用比纯反射更舒服。3.4 从 Generate/All 到 Android 打包代码写好后HybridCLR 的构建流程不是直接点 Unity 的 Build Player而是先执行HybridCLR - Generate/All。这一步会完成几件事把热更程序集编译成 dll、扫描代码生成必要的桥接代码、生成 AOT 泛型补充列表。也就是说桥接代码和泛型列表不是纯手工维护的而是在 Generate 阶段自动生成的。每次修改热更代码后如果你直接打包而忘了重新执行 Generate/All很可能打出来的包运行后行为异常因为桥接信息没有同步过来。命令行构建时也需要在打包前调用对应接口常见写法是using HybridCLR.Editor.Commands; using UnityEditor; using UnityEditor.Build; public static class BuildEntry { public static void BuildAndroid() { PrebuildCommand.GenerateAll(); BuildPlayerOptions options new BuildPlayerOptions(); options.scenes new[] { Assets/Scenes/Main.unity }; options.locationPathName Build/Android/demo.apk; options.target BuildTarget.Android; options.options BuildOptions.None; BuildPipeline.BuildPlayer(options); } }真机验证时Player Settings 里注意三点Scripting Backend 必须选 IL2CPPTarget Architecture 要勾选 ARM64很多中低端新机也已经只有 64 位库了至少你要保证包含 ARM64Strip Engine Code 可以暂时开着但首轮验证如果出现异常建议先关掉一次对比排查确认是热更链路问题还是裁剪问题。3.5 验证一次真正的不重装更新首包装完后写一个最简单的热更验证入口在热更程序集里做这样一件事在屏幕中央显示HotUpdate Version 1。装到手机上确认显示正确。然后把代码里的版本号改成HotUpdate Version 2重新 Generate/All重新打 AssetBundle但不要重新打 APK。把新的 AB 放到下载源手机 App 启动后下载新 AB再次加载时如果屏幕显示Version 2说明热更已经跑通。这一步是整个接入的“成人礼”。只要这个链路通了后面要做的就是把下载、校验、解压、加载打磨成正式框架。我见过不少项目卡在“编辑器里改了代码直接运行是新的但热更链路没通”核心原因就是忘了验证从 AB 里加载的还是不是最新那版 dll。打包 AB 之前建议在 AB 文件名或 dll 里写入版本号标识启动时打印出来避免新旧资源混淆。4. 首包之后躲不开的坑元数据缺失、AOT 泛型与裁剪4.1 真机 MissingMethodException 的排查路径能把 Demo 跑通只代表最小链路没问题。真实项目的第一个坎往往出现在把一部分业务代码挪进热更程序集之后。我印象最深的一次报错是 Android 真机进入某个界面直接抛ExecutionEngineException: Attempting to call method xxx for which no ahead of time (AOT) code was generated。在编辑器里怎么跑都没事一上 IL2CPP 就崩。遇到这类错误第一反应不要只盯着报错的那一行函数而是按照这个顺序排查初始化代码是否真的执行了。真机上热更初始化可能被 SDK 或启动顺序问题跳过先打日志确认LoadMetadataForAOTAssembly每个 dll 都成功了。元数据列表是否完整。报错类型如果是System.Collections.Generic.Dictionaryint, MyStruct之类的 AOT 泛型先查 System.dll、mscorlib.dll 的元数据是否被加载。报错方法是不是定义在热更 dll 里但实现需要调用 AOT 侧的泛型特化。这是最常见的情况。是否开启了代码裁剪裁剪把需要用到的元数据当成“无用数据”干掉了。不要一上来就想着用“AOT 泛型引用列表”硬补。先搞清楚报错方法属于哪个程序集、是不是泛型、泛型参数是不是值类型排查方向会清晰很多。4.2 AOT 泛型为什么不能靠事前祈祷规避AOT 泛型问题的本质是编译期和运行期的信息不对等。IL2CPP 打包时只会把主工程代码里实际引用过的泛型特化编译出来。假如你有一个MyStruct只在热更 dll 里出现了ListMyStruct而主工程从来没有实例化过这个组合那么在 AOT 的机器码里就真的没有ListMyStruct的实现。程序运行时发现需要它无论怎么找都找不到现成代码。HybridCLR 给出的路径是你想不到那我们就在运行时让解释器去现读 IL、现解释执行。所以补充元数据不只是凑个数它是给解释器提供了“原料”。只要元数据里包含那个泛型方法的 IL解释器就能自己把它跑起来不依赖 IL2CPP 现成机器码。但在实际项目里我遇到过需要补充的元数据太多导致启动阶段加载耗时上升的情况。后来我们做了个折中对性能敏感、且只在固定几个类型之间使用的泛型尽量在主工程的 AOT 侧提前打一次“引用锚点”让它被 IL2CPP 编译出来对业务里零散的泛型用法交给补充元数据解释执行。这样既不出错性能也可控。4.3 link.xml 裁剪与混淆带来的一连串问题元数据有了但如果构建时裁剪器把 dll 里的元数据当成“没被引用”的垃圾裁掉加载元数据时一样会失败。HybridCLR 官方工程里通常会带一份 link.xml 或者在 Installer 时配置好 keep 规则如果你是自己创建的新工程注意保留 AOT 程序集的相关节点。我们的教训是某次为了减包重打开 Strip Engine Code结果线上部分低端机开始随机出现加载失败。后来检查发现裁剪配置没有把第三方 SDK 里被热更代码反射调用的类型排除出去反射调用在 IL2CPP 裁剪后找不到类型。排查时可以先试着把Managed Stripping Level调到最低确认问题消失再逐步调高裁减等级定位是哪个规则误伤了类型。如果项目用了混淆或加固尤其是对 dll 做二次处理的方案要和热更链路分开对待。热更 dll 自己可以加密混淆运行时解密再Assembly.Load没问题但 AOT 元数据那批 dll 尽量不要做会影响元数据结构的混淆否则LoadMetadataForAOTAssembly时的模式校验可能直接不通过。排查这类问题有个技巧关闭混淆打一个包如果不再报错基本就是混淆规则或顺序的问题。4.4 一次真实排查字典泛型在热更里爆炸当初我们把任务系统挪进热更程序集时热更代码里有这么一段Dictionaryint, TaskReward rewardMap new Dictionaryint, TaskReward();TaskReward是热更程序集里的一个普通类int是值类型。这个写法在 C# 里再普通不过但在 IL2CPP 热更环境下它是一个典型的泛型特化组合主工程 AOT 侧从来没写过Dictionaryint, TaskReward所以没有现成 AOT 代码。最终是靠补充元数据解决的。我们在 AOT 元数据列表里带上 System.dll字典泛型的实现定义在这里并在加载热更 dll 之前调用LoadMetadataForAOTAssembly加载它解释器拿到元数据后就能自己解释执行这个泛型方法。如果你也想临时验证某个泛型问题是不是补充元数据能解决可以写一段只包含该泛型操作的测试热更代码真机跑一次比在论坛上猜快得多。5. 与项目框架配套AB 打包、启动更新和版本保护5.1 热更 dll 放 AssetBundle元数据放哪里热更 dll 本质上是一个二进制文件你可以直接放服务器让客户端下载后写到 persistentDataPath也可以塞进 AssetBundle。实战上我更推荐塞 AssetBundle原因不是放不下一个 dll而是项目本来就有资源更新链路复用同一套下载、校验、加载逻辑比另起一套文件下载稳定得多。有一点经验很重要不要把热更 dll 用 Unity 的 TextAsset 直接打进 ResourcesResources 里的东西在包发布后是不能动态替换的只适合放“永远不会变的 AOT 兜底版本”或某个基础元数据。真正要更新的是放在 AssetBundle 里的那份 dll首包时可以把这个 AB 同时放到 StreamingAssets Unity HybridCLR热更新实战：原理、接入顺序与真机排坑
我到现在都记得第一次线上事故的场景一个已经过审上架的手游运营活动发奖励的数值公式少取了一次随机数玩家领到的奖励高了两倍。服务端立刻封住漏洞但已经安装的客户端代码是死的发新版要走渠道审核少则一天多则一周那几天项目组每个人脸上都写着焦虑。那次之后我们整个团队把“代码热更新”从“以后再说”提到了“下周必须验证”的优先级。最后选型、验证、接入的方案就是今天这篇要聊的 Unity HybridCLR 热更新。如果只用一句话介绍HybridCLR 是一个基于 IL2CPP 的 C# 热更新方案它能让你的 Unity 项目在不重新打包上架、玩家不重新下载安装包的情况下通过加载一段新的 C# 程序集来更新游戏逻辑。这篇文章是我自己从零把一个 Demo 工程接入 HybridCLR再逐步推进到真实项目的完整记录。重点不是重复官方文档而是告诉你接入顺序、依赖方向、AOT 泛型问题这些文档里不容易一次讲透的东西以及我踩过的坑长什么样。如果你是想评估热更新方案的技术负责人、正在给老项目接热更的 Unity 客户端同学或者刚被分配要验证 HybridCLR 可行性的新手这篇应该能帮你省下不少试错时间。读完你应该能知道它和 Lua 热更、和 IDE 里的热重载到底什么关系接入前工程要做什么体检真机上跑通一个最小热更工程需要哪几步以及第一轮真机崩溃该怎么查。1. 为什么是 HybridCLR而不是 Lua 或者热重载1.1 IL2CPP 把代码焊死在哪里要理解 HybridCLR 的价值先得知道 Unity 的 IL2CPP 到底做了什么。在没有 IL2CPP 的 Mono 时代C# 代码会被编译成 IL运行时由 Mono 虚拟机解释或 JIT 编译执行。那个年代想在 iOS 上做热更新很麻烦因为苹果明确禁止应用在自己的沙盒里动态生成可执行代码JIT 这条路在 iOS 上基本是堵死的。IL2CPP 是把 C# 先编译成 IL再在构建阶段把 IL 转成 C最后随原生工程一起编译成目标平台的机器码。好处是启动快、性能好、代码不容易被直接反编译成原始 C#坏处也藏在这里所有 C# 逻辑都在编译期被翻译并“焊死”进了原生二进制运行时已经没有一套能把新 IL 编译成机器码的机制了。这就好比你把菜谱都刻成了石碑读者只能照着石碑做菜现在你拿到一张新菜谱却没有火源也没有翻译想按新菜谱做菜根本无从下手。HybridCLR 做的是在 IL2CPP 旁边补了一个“解释执行器”让新拿到的 C# 程序集也就是热更 dll里的 IL 字节码不经过 JIT 也能被逐条解释执行。1.2 它和 xLua、ILRuntime 的本质差异很多团队第一次聊热更新听到的往往是 xLua、tolua或者纯 C# 的 ILRuntime。这里我直接按实际感受做个比较。Lua 方案的核心是“换语言”业务逻辑不写在 C# 里而是写 Lua运行时由 C# 侧的虚拟机解释执行。好处是生态成熟、很多老项目都在用代价是整个项目的核心玩法可能要从 C# 平移成 Lua维护一套双语言逻辑团队里每个人都要会 Lua出问题时要跨语言查堆栈代码补全和重构也不够舒服。ILRuntime 是纯 C# 的解释器方案不需要换语言但它和 Unity 的 AOT 世界之间隔了一层自己的运行时对某些 C# 特性的支持以及对 Unity 引擎调用、泛型、值类型结构的处理需要开发者额外注意。性能和兼容性一直在进步但遇到冷门边界总有“为什么这里不行”的疑惑。HybridCLR 选择的是另一条路线尽可能贴近原生 CLR 的实现方式在 IL2CPP 的 AOT 基础上加一个解释器模块并且用“补充元数据”的方式解决 AOT 泛型缺失的经典问题。用下来最直观的感受是它不是让你把逻辑翻译成另一种语言而是让热更 dll 里的 C# 代码自己跑起来和主工程的 C# 代码写法差别不大。对比项Lua 系方案ILRuntimeHybridCLR业务语言Lua C#C#C#与 IL2CPP 关系独立虚拟机独立解释器基于 IL2CPP 补充解释能力学习成本需要掌握 Lua较低但边界概念多较低重点是理解 AOT 与热更分界泛型等边界问题不受 IL2CPP 泛型影响有自己的处理通过补充元数据解决大多数社区活跃度高但偏向旧项目中高近几年增长很快需要客观说的是HybridCLR 本质上是修改了 Unity 的 IL2CPP 构建链路Unity 版本升级、IL2CPP 内部实现调整都有可能影响它。所以它不是一个“装一次永远不用管”的方案每次 Unity 升级或 HybridCLR 升级都要做回归验证。这点后面章节会细说。1.3 先理清“热更新”和“热重载”不是一回事热搜词里出现了不少和热更新相关的词比如 Flutter 热重载、IDEA 修改代码热更新、Nacos 配置热更新。这些词经常被混在一起但它们解决的问题完全不同。Flutter 的热重载本质是开发期工具改完代码按一下 R开发进程把新的 widget 树推给正在运行的调试 App帮开发者快速看 UI 效果。它不面向线上玩家代码改动只在开发环境里生效。IDEA 里修改 Java 代码后的热更新是让本地开发服务器不用重启就能加载新类属于开发效率工具的范围。Nacos 配置热更新更新的是配置项不是程序逻辑本身。而 Unity 项目里说的“代码热更新”指的是已经安装到玩家手机上的 App在不发新包的前提下从服务器拉取新的 C# 程序集并在本地执行新逻辑。这是玩家可见的能力直接关系到线上事故的处理速度和上面那些开发期工具完全不是一个维度。所以有些同学问“我项目里用 IDE 热重载很顺是不是就不用 HybridCLR 了”答案显然是否定的。2. 接入前先给工程“体检”程序集、依赖方向、泛型用法2.1 依赖方向热更代码能引用什么不能引用什么接入 HybridCLR 最容易犯的错是直接拿一个已经写了两三年的老工程把所有代码都扫进热更程序集然后开始打包。正确的第一步是给工程划分程序集边界。Unity 项目里用 asmdef 把代码分成多个程序集主工程里有一套专门给热更代码用的接口和公共代码热更代码所在的程序集可以引用主工程的公共程序集但主工程的 AOT 代码绝对不能反过来引用热更程序集里的类型。一旦主工程静态引用了热更代码里的类打 IL2CPP 包时就会把热更代码一起编进去后续想替换逻辑就会非常别扭。我在项目里习惯的分层是这样的AOT 主程序集启动流程、SDK 对接、资源管理、渲染相关、游戏的底层框架。AOT 公共接口层纯接口和 DTO 定义比如战斗结算接口、活动模板接口供热更代码实现或调用。热更程序集赛季玩法、活动界面、数值表现、任务系统这类需要频繁调整的逻辑。依赖方向是热更层可以引用 AOT 公共接口层AOT 公共接口层不能引用热更层。因为热更层是运行时才被加载的AOT 侧的代码在编译期根本不知道它的存在两者之间只能靠接口或反射沟通。2.2 重点检查一遍泛型使用习惯体检时另一个重点是泛型。C# 泛型在 AOT 编译下有个天然矛盾IL2CPP 编译器在打包时只会为主工程代码里“显式出现过的泛型实例化”生成机器码。如果热更代码运行时突然出现一个 AOT 模块里从未实例化过的泛型组合比如DictionaryMyStruct, intIL2CPP 那边并没有对应的目标代码运行时就会报类似AOT generic method can not be instantiated的错误。HybridCLR 的解法是“补充元数据 解释器兜底”。打包时项目会带上 AOT 必需 dll比如 mscorlib、System、UnityEngine.CoreModule 这些的元数据运行时先加载这些元数据让解释器能够自己解析泛型方法的 IL 并执行而不是必须依赖 IL2CPP 现成的机器码。这并不代表你可以完全无视泛型。我建议在接入前把项目里“值类型 泛型容器混用”的地方扫一遍。比如大量使用Listint、Dictionaryint, MyEnum、Dictionarylong, MyStruct尤其是这些结构体是活动逻辑里临时定义的时候要格外留意。这里不是说不能用而是你要意识到这类代码会触发 AOT 泛型补充机制线上报错后排查成本会高一些。2.3 确认版本兼容与目标平台体检还包括两个基础问题项目用的 Unity 版本以及 Scripting Backend 是否已经是 IL2CPP。HybridCLR 只支持 IL2CPPMono 后端不在讨论范围内。Android 项目由于现在 Google Play 和国内渠道对 Target API Level 的要求越来越高很多项目把target API level提到了 33、34、35这个过程中只要正常使用 IL2CPP 并勾选 ARM64不会和 HybridCLR 产生直接冲突。但如果是很老的项目一直跑在 ARMv7 或 Mono 上最好先把构建链路切干净再谈热更。Unity 版本建议尽量用 LTS比如 2021.3 LTS、2022.3 LTS 或官方文档当前明确支持的版本。HybridCLR 的发布节奏通常能跟上主流 LTS用非 LTS 版本容易遭遇兼容性盲区。安装时下载的是focus-creative-games/hybridclr_unity这份 Unity 侧工程代码版本要和项目 Unity 版本匹配别随手拉最新版就往老项目里塞。3. 真机跑通全流程一个最小可热更工程的搭建记录3.1 安装包和 Installer 到底做了什么接入时首先通过 Unity Package Manager 用 Git URL 把 HybridCLR 的 Unity 包加到工程里。拉取成功后菜单栏会出现 HybridCLR 相关的入口。接下来执行的是 HybridCLR - Installer这一步会往工程里写一些必要的代码更关键的是它会修改本地的 IL2CPP把解释器相关模块合入 il2cpp 的构建链。也就是说它不只是往 Assets 里加几个脚本还动到了 Unity 编辑器安装目录下的 il2cpp 相关文件。这里有两个容易踩的点。第一Installer 执行时如果 Unity 正在占用相关文件或者杀毒软件拦截了对安装目录的修改安装可能“假成功”。我遇到过安装后 Generate 时各种诡异报错重装一次 HybridCLR 就好了。建议执行完 Installer 后先做一次简单的生成操作验证而不是直接开始打大包。第二升级 Unity 小版本后最好重新执行 Installer。IL2CPP 内部文件结构会随版本变化旧的补丁不一定还能用。我们项目从 Unity 2021.3.16 升到 2021.3.31 时因为漏了这一步打出来的包初始化阶段直接崩溃排查了半天才发现是 installer 没重跑。3.2 创建热更程序集并在 Settings 里登记HybridCLR 需要知道哪些程序集要被当作热更程序集处理。官方推荐用 asmdef 组织但不是把文件夹命名为 HotUpdate 就行而是在工程里建一个真正的 Assembly Definition。我的做法是在 Assets 下建两个目录Assets/Scripts/Main主工程逻辑里面放Main.asmdef。Assets/Scripts/HotUpdate热更逻辑里面放HotUpdate.asmdef。由于 HotUpdate 需要引用 Main 里定义的类型和接口在HotUpdate.asmdef的 Assembly Definition References 里加上 Main反之 Main 里不要引用 HotUpdate。这样主工程干净热更程序集可以随意引用它依赖的 AOT 库。创建好 asmdef 后打开菜单HybridCLR - Settings把 HotUpdate 加进热更新程序集列表。Install 时官方脚本会自动生成一套默认配置里面通常已经预设了 compile 用的 AOT 程序集列表和补充元数据列表。新工程用默认配置其实就能跑通不需要一开始就手动维护一堆列表。3.3 初始化的核心代码补充元数据再加载热更程序集接入代码最核心的只有两步先补充 AOT 元数据再Assembly.Load热更 dll。补充元数据这一步是用HybridCLR.RuntimeApi.LoadMetadataForAOTAssembly把 AOT dll 的元数据喂给解释器。注意每个 dll 要单独调用一次不能把多个 dll 拼成一个 byte 数组一次性传进去。这里直接放一份可运行的初始化思路using System; using System.Reflection; using HybridCLR; using UnityEngine; public static class HotfixBootstrap { // 假设这些 dll 都已经被打进同一个 AssetBundle // 并且以 TextAsset 形式加载 private static readonly string[] AotDllNames { mscorlib.dll, System.dll, System.Core.dll, UnityEngine.CoreModule.dll, Main.dll, }; private const string HotUpdateDllName HotUpdate.dll; public static void Start() { try { LoadAotMetadata(); LoadHotUpdateAssembly(); } catch (Exception e) { Debug.LogError($[Hotfix] 热更启动失败走 AOT 兜底逻辑. {e}); FallbackToAOT(); } } private static void LoadAotMetadata() { AssetBundle ab AssetBundle.LoadFromFile(GetBundlePath()); foreach (string dllName in AotDllNames) { TextAsset ta ab.LoadAssetTextAsset(dllName); if (ta null) { Debug.LogError($[Hotfix] 缺少 AOT 元数据: {dllName}); continue; } // 补充元数据必须发生在热更代码调用相关 AOT 泛型之前 RuntimeApi.LoadMetadataForAOTAssembly(ta.bytes, HomologousImageMode.SuperSet); } ab.Unload(false); } private static void LoadHotUpdateAssembly() { AssetBundle ab AssetBundle.LoadFromFile(GetBundlePath()); TextAsset dll ab.LoadAssetTextAsset(HotUpdateDllName); Assembly hotUpdateAssembly Assembly.Load(dll.bytes); Type entry hotUpdateAssembly.GetType(HotUpdate.GameMain); if (entry null) { Debug.LogError([Hotfix] 热更入口类型不存在); return; } MethodInfo start entry.GetMethod(StartEntry); start?.Invoke(null, null); ab.Unload(false); } private static string GetBundlePath() { // 首包资源在 StreamingAssets后续更新资源在 persistentDataPath // 这里根据项目策略自行切换 return Application.streamingAssetsPath /hotupdate; } private static void FallbackToAOT() { // 你原有的启动逻辑 AOTMain.Start(); } }有几个细节需要说明。HomologousImageMode.SuperSet是官方示例里很常用的模式意思是用包含超集信息的方式加载元数据对裁剪后的 dll 兼容性更好。如果你的 dll 完全没裁剪可以用 Consistent 模式但项目一旦开了 Strip Engine Code经常会出现某些类型被裁掉的情况所以用 SuperSet 在实际项目里更省心。补充元数据的顺序一定要在加载热更 dll 之前。你在热更 dll 里写的代码可能用到了主工程的泛型方法解释器在执行时如果 AOT 侧没有现成函数实现就需要通过补充元数据去解析对应 IL。这个动作发生得越晚越容易在诡异的位置抛出异常。不要直接在主工程里静态调用热更程序集里的类。上面代码用反射拿HotUpdate.GameMain再调方法是我推荐的最小实现。真实项目里可以把这个入口抽象成一个接口放到 AOT 公共层热更代码提供一个实现这样主工程只需要按需求反射加载热更程序集再转换成约定接口去调用比纯反射更舒服。3.4 从 Generate/All 到 Android 打包代码写好后HybridCLR 的构建流程不是直接点 Unity 的 Build Player而是先执行HybridCLR - Generate/All。这一步会完成几件事把热更程序集编译成 dll、扫描代码生成必要的桥接代码、生成 AOT 泛型补充列表。也就是说桥接代码和泛型列表不是纯手工维护的而是在 Generate 阶段自动生成的。每次修改热更代码后如果你直接打包而忘了重新执行 Generate/All很可能打出来的包运行后行为异常因为桥接信息没有同步过来。命令行构建时也需要在打包前调用对应接口常见写法是using HybridCLR.Editor.Commands; using UnityEditor; using UnityEditor.Build; public static class BuildEntry { public static void BuildAndroid() { PrebuildCommand.GenerateAll(); BuildPlayerOptions options new BuildPlayerOptions(); options.scenes new[] { Assets/Scenes/Main.unity }; options.locationPathName Build/Android/demo.apk; options.target BuildTarget.Android; options.options BuildOptions.None; BuildPipeline.BuildPlayer(options); } }真机验证时Player Settings 里注意三点Scripting Backend 必须选 IL2CPPTarget Architecture 要勾选 ARM64很多中低端新机也已经只有 64 位库了至少你要保证包含 ARM64Strip Engine Code 可以暂时开着但首轮验证如果出现异常建议先关掉一次对比排查确认是热更链路问题还是裁剪问题。3.5 验证一次真正的不重装更新首包装完后写一个最简单的热更验证入口在热更程序集里做这样一件事在屏幕中央显示HotUpdate Version 1。装到手机上确认显示正确。然后把代码里的版本号改成HotUpdate Version 2重新 Generate/All重新打 AssetBundle但不要重新打 APK。把新的 AB 放到下载源手机 App 启动后下载新 AB再次加载时如果屏幕显示Version 2说明热更已经跑通。这一步是整个接入的“成人礼”。只要这个链路通了后面要做的就是把下载、校验、解压、加载打磨成正式框架。我见过不少项目卡在“编辑器里改了代码直接运行是新的但热更链路没通”核心原因就是忘了验证从 AB 里加载的还是不是最新那版 dll。打包 AB 之前建议在 AB 文件名或 dll 里写入版本号标识启动时打印出来避免新旧资源混淆。4. 首包之后躲不开的坑元数据缺失、AOT 泛型与裁剪4.1 真机 MissingMethodException 的排查路径能把 Demo 跑通只代表最小链路没问题。真实项目的第一个坎往往出现在把一部分业务代码挪进热更程序集之后。我印象最深的一次报错是 Android 真机进入某个界面直接抛ExecutionEngineException: Attempting to call method xxx for which no ahead of time (AOT) code was generated。在编辑器里怎么跑都没事一上 IL2CPP 就崩。遇到这类错误第一反应不要只盯着报错的那一行函数而是按照这个顺序排查初始化代码是否真的执行了。真机上热更初始化可能被 SDK 或启动顺序问题跳过先打日志确认LoadMetadataForAOTAssembly每个 dll 都成功了。元数据列表是否完整。报错类型如果是System.Collections.Generic.Dictionaryint, MyStruct之类的 AOT 泛型先查 System.dll、mscorlib.dll 的元数据是否被加载。报错方法是不是定义在热更 dll 里但实现需要调用 AOT 侧的泛型特化。这是最常见的情况。是否开启了代码裁剪裁剪把需要用到的元数据当成“无用数据”干掉了。不要一上来就想着用“AOT 泛型引用列表”硬补。先搞清楚报错方法属于哪个程序集、是不是泛型、泛型参数是不是值类型排查方向会清晰很多。4.2 AOT 泛型为什么不能靠事前祈祷规避AOT 泛型问题的本质是编译期和运行期的信息不对等。IL2CPP 打包时只会把主工程代码里实际引用过的泛型特化编译出来。假如你有一个MyStruct只在热更 dll 里出现了ListMyStruct而主工程从来没有实例化过这个组合那么在 AOT 的机器码里就真的没有ListMyStruct的实现。程序运行时发现需要它无论怎么找都找不到现成代码。HybridCLR 给出的路径是你想不到那我们就在运行时让解释器去现读 IL、现解释执行。所以补充元数据不只是凑个数它是给解释器提供了“原料”。只要元数据里包含那个泛型方法的 IL解释器就能自己把它跑起来不依赖 IL2CPP 现成机器码。但在实际项目里我遇到过需要补充的元数据太多导致启动阶段加载耗时上升的情况。后来我们做了个折中对性能敏感、且只在固定几个类型之间使用的泛型尽量在主工程的 AOT 侧提前打一次“引用锚点”让它被 IL2CPP 编译出来对业务里零散的泛型用法交给补充元数据解释执行。这样既不出错性能也可控。4.3 link.xml 裁剪与混淆带来的一连串问题元数据有了但如果构建时裁剪器把 dll 里的元数据当成“没被引用”的垃圾裁掉加载元数据时一样会失败。HybridCLR 官方工程里通常会带一份 link.xml 或者在 Installer 时配置好 keep 规则如果你是自己创建的新工程注意保留 AOT 程序集的相关节点。我们的教训是某次为了减包重打开 Strip Engine Code结果线上部分低端机开始随机出现加载失败。后来检查发现裁剪配置没有把第三方 SDK 里被热更代码反射调用的类型排除出去反射调用在 IL2CPP 裁剪后找不到类型。排查时可以先试着把Managed Stripping Level调到最低确认问题消失再逐步调高裁减等级定位是哪个规则误伤了类型。如果项目用了混淆或加固尤其是对 dll 做二次处理的方案要和热更链路分开对待。热更 dll 自己可以加密混淆运行时解密再Assembly.Load没问题但 AOT 元数据那批 dll 尽量不要做会影响元数据结构的混淆否则LoadMetadataForAOTAssembly时的模式校验可能直接不通过。排查这类问题有个技巧关闭混淆打一个包如果不再报错基本就是混淆规则或顺序的问题。4.4 一次真实排查字典泛型在热更里爆炸当初我们把任务系统挪进热更程序集时热更代码里有这么一段Dictionaryint, TaskReward rewardMap new Dictionaryint, TaskReward();TaskReward是热更程序集里的一个普通类int是值类型。这个写法在 C# 里再普通不过但在 IL2CPP 热更环境下它是一个典型的泛型特化组合主工程 AOT 侧从来没写过Dictionaryint, TaskReward所以没有现成 AOT 代码。最终是靠补充元数据解决的。我们在 AOT 元数据列表里带上 System.dll字典泛型的实现定义在这里并在加载热更 dll 之前调用LoadMetadataForAOTAssembly加载它解释器拿到元数据后就能自己解释执行这个泛型方法。如果你也想临时验证某个泛型问题是不是补充元数据能解决可以写一段只包含该泛型操作的测试热更代码真机跑一次比在论坛上猜快得多。5. 与项目框架配套AB 打包、启动更新和版本保护5.1 热更 dll 放 AssetBundle元数据放哪里热更 dll 本质上是一个二进制文件你可以直接放服务器让客户端下载后写到 persistentDataPath也可以塞进 AssetBundle。实战上我更推荐塞 AssetBundle原因不是放不下一个 dll而是项目本来就有资源更新链路复用同一套下载、校验、加载逻辑比另起一套文件下载稳定得多。有一点经验很重要不要把热更 dll 用 Unity 的 TextAsset 直接打进 ResourcesResources 里的东西在包发布后是不能动态替换的只适合放“永远不会变的 AOT 兜底版本”或某个基础元数据。真正要更新的是放在 AssetBundle 里的那份 dll首包时可以把这个 AB 同时放到 StreamingAssets