1. 热更新到底在解决什么问题1.1 从一次线上事故说起前两年我参与过一款已经上线的卡牌手游维护某个周五晚上运营突然要改一张卡牌的技能数值从“造成200%攻击力伤害”改成“造成180%攻击力伤害并附加减速”。听起来就是改一个配置表的事但当时项目没有做热更新这个改动意味着要走渠道审核、重新打包、重新提审安卓渠道快的话一天iOS 遇到周末可能要拖到周一。运营那边活动已经预热了最后只能硬着头皮用服务器下发的方式绕过去客户端表现和服务器逻辑对不上玩家截图到处传口碑掉了一截。那次之后我下定决心把热更新这套东西吃透。后来换项目从零开始搭了一套YooAsset HybridCLR的方案一直用到项目上线一年多中间迭代了几十个版本纯逻辑改动和 UI 调整基本都能做到当天出包、当天验证、当天上线。这篇就把我踩过的坑和完整的搭建思路整理出来给正在做 Unity 进阶、准备上热更新的朋友一个可以直接抄的参考。先说清楚这套组合各自负责什么。YooAsset管的是资源也就是 AssetBundle 的打包、加载、版本比对、下载、缓存这一整套流程HybridCLR管的是代码它让 Unity 里用 C# 写的逻辑代码能够以解释执行的方式跑起来从而绕开 IL2CPP 的 AOT 限制实现逻辑热更。两者配合资源和代码都能热更才算是一套完整的热更新方案。1.2 谁适合看这篇如果你已经会用 Unity 做完整的单机或者联网项目熟悉 Prefab、ScriptableObject、协程这些基础但对“怎么让线上包不改包就能更新”这件事还没有清晰思路那这篇就是写给你的。我会从最基础的概念讲起把每个环节为什么这么做讲透再给出可以直接落地的配置和代码。如果你已经在用 Addressable 或者自己写的 AB 管理想迁移到 YooAsset或者想给现有项目加代码热更能力这篇里的对比和迁移注意事项也能帮到你。整篇内容偏基础篇重点在“搭起来、跑通、能出包”进阶的优化和复杂场景我会在后续文章里展开。2. 方案选型为什么是 YooAsset 加 HybridCLR2.1 资源层为什么选 YooAsset 而不是 AddressableUnity 官方现在主推的是 Addressable功能确实全但我在实际项目里用下来有几个点比较难受。第一是它的分组和打包策略配置项非常多新手很容易配错一个 Group 的 Bundle Mode 选错可能整个包体就炸了第二是它的版本管理和 CDN 部署需要自己写不少胶水代码官方给的示例偏简单真上生产要补很多东西第三是它的加载 API 偏底层业务层用起来不够顺手。YooAsset 是国内团队做的开源方案定位很明确就是解决 AssetBundle 从打包到运行时的全流程管理。它的几个优势我特别看重打包策略配置直观一个 Collector 配好收集规则和打包规则就行运行模式清晰编辑器模拟、单机、联机三种模式切换方便开发期不用真打包就能跑版本比对和下载流程内置联机模式下自动处理清单比对、增量下载、断点续传这些逻辑。对于中小团队来说能省掉大量自己造轮子的时间。当然 Addressable 也不是不能用如果你的团队已经有一套成熟的 Addressable 工作流没必要为了换而换。但如果是新项目从零开始我个人的建议是优先考虑 YooAsset上手曲线更平缓出问题的概率更低。2.2 代码层为什么选 HybridCLR代码热更这块历史上主流方案有几种。早期用得比较多的是Lua系方案比如 xLua、ToLua逻辑用 Lua 写通过 C# 和 Lua 的互调实现热更。这套方案成熟稳定但问题是团队要维护两套语言C# 和 Lua 之间的类型转换、GC、调试都是成本招人也要招会 Lua 的。另一种是ILRuntime用 C# 写热更代码通过解释执行 IL 实现。它比 Lua 好的一点是语言统一了但性能上因为要跨域调用热更代码和主工程代码之间的交互有额外开销而且它对 C# 新版本语法的支持有滞后。HybridCLR是近两年起来的方案它的核心思路是扩展 IL2CPP 的运行时让 AOT 编译出来的程序集和解释执行的程序集能够无缝互通。也就是说热更代码和主工程代码在类型系统层面是打通的调用热更代码里的类就像调用普通 C# 类一样自然没有跨域的概念。性能上比纯解释方案好很多语法支持也基本跟得上最新的 C# 版本。对我们这种想用一套 C# 打天下的团队来说HybridCLR 是目前最舒服的选择。2.3 两者结合的完整链路把两者串起来看一次完整的热更流程是这样的开发阶段把要热更的逻辑代码单独放到一个程序集里标记为热更程序集打包时这个程序集不参与 AOT 编译而是作为 DLL 被 YooAsset 当作资源打进 AB 包运行时先通过 YooAsset 从 CDN 或者本地把最新的 DLL 和资源下载下来再用 HybridCLR 的加载接口把 DLL 加载进运行时最后反射调用入口方法启动热更逻辑。这里有个关键点要理解HybridCLR 负责“怎么让 DLL 跑起来”YooAsset 负责“DLL 从哪来、怎么更新”。两者职责清晰配合起来就是一套完整的代码加资源热更方案。3. 环境搭建与工程配置实操3.1 版本选择和安装版本这块我踩过坑必须强调一下。HybridCLR 对 Unity 版本有要求太老的版本不支持太新的版本可能还没适配。我实测下来比较稳的组合是Unity 2021.3 LTS 或者 2022.3 LTS这两个是长期支持版本HybridCLR 的适配也最完善。2020 及以前的版本不建议2023 之后的版本要确认 HybridCLR 的 release 说明里有没有明确支持。YooAsset 的安装通过 Package Manager 的 Git URL 方式最方便在Packages/manifest.json里加上对应的依赖项或者在 Package Manager 里选“Add package from git URL”。HybridCLR 的安装稍微特殊一点它需要修改 Unity 的安装目录所以官方提供了一个安装器。安装流程是先通过 Package Manager 装好 HybridCLR 的包然后在菜单栏找到 HybridCLR 的安装入口点安装它会自动把 IL2CPP 的相关文件替换成支持解释执行的版本。注意HybridCLR 的安装会修改 Unity 编辑器安装目录下的文件所以如果你用的是团队共享的 Unity 安装装之前最好确认一下会不会影响其他人。另外安装完成后建议重启一次编辑器让改动生效。3.2 程序集划分的核心原则这是整个方案里最需要想清楚的一步。HybridCLR 的工作方式是AOT 程序集在打包时被编译成机器码不能热更热更程序集以 DLL 形式存在可以热更。所以我们要把代码合理地分到这两类程序集里。我的划分原则是这样的框架层、第三方库、启动流程放 AOT这些代码基本不会变而且启动阶段就要用业务逻辑、UI 逻辑、数值计算、活动玩法放热更这些是迭代最频繁的部分。具体操作是在 Unity 里创建 asmdef 文件来划分程序集比如建一个Game.HotUpdate的 asmdef把业务代码都放进去。这里有个容易忽略的点热更程序集不能引用 AOT 程序集里没有的类型反过来 AOT 程序集可以引用热更程序集里的类型通过反射或者接口。所以划分的时候要保证热更程序集依赖的基础类型都在 AOT 里比如 Unity 引擎的类、你自己框架层的基类。3.3 关键配置项逐条说明配置这块我列一个表把几个必须改的地方说清楚。配置项位置作用建议值Scripting BackendPlayer Settings脚本后端IL2CPPApi Compatibility LevelPlayer SettingsAPI 兼容级别.NET 4.xHybridCLR SettingsHybridCLR 面板热更程序集列表填入热更 asmdef 名YooAsset CollectorYooAsset 面板资源收集规则按文件夹或标签收集YooAsset Play ModeYooAsset 面板运行模式开发期用 EditorSimulateModeApi Compatibility Level一定要选.NET 4.x选.NET Standard 2.0的话有些反射相关的 API 用不了HybridCLR 加载 DLL 时会报错。Scripting Backend必须是 IL2CPPMono 后端下 HybridCLR 没有意义因为 Mono 本身就能热更。HybridCLR 面板里的热更程序集列表要把你创建的Game.HotUpdate这类 asmdef 的名字填进去。填完之后打包时这些程序集就不会被 AOT 编译而是生成对应的 DLL 文件。4. 资源打包与加载的完整实现4.1 YooAsset 的初始化流程YooAsset 的初始化分几步走。第一步是创建 Package一个 Package 可以理解为一个独立的资源包比如基础资源包、活动资源包可以分开。第二步是初始化运行模式开发期用EditorSimulateMode它不需要真打包直接从 AssetDatabase 读资源改完代码和资源立刻生效调试效率极高出包测试用OfflinePlayMode资源打进包体不联网正式上线用HostPlayMode从 CDN 下载。初始化代码大概长这样private IEnumerator InitYooAsset() { var package YooAssets.CreatePackage(DefaultPackage); YooAssets.SetDefaultPackage(package); var initParams new HostPlayModeParameters(); initParams.BuildinQueryServices new GameQueryServices(); initParams.RemoteServices new RemoteServices(hostServer, fallbackHostServer); initParams.DecryptionServices new GameDecryptionServices(); var initOp package.InitializeAsync(initParams); yield return initOp; if (initOp.Status ! EOperationStatus.Succeed) { Debug.LogError($YooAsset init failed: {initOp.Error}); yield break; } var versionOp package.UpdatePackageVersionAsync(); yield return versionOp; if (versionOp.Status ! EOperationStatus.Succeed) yield break; var manifestOp package.UpdatePackageManifestAsync(versionOp.PackageVersion); yield return manifestOp; if (manifestOp.Status ! EOperationStatus.Succeed) yield break; }这段代码里RemoteServices是你要自己实现的负责告诉 YooAsset 从哪个地址下载资源。UpdatePackageVersionAsync会去远端拉一个版本文件比对本地版本决定要不要更新清单。清单更新完就可以开始下载差异资源了。4.2 资源收集和打包策略YooAsset 的打包核心是 Collector。一个 Collector 配一个收集规则和一个打包规则。收集规则决定哪些资源被打进这个 Collector可以按文件夹、按标签、按资源类型。打包规则决定这些资源怎么合并成 Bundle常见的有PackDirectory按目录打包、PackByFile一个文件一个包、PackByTag按标签打包。我的经验是UI 资源按目录打包一个界面的图集和 Prefab 放一个目录打成一个包加载和卸载都方便公共资源单独打一个包比如字体、通用图集、Shader这些被多个界面引用单独打包避免重复配置表按类型打包所有配置表打成一个包启动时一次性加载。提示打包粒度太细会导致 Bundle 数量爆炸加载时 IO 次数多粒度太粗会导致更新时下载量大改一个小图要下整个大包。一般建议单个 Bundle 控制在 1 到 5 MB 之间具体看项目规模调整。4.3 热更 DLL 作为资源处理HybridCLR 生成的热更 DLL 需要被 YooAsset 当作资源管理这样才能走下载和更新流程。做法是在打包前把 HybridCLR 编译出来的 DLL 拷贝到一个指定目录然后让 YooAsset 的 Collector 把这个目录收集进去。这里有个细节DLL 文件的后缀名。Unity 默认不识别.dll作为 TextAsset需要把后缀改成.bytes才能被当作二进制资源加载。HybridCLR 提供了编译后处理的接口可以在编译完成时自动把 DLL 改名并拷贝到目标目录。// 编译后处理把热更 DLL 拷贝到 YooAsset 收集目录 public static void OnPostProcessBuild() { string dllDir Path.Combine(Application.dataPath, HotUpdateDlls); // 把 HybridCLR 编译产物拷贝过来并改名 // 具体路径根据 HybridCLR 的输出目录调整 }加载的时候先用 YooAsset 把 DLL 的 bytes 读出来再交给 HybridCLR 的RuntimeApi.LoadMetadataForAOTAssembly和Assembly.Load处理。5. 代码热更的加载与执行5.1 AOT 补充元数据的处理HybridCLR 有个概念叫AOT 补充元数据。因为 AOT 程序集在打包时被编译成了机器码一些泛型实例化、反射相关的元数据可能丢失了。当热更代码里用到这些丢失的元数据时就需要在运行时把对应的补充元数据 DLL 加载进来。补充元数据的 DLL 是 HybridCLR 在打包时自动生成的通常叫mscorlib.dll.bytes、System.dll.bytes这类。加载顺序上补充元数据要在热更 DLL 之前加载否则热更代码里用到相关类型时会报错。// 先加载补充元数据 foreach (var aotDll in aotMetaDlls) { var bytes LoadDllBytes(aotDll); RuntimeApi.LoadMetadataForAOTAssembly(bytes, HomologousImageMode.SuperSet); } // 再加载热更 DLL var hotUpdateBytes LoadDllBytes(Game.HotUpdate.dll); var assembly Assembly.Load(hotUpdateBytes);HomologousImageMode.SuperSet这个模式是推荐值它比Consistent模式兼容性更好能处理更多元数据缺失的情况。5.2 热更入口的反射调用热更 DLL 加载进来后需要一个入口方法启动热更逻辑。通常的做法是在热更程序集里定义一个静态类比如HotUpdateEntry里面有一个Start方法。AOT 层通过反射找到这个类和方法调用它。var entryType assembly.GetType(Game.HotUpdate.HotUpdateEntry); var startMethod entryType.GetMethod(Start, BindingFlags.Public | BindingFlags.Static); startMethod.Invoke(null, null);反射调用有性能开销但只在启动时调一次可以忽略。如果热更逻辑需要和 AOT 层频繁交互更好的做法是定义一个接口放在 AOT 层热更层实现这个接口AOT 层通过接口调用避免每次反射。5.3 版本管理和回滚机制热更最怕的是更新出问题导致玩家进不去游戏。所以版本管理和回滚机制必须做。我的做法是每次热更都生成一个版本号记录在清单文件里客户端启动时先拉远端版本号和本地比对如果远端版本比本地新就下载新资源下载完成后做一次校验校验通过才切换版本。回滚的话保留上一个版本的资源不删如果新版本启动失败自动切回旧版本。YooAsset 的缓存机制支持多版本共存只要不清缓存旧版本资源还在。注意回滚机制要在启动流程里做好超时和异常捕获比如下载超时、DLL 加载失败、入口方法抛异常这些情况都要能捕获到并触发回滚否则玩家会卡在加载界面。6. 常见问题排查与避坑经验6.1 打包和加载阶段的典型报错报错一TypeLoadException或者MissingMethodException。这个基本是 AOT 补充元数据没加载全导致的。排查方法是看报错里提到的类型属于哪个程序集然后确认对应的补充元数据 DLL 有没有加载。有时候是加载顺序问题补充元数据必须在热更 DLL 之前加载。报错二DllNotFoundException或者 IL2CPP 相关的错误。这个通常是 HybridCLR 没安装成功或者安装后没重启编辑器。重新走一遍安装流程确认安装目录下的 IL2CPP 文件被正确替换。报错三YooAsset 下载资源 404。检查 CDN 地址配置确认远端服务器上的资源版本文件和 Bundle 文件都上传了。YooAsset 的版本文件命名有规则上传时不要改名字。6.2 性能相关的注意事项热更代码因为是解释执行性能比 AOT 代码差一些。所以性能敏感的逻辑不要放热更比如每帧执行的角色移动计算、物理模拟、大量循环的数值计算。这些放 AOT 层热更层只做逻辑调度和状态管理。另外热更代码和 AOT 代码之间的调用虽然 HybridCLR 做了优化但频繁跨程序集调用还是有开销。我的做法是减少跨程序集的调用次数比如热更层一次性把数据准备好传给 AOT 层批量处理而不是每帧多次调用。6.3 开发流程上的经验开发期一定要用 YooAsset 的EditorSimulateMode改代码和资源立刻生效不用打包。只有出包测试和上线才用真打包模式。这样能把迭代效率提上来。热更程序集的划分要提前规划好不要等代码写了一大堆再拆。拆程序集的时候循环依赖是最头疼的问题提前规划能避免。每次热更前先在本地用真机跑一遍完整的下载和加载流程确认没问题再上传 CDN。我见过好几次是本地模拟模式没问题真机联机模式因为网络或者路径问题挂掉的。问题现象可能原因排查方向启动卡加载界面下载超时或失败检查 CDN 地址和网络热更代码不生效DLL 没更新或没加载检查 DLL 版本和加载日志报类型找不到补充元数据缺失检查 AOT 元数据加载列表包体异常增大Bundle 粒度太细调整打包策略内存占用高资源没释放检查卸载逻辑7. 从基础到进阶的下一步基础篇把整套流程跑通之后接下来可以往几个方向深入。一个是资源加载的异步化和预加载策略怎么在场景切换时平滑加载怎么避免卡顿一个是热更代码的调试HybridCLR 支持在编辑器里直接调试热更代码配好之后断点调试和普通代码一样还有一个是多平台适配安卓、iOS、小游戏平台在热更上的差异和注意事项。我自己在实际项目里最大的体会是热更新这套东西搭起来不难难的是稳定。真正上线之后网络波动、CDN 故障、玩家设备差异各种情况都会遇到。所以启动流程的容错、日志上报、灰度发布这些工程化的东西比技术本身更值得花时间。先把基础跑通再一步步把这些保障加上去项目才能稳。