1. 为什么2026年还要死磕YooAsset加HybridCLR这套组合
如果你是从Unity 2018、2019那个年代一路走过来的开发者，大概率经历过用AssetBundle手写依赖管理、自己维护版本清单、热更代码靠反射或者Lua桥接的苦日子。那个阶段能跑通一套热更流程的人，基本都算团队里的“基建大佬”。但到了2026年，Unity的生态已经发生了很大变化，再抱着老一套AB包管理思路不放，维护成本会高到让你怀疑人生。
这套YooAsset加HybridCLR的组合，本质上解决的是两个层面的问题。YooAsset管的是资源热更，也就是美术资源、配置表、预制体这些东西怎么在不重新发版的情况下更新到玩家手机上；HybridCLR管的是代码热更，也就是C#逻辑本身怎么绕过IL2CPP的AOT限制，实现真正的热更新。两者配合起来，才是一套完整的、能上生产环境的热更方案。
我之所以说“2026最新版”这个时间点值得单独拿出来讲，是因为HybridCLR从最初的实验性方案，到现在已经迭代得相当稳定，社区案例也足够多了。YooAsset同样从1.x走到了2.x，API和设计理念都有调整。网上很多教程还是基于老版本写的，你照着做大概率会踩坑。这篇文章我会把基础篇该讲的东西全部铺开，从环境搭建到第一个可运行的热更Demo，把每个环节的“为什么”和“怎么做”都讲透。
适合谁看？如果你已经会写C#、用过Unity的基本功能，但对热更只有模糊概念，或者之前用过其他方案但想迁移到这套组合，那这篇就是给你准备的。纯小白也能看，但至少要能看懂C#代码和Unity的基本操作。
2. 热更方案选型背后的逻辑与核心概念拆解
2.1 为什么是YooAsset而不是Addressable
Unity官方其实有自己的资源热更方案Addressable，功能也很强。但实际项目里选YooAsset的团队越来越多，原因很现实。Addressable的底层还是AssetBundle，但它的配置界面和运行时API对国内团队来说有几个不太顺手的地方。比如它的Group配置在大型项目里容易变得混乱，远程加载的Catalog更新机制在弱网环境下表现不够稳定，而且和国内常见的CDN分发流程配合时需要额外做不少适配工作。
YooAsset的设计思路更贴近国内项目的实际需求。它把资源分成若干Package，每个Package可以独立配置更新策略，支持单机模式和联机模式切换。最关键的是它的版本管理机制非常清晰，Manifest文件的对比和增量下载逻辑写得很直白，你出问题的时候能快速定位到是哪一步卡住了。另外YooAsset的社区在国内非常活跃，遇到问题搜一下基本都能找到答案，这对中小团队来说太重要了。
还有一个容易被忽略的点：YooAsset对HybridCLR的兼容是官方级别的。它的代码里直接考虑了热更程序集的加载顺序问题，你不需要自己写一堆胶水代码去协调资源加载和代码加载的时序。这一点在Addressable上就要自己处理，容易出玄学Bug。
2.2 HybridCLR到底解决了什么问题
要理解HybridCLR的价值，得先知道IL2CPP的限制。Unity在打包时会把C#代码通过IL2CPP转换成C++再编译成原生代码，这个过程是AOT（提前编译）的。AOT的好处是运行效率高，但坏处是代码在打包后就固定了，你没法在运行时动态加载新的C#代码。传统的热更方案要么用Lua这种解释型语言重写逻辑，要么用反射加动态编译，但后者在iOS上基本走不通。
HybridCLR的思路很巧妙。它扩展了IL2CPP的运行时，让AOT部分和解释执行部分可以混合工作。简单说，它给IL2CPP加了一个“解释器”，那些需要热更的代码以DLL的形式存在，运行时由这个解释器来执行。不需要热更的代码还是走AOT，性能不受影响。这样你就能在iOS和Android上都能实现C#代码的热更新，而且性能比纯Lua方案好很多，因为大部分底层逻辑还是原生代码在跑。
这里有个关键概念叫“补充元数据”。AOT程序集在打包时会被裁剪，一些泛型实例化和反射用到的元数据可能丢失。HybridCLR需要你在打包时额外生成这些元数据并随包发布，运行时再加载进来，这样热更代码才能正确访问AOT里的类型。这个机制是HybridCLR能稳定工作的基石，基础篇里必须把它搞清楚。
2.3 资源热更和代码热更的时序关系
这是很多新手最容易搞混的地方。资源热更和代码热更不是独立的，它们有严格的先后顺序。正确的流程是：游戏启动后先检查资源版本，下载并更新资源清单，然后根据清单里的信息确定需要加载哪些热更程序集，接着加载这些程序集的元数据，最后才是加载热更DLL并执行入口逻辑。
为什么是这个顺序？因为热更DLL本身也是资源，它需要通过YooAsset下载下来。而DLL要能被HybridCLR正确加载，又依赖于补充元数据先到位。所以整个链条是：资源系统初始化→版本检查→下载更新→加载元数据→加载热更DLL→执行热更逻辑。任何一步顺序错了，都会导致加载失败或者运行时报错。
我在实际项目里见过有人把热更DLL直接放在StreamingAssets里不走YooAsset，结果版本管理混乱，回滚都回不去。基础篇虽然不涉及复杂的版本回滚策略，但这个时序概念必须从一开始就建立正确。
3. 环境搭建与项目初始化的完整实操
3.1 Unity版本和必要插件的选择
Unity版本建议用2022.3 LTS或者Unity 6的LTS版本。2022.3是目前最稳的长期支持版，HybridCLR和YooAsset对它支持都很好。Unity 6也可以，但要注意有些第三方插件可能还没完全适配。千万别用2019或者2020的老版本，HybridCLR的新特性用不了，而且IL2CPP的bug也比较多。
需要的插件就两个：YooAsset和HybridCLR。YooAsset可以直接从GitHub的Release页面下载unitypackage，或者用UPM的方式添加。HybridCLR推荐用它的Installer来安装，因为涉及到IL2CPP源码的修改，手动搞容易出错。安装HybridCLR后，菜单栏会多出一个HybridCLR的选项，里面有Installer和Settings。
这里有个坑要注意：HybridCLR的Installer会修改Unity安装目录下的IL2CPP源码。如果你用的是Unity Hub管理的多版本Unity，确保你对当前项目使用的那个版本执行Installer。装完之后最好重启一下Unity，让所有修改生效。
3.2 项目目录结构的规划
在动手写代码之前，先把目录结构规划好，后面会省很多事。我习惯这样分：
Assets/Res：存放所有需要热更的资源，比如预制体、贴图、配置表。这个目录下的内容会被YooAsset收集。Assets/HotUpdate：存放热更代码的工程，独立一个asmdef，不参与主包编译。Assets/Main：主包代码，包括启动逻辑、YooAsset初始化、HybridCLR初始化。Assets/StreamingAssets：存放首包资源，YooAsset的Builtin模式会用到。
热更代码一定要用asmdef隔离出来，并且这个asmdef不能被打进主包。具体做法是在asmdef的配置里把Platforms勾选去掉，或者用HybridCLR提供的工具来标记。这样打包时主包不会包含热更代码，热更DLL由YooAsset单独管理。
3.3 HybridCLR的初始化配置
安装完HybridCLR后，打开HybridCLR/Settings面板。这里有几个关键配置：
Enable HybridCLR：勾上，这是总开关。Hot Update Assemblies：把你热更代码的asmdef名字填进去，比如HotUpdate。AOT Assemblies：一般保持默认，它会自动把Unity引擎和常用库加进去。
然后需要生成补充元数据。在HybridCLR菜单里找到Generate All，它会做几件事：生成桥接函数、生成AOT泛型元数据、生成裁剪后的AOT DLL。这些文件会输出到你指定的目录，通常放在StreamingAssets下，随包发布。
注意：每次修改了AOT部分的代码或者升级了Unity版本，都要重新Generate All。否则热更代码可能找不到对应的元数据，运行时报
ExecutionEngineException。
3.4 YooAsset的初始化与资源模式选择
YooAsset支持三种运行模式：EditorSimulateMode、OfflinePlayMode、HostPlayMode。开发阶段用EditorSimulateMode，不需要打包就能模拟资源加载，速度最快。测试和正式包用HostPlayMode，支持从远程服务器下载资源。OfflinePlayMode是单机模式，所有资源都在包里，不联网更新。
初始化代码大概长这样：
private IEnumerator InitializeYooAsset() { var package = YooAssets.CreatePackage("DefaultPackage"); YooAssets.SetDefaultPackage(package); var initParams = new HostPlayModeParameters(); initParams.BuildinQueryServices = new GameQueryServices(); initParams.RemoteServices = new RemoteServices(); 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) { Debug.LogError("Update version failed: " + versionOp.Error); yield break; } string packageVersion = versionOp.PackageVersion; var manifestOp = package.UpdatePackageManifestAsync(packageVersion); yield return manifestOp; if (manifestOp.Status != EOperationStatus.Succeed) { Debug.LogError("Update manifest failed: " + manifestOp.Error); yield break; } // 接下来创建下载器，下载所有需要更新的资源 var downloader = package.CreateResourceDownloader(10, 3); if (downloader.TotalDownloadCount > 0) { downloader.BeginDownload(); yield return downloader; } // 资源更新完成，开始加载热更DLL StartCoroutine(LoadHotUpdateAssemblies()); }这段代码里，GameQueryServices和RemoteServices需要你自己实现，分别告诉YooAsset去哪里找内置资源和远程资源。GameDecryptionServices是可选的，如果你对资源做了加密就需要实现它。
4. 热更程序集的加载与执行全流程
4.1 补充元数据的加载顺序
资源更新完成后，第一件事是加载补充元数据。这些元数据文件是之前Generate All生成的，通常是一堆DLL文件，放在StreamingAssets或者通过YooAsset下载。加载顺序很重要，必须先加载AOT元数据，再加载热更DLL。
private IEnumerator LoadMetadataForAOT() { // 这些DLL名字是Generate All时生成的，具体名字看你的配置 string[] aotMetadataList = new string[] { "mscorlib.dll.bytes", "System.dll.bytes", "System.Core.dll.bytes", // ... 其他需要补充元数据的AOT程序集 }; foreach (var metadata in aotMetadataList) { var handle = YooAssets.LoadAssetAsync<TextAsset>(metadata); yield return handle; var textAsset = handle.AssetObject as TextAsset; if (textAsset != null) { HybridCLR.RuntimeApi.LoadMetadataForAOTAssembly( textAsset.bytes, HomologousImageMode.SuperSet ); } handle.Release(); } }HomologousImageMode.SuperSet是推荐模式，它会把补充元数据和AOT程序集做超集合并，兼容性最好。如果你用Consistent模式，要求补充元数据和AOT程序集的版本完全一致，容易出问题。
4.2 热更DLL的加载与入口调用
元数据加载完后，就可以加载热更DLL了。热更DLL也是通过YooAsset加载，拿到bytes后直接调用Assembly.Load。
private IEnumerator LoadHotUpdateAssemblies() { yield return LoadMetadataForAOT(); string[] hotUpdateDlls = new string[] { "HotUpdate.dll.bytes", // 如果有多个热更程序集，都列在这里 }; foreach (var dllName in hotUpdateDlls) { var handle = YooAssets.LoadAssetAsync<TextAsset>(dllName); yield return handle; var textAsset = handle.AssetObject as TextAsset; if (textAsset != null) { Assembly.Load(textAsset.bytes); } handle.Release(); } // 所有热更DLL加载完毕，调用入口方法 InvokeHotUpdateEntry(); } private void InvokeHotUpdateEntry() { // 通过反射找到热更代码里的入口类和方法 var entryType = System.Type.GetType("HotUpdate.GameEntry, HotUpdate"); if (entryType != null) { var method = entryType.GetMethod("Start", System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static); method?.Invoke(null, null); } else { Debug.LogError("HotUpdate entry type not found!"); } }这里有个细节：热更DLL的名字必须和asmdef的名字一致，而且加载时用的名字要和Generate All时配置的一致。如果你改了asmdef名字但忘了重新Generate All，运行时会找不到类型。
4.3 热更代码的编写规范
热更代码不是随便写的，有一些限制必须遵守。首先，热更代码不能直接引用主包里没有的类型，除非那个类型在AOT元数据里有补充。其次，热更代码里用到的泛型实例化，如果AOT部分没有对应的实例化，需要手动在AOT代码里写一个“占位”来触发编译。
比如你在热更代码里用了List<MyCustomType>，但AOT部分从来没出现过这个组合，IL2CPP裁剪时就不会生成对应的代码。解决办法是在AOT代码里加一个静态方法，里面写一句var list = new List<MyCustomType>();，但这个方法永远不会被调用，只是为了骗过编译器。
实操心得：我习惯在AOT部分建一个
AOTGenericReferences类，把所有热更代码可能用到的泛型组合都列一遍。虽然丑，但能避免很多运行时崩溃。
另外，热更代码里不要用async/await的某些高级特性，HybridCLR对Task的支持在早期版本有些限制，虽然现在好多了，但基础篇阶段建议先用协程或者简单的回调，减少变量。
5. 常见问题排查与避坑经验实录
5.1 加载失败类问题速查
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
Assembly.Load返回null | DLL bytes为空或格式错误 | 检查YooAsset是否成功下载，用十六进制工具看文件头是否是MZ |
| 找不到热更类型 | asmdef名字和DLL名字不一致 | 确认Generate All时的配置和运行时加载的名字完全一致 |
ExecutionEngineException | 补充元数据缺失 | 检查AOT元数据是否全部加载，特别是泛型相关的 |
| iOS上崩溃 | AOT裁剪过度 | 在link.xml里保留需要的类型，或者用HybridCLR的AOT参考生成 |
| 热更代码修改后不生效 | 旧DLL被缓存 | 清理YooAsset的缓存目录，或者修改版本号强制更新 |
5.2 打包时的注意事项
打包前一定要做这几件事：先Generate All，再Build YooAsset资源，最后Build Player。顺序错了会导致元数据和资源不匹配。Build YooAsset时，注意选择正确的构建模式，首包资源用Builtin，热更资源用Remote。
Android打包时，如果用了IL2CPP，确保Strip Engine Code不要设成High，否则容易把HybridCLR需要的代码裁掉。iOS打包时，Managed Stripping Level建议用Low或者Minimal，配合link.xml来精确控制裁剪。
还有一个坑：Unity 2022之后的版本默认开启了Incremental GC，HybridCLR在某些情况下和它配合会有问题。如果遇到莫名其妙的GC崩溃，可以试试在Player Settings里关掉Incremental GC。
5.3 调试技巧与日志排查
HybridCLR的报错信息有时候很隐晦，比如只告诉你“找不到方法”但不说是哪个。这时候可以打开HybridCLR的详细日志开关，在Settings里把Log Level调到Debug。另外，在加载元数据和DLL的每一步都打上日志，记录加载了哪些文件、耗时多少、是否成功。这样出问题的时候能快速定位到是哪一步。
我自己的习惯是在热更代码的入口方法第一行就写一句Debug.Log("[HotUpdate] Entry called")，如果这行日志没出来，说明DLL加载或入口调用有问题；如果出来了但后续逻辑不对，那就是热更代码本身的Bug。这个简单的技巧能帮你省很多排查时间。
最后分享一个我踩过的坑：有一次热更后游戏黑屏，查了半天发现是热更DLL里引用了主包的一个ScriptableObject类型，但这个类型在AOT元数据里没有补充。解决办法是在AOT代码里加一个该类型的引用，重新Generate All。所以记住，热更代码和主包代码的边界一定要清晰，跨边界引用类型时务必确认元数据是否完整。
