1. 为什么小游戏项目必须做热更从一次线上事故说起去年年底我接手了一个休闲小游戏项目玩法不复杂核心逻辑就是合成关卡推进团队四个人工期两个月。上线第一周数据还不错结果第三关有个道具的数值配错了导致玩家可以无限刷金币。这个问题如果走传统发版流程从提审到用户真正更新安卓渠道快的话一天iOS加上审核周期至少两三天等版本铺开的时候经济系统已经被冲烂了。那次事故之后我把热更方案彻底重做了一遍最终落地的组合就是YooAsset 管资源 HybridCLR 管代码。这套方案在小游戏场景下特别合适原因很直接小游戏包体限制严格首包必须小玩法迭代快策划改数值、改配置不能等发版代码逻辑也经常要修纯资源热更覆盖不了 C# 逻辑的改动。这篇文章我会把整套方案从选型、搭建、实操到踩坑完整讲一遍。适合正在做 Unity 小游戏、准备接入热更、或者已经接了但被各种报错折磨的开发者。哪怕你之前没接触过 YooAsset 和 HybridCLR跟着走也能把双更新跑通。先说清楚这套方案解决的核心问题资源预制体、贴图、配置、音频和代码C# 逻辑都能在不重新发版的前提下更新。资源部分靠 YooAsset 做打包、分发、加载代码部分靠 HybridCLR 做补充元数据 热更程序集加载。两者配合才能做到真正的双更新。2. 方案选型为什么是 YooAsset HybridCLR 而不是别的2.1 资源热更为什么放弃 Addressable 选 YooAssetUnity 官方有 Addressable功能很全但我实测下来在小游戏场景有几个不舒服的点。第一是包体Addressable 依赖的库比较重对首包体积敏感的小游戏不太友好。第二是构建速度资源多了之后 Build 一次要等很久迭代节奏被打断。第三是它的 Catalog 机制在弱网环境下加载体验一般小游戏用户网络波动大这点很致命。YooAsset 是国内团队做的设计目标就是轻量和高效。它的资源清单是二进制格式加载快支持多种运行模式编辑器模拟、单机、联机开发期不用每次打包分包策略灵活可以按标签、按目录、按资源类型分。最关键的是它对小游戏平台的适配做得比较到位微信小游戏、抖音小游戏这些平台都有现成的处理。我对比过两者的构建产物同样一批资源YooAsset 打出来的包体通常比 Addressable 小 10% 到 20%这个差距在小游戏首包限制下很关键。2.2 代码热更为何锁定 HybridCLR代码热更的方案市面上有几类Lua 系xLua、ToLua、ILRuntime、HybridCLR。Lua 系需要把逻辑用 Lua 重写团队要学新语言而且和 C# 交互有性能损耗。ILRuntime 是解释执行 IL性能比原生差不少复杂逻辑会卡。HybridCLR 走的是另一条路——它把热更程序集在运行时转成原生代码执行性能接近 AOT 编译的代码同时保留 C# 的开发体验。HybridCLR 的核心原理是补充元数据Supplementary Metadata加解释器与 AOT 混合执行。简单说AOT 主包里没有的泛型实例化、被裁剪的元数据通过补充元数据的方式在运行时补齐然后热更 DLL 就能正常加载执行。它不需要你改语言C# 照写这对团队来说学习成本几乎为零。注意HybridCLR 对 Unity 版本有要求建议 2020.3.36 以上2021.3 LTS 和 2022.3 LTS 是验证最充分的。太老的版本可能缺少必要的 API 支持。2.3 两者组合的协同关系很多人会误以为资源热更和代码热更是两件独立的事其实它们必须协同。热更代码里引用的预制体、配置表都要通过 YooAsset 加载而 YooAsset 的加载逻辑本身可能也需要热更。所以正确的做法是主包里放最小可运行的启动逻辑 YooAsset 运行时 HybridCLR 运行时启动后先检查资源版本再检查代码版本两者都更新完再进入游戏。这个顺序不能反。如果先加载热更代码但代码里依赖的资源还没更新就会报资源找不到。我踩过这个坑后面会详细讲。3. 环境搭建与工程结构设计3.1 版本与依赖清单我用的这套组合经过多个项目验证稳定性不错组件版本说明Unity2022.3.20f1 LTS长期支持版HybridCLR 适配完善YooAsset2.1.x2.x 版本 API 更稳定HybridCLR6.x与 Unity 2022 匹配目标平台微信小游戏 / 抖音小游戏本文以微信小游戏为主安装 HybridCLR 推荐用它的 Installer在 Package Manager 里添加 Git URL 后通过菜单HybridCLR/Installer一键安装它会自动处理 il2cpp 的裁剪和配置。手动装容易漏步骤尤其是link.xml和裁剪相关的设置。YooAsset 直接通过 Package Manager 添加即可注意选 2.x 分支1.x 和 2.x 的 API 差异较大网上很多老教程是 1.x 的照抄会报错。3.2 工程目录怎么划分目录结构直接影响打包和热更的清晰度我习惯这样分Assets/ Main/ # 主包内容不参与热更 Scripts/ Launch/ # 启动逻辑 Runtime/ # YooAsset、HybridCLR 运行时封装 Scenes/ Launch.unity # 启动场景 HotUpdate/ # 热更内容 Scripts/ # 热更代码编译成 DLL Res/ # 热更资源 Prefabs/ Configs/ Textures/ HybridCLRGenerate/ # HybridCLR 生成的补充元数据关键原则主包只放启动必需的东西其余全部丢进 HotUpdate。主包越小首包体积越可控热更覆盖范围越大。3.3 程序集划分的关键操作HybridCLR 要求热更代码必须放在独立的程序集里不能和主包代码混在一起。操作步骤在HotUpdate/Scripts下创建HotUpdate.asmdef命名比如Game.HotUpdate。主包代码放在另一个 asmdef比如Game.Main。在Game.Main的 asmdef 里不要引用Game.HotUpdate否则会被打进主包。热更程序集可以引用主包程序集反过来不行。这一步做错的话热更 DLL 会被误打进主包热更就失效了。判断方法打包后看主包的Assembly-CSharp.dll或对应程序集里有没有热更代码的类。提示HybridCLR 的 Settings 面板里要配置HotUpdateAssemblies把Game.HotUpdate加进去这样它才会被识别为热更程序集不参与 AOT 编译。4. YooAsset 资源热更的完整实操4.1 资源打包模式与清单配置YooAsset 有三种运行模式开发期和上线期用法不同EditorSimulateMode编辑器下直接读 AssetDatabase不用打包改资源立刻生效开发期用这个。OfflinePlayMode单机模式资源全在包内适合不需要热更的纯单机。HostPlayMode联机模式从 CDN 或服务器拉资源热更就用这个。上线配置里HostPlayMode需要设置IRemoteServices也就是资源服务器地址。小游戏平台通常用平台自己的 CDN微信小游戏可以用云开发的文件存储。打包时在 YooAsset 的 Build 面板里配置Package Name包名比如DefaultPackage。Build Pipeline选BuiltinBuildPipeline或ScriptableBuildPipeline后者更灵活。Compress Option小游戏建议LZ4压缩率和解压速度平衡好。Output Path输出目录注意区分本地和远程。4.2 资源版本与清单的更新流程YooAsset 的更新流程分几步我按实际代码顺序讲// 1. 初始化 Package var package YooAssets.CreatePackage(DefaultPackage); var initParams new HostPlayModeParameters { BuildinQueryServices new GameQueryServices(), RemoteServices new RemoteServices(defaultHostServer, fallbackHostServer) }; var initOp package.InitializeAsync(initParams); yield return initOp; // 2. 获取资源版本 var versionOp package.UpdatePackageVersionAsync(); yield return versionOp; string packageVersion versionOp.PackageVersion; // 3. 获取资源清单 var manifestOp package.UpdatePackageManifestAsync(packageVersion); yield return manifestOp; // 4. 创建下载器并下载 var downloader package.CreateResourceDownloader(10, 3); if (downloader.TotalDownloadCount 0) { downloader.BeginDownload(); yield return downloader; }这里有几个参数要解释。CreateResourceDownloader(10, 3)里的 10 是并发下载数3 是失败重试次数。小游戏平台并发太高容易被限流我一般设 6 到 10。重试次数设 3 比较稳网络抖动时能自动恢复。UpdatePackageVersionAsync会去服务器拉一个版本文件里面记录了当前最新的资源版本号。如果版本号和本地一致说明没有更新直接跳过下载。这个机制保证了每次启动不会重复下载。4.3 资源加载与释放的正确姿势加载资源用package.LoadAssetAsyncT(location)location 是资源的地址可以在打包时配置。我习惯用资源路径作为地址直观好维护。var handle package.LoadAssetAsyncGameObject(Prefabs/Enemy); yield return handle; var prefab handle.AssetObject as GameObject; Instantiate(prefab); // 用完记得释放 handle.Release();释放这块是重灾区。YooAsset 的 handle 必须成对释放加载了不释放内存会一直涨。我见过项目因为没释放玩十分钟内存爆掉。建议封装一层资源管理器统一管理 handle 的生命周期场景切换时批量释放。注意LoadAssetAsync返回的 handle 如果被多个地方引用要确保每个引用方都 Release或者用引用计数管理。直接 Release 一次就销毁其他引用方会拿到空对象。5. HybridCLR 代码热更的核心实现5.1 补充元数据的生成与加载HybridCLR 最关键的一步是补充元数据。AOT 主包在编译时il2cpp 会裁剪掉一些没被直接引用的泛型实例化和元数据。热更代码里如果用到了这些被裁剪的部分运行时会报ExecutionEngineException或者找不到方法。解决办法是生成补充元数据 DLL在运行时加载。操作菜单HybridCLR/Generate/All它会生成补充元数据、裁剪后的 AOT 泛型等。生成的 DLL 放在HybridCLRGenerate目录需要打进热更资源里。运行时在加载热更程序集之前先加载这些补充元数据。// 加载补充元数据 foreach (var dllName in aotMetaDlls) { var handle package.LoadRawFileAsync(dllName); yield return handle; byte[] dllBytes handle.GetRawFileData(); RuntimeApi.LoadMetadataForAOTAssembly(dllBytes, HomologousImageMode.SuperSet); handle.Release(); }HomologousImageMode.SuperSet是推荐模式兼容性最好。这一步必须在加载热更 DLL 之前完成顺序错了会直接崩。5.2 热更程序集的加载与反射调用补充元数据加载完就可以加载热更 DLL 了var handle package.LoadRawFileAsync(Game.HotUpdate.dll.bytes); yield return handle; byte[] dllBytes handle.GetRawFileData(); var assembly Assembly.Load(dllBytes); // 反射调用入口 var type assembly.GetType(Game.HotUpdate.GameEntry); var method type.GetMethod(Start); method.Invoke(null, null);热更 DLL 打包时要注意Unity 编译出来的 DLL 是Game.HotUpdate.dll但小游戏平台加载时通常需要加.bytes后缀避免被平台当成可执行文件拦截。YooAsset 打包时把 DLL 当二进制资源处理加载用LoadRawFileAsync。反射调用入口只做一次进去之后热更代码内部就可以正常互相调用了。入口方法建议做成静态无参的简单可靠。5.3 热更代码里如何引用主包类型热更代码可以引用主包里的类比如主包的ResourceManager、EventSystem这些。但要注意主包里的类如果被裁剪了热更代码调用时会找不到。解决办法是在主包里保留一个link.xml把需要被热更代码引用的类型和命名空间标记为不裁剪。linker assembly fullnameGame.Main type fullnameGame.Main.ResourceManager preserveall/ type fullnameGame.Main.EventDispatcher preserveall/ /assembly /linker这个文件放在Assets下任意位置即可il2cpp 编译时会读取。漏配的话编辑器里跑得好好的真机上就报TypeLoadException这个坑我踩过不止一次。6. 双更新的启动流程编排6.1 启动时序的完整设计把资源和代码的更新串起来启动流程是这样的初始化 YooAsset Package。检查资源版本下载资源更新。加载补充元数据 DLL。加载热更程序集 DLL。反射调用热更入口进入游戏逻辑。这个顺序是硬性的。第 2 步必须在第 3、4 步之前因为补充元数据和热更 DLL 本身也是资源要通过 YooAsset 下载。第 3 步必须在第 4 步之前否则热更 DLL 里的泛型会崩。6.2 版本比对与增量更新策略每次启动都全量下载肯定不行要做增量。YooAsset 的清单机制天然支持增量UpdatePackageManifestAsync会对比本地和远程清单只下载差异部分。代码这边我给热更 DLL 加一个版本号存在配置里版本变了才重新下载 DLL。string localCodeVersion PlayerPrefs.GetString(CodeVersion, 0); string remoteCodeVersion GetRemoteCodeVersion(); // 从版本文件读 if (localCodeVersion ! remoteCodeVersion) { // 下载新的热更 DLL // 更新本地版本号 PlayerPrefs.SetString(CodeVersion, remoteCodeVersion); }这样大部分启动只更新资源代码没变就不下载 DLL节省流量和时间。6.3 断点续传与失败重试小游戏网络环境差下载中断是常态。YooAsset 的下载器支持断点续传但需要你的RemoteServices正确实现GetDownloadUrl和文件校验。我建议在下载失败时给用户一个明确的提示并提供重试按钮而不是静默失败。重试策略上我做的是单文件失败重试 3 次整体下载失败后允许用户手动重试重试时从已下载的部分继续。实测下来弱网环境下这套策略能把下载成功率从 70% 提到 95% 以上。7. 避坑清单我踩过的那些坑7.1 资源与代码更新顺序错乱最常见的坑先加载热更代码代码里引用了新资源但资源还没下载完直接报资源找不到。必须严格按资源→元数据→代码的顺序。我在启动流程里加了状态机每个阶段完成才进下一个杜绝并发导致的顺序问题。7.2 泛型实例化缺失导致的崩溃热更代码里用了ListCustomType这种泛型如果CustomType在主包里没被任何 AOT 代码引用过il2cpp 会裁剪掉这个泛型实例化运行时直接崩。解决办法有两个一是在主包里写一个占位方法强制引用这些泛型二是靠补充元数据补齐。我一般两个都做双保险。7.3 小游戏平台的 DLL 加载限制微信小游戏对动态加载 DLL 有安全限制直接Assembly.Load可能被拦截。HybridCLR 官方提供了针对小游戏平台的适配需要开启对应的宏和配置。具体是在 HybridCLR Settings 里勾选目标平台它会生成平台专用的加载代码。没开这个的话编辑器正常真机报错。7.4 裁剪配置遗漏link.xml漏配是高频问题。除了主包类型还要注意 Unity 自身的一些类型比如System.Collections.Generic下的某些泛型。我的做法是先在 Development Build 下跑看有没有TypeLoadException有就补进link.xml反复几轮直到干净。7.5 内存泄漏与 handle 未释放前面提过YooAsset 的 handle 不释放会内存泄漏。我封装了一个AssetHandleManager所有加载都走它场景切换时统一释放。另外热更 DLL 加载后Assembly对象本身占内存如果频繁热更要注意旧 Assembly 的释放不过一般一个版本内不会重复加载问题不大。坑点现象解决顺序错乱资源找不到状态机控制顺序泛型缺失ExecutionEngineException占位引用 补充元数据DLL 加载被拦真机崩溃开启平台适配宏裁剪遗漏TypeLoadException补 link.xmlhandle 未释放内存持续上涨统一管理器释放8. 性能与包体优化的实战经验8.1 首包体积怎么压到最小小游戏首包限制通常在 4MB 到 20MB 之间具体看平台。压缩策略主包只放启动场景和启动脚本其余全热更。贴图用 ASTC 或 ETC2 压缩小游戏平台优先 ASTC。音频用 MP3 或 OGG不要用 WAV。代码开启 il2cpp 的Managed Stripping Level为 High配合link.xml保底。移除未使用的 Unity 模块比如物理、动画如果不用就裁掉。我实测过一个中等复杂度的小游戏优化前首包 15MB优化后能压到 6MB 左右。8.2 热更下载速度优化下载速度取决于并发数和资源大小。并发数不是越高越好小游戏平台一般限制单域名并发设太高反而被限流。我一般设 6 到 8。资源方面把大文件拆小比如一张 2048 的图拆成几张 1024下载时能并行整体更快。另外CDN 的选择很关键。用平台自带的 CDN 通常比自建快因为节点离用户近。微信小游戏用云开发存储抖音用它的对象存储都是优化过的。8.3 运行时性能监控热更代码执行性能和 AOT 接近但反射调用入口那一下有开销所以入口只调一次。运行时要监控帧率、内存、GC。我习惯在 Development Build 下开 Profiler重点看热更代码有没有频繁 GC Alloc。HybridCLR 的解释执行部分如果被频繁调用会有额外开销热点逻辑尽量放在 AOT 侧或者优化成不触发解释器的形式。9. 上线后的维护与迭代建议9.1 灰度发布怎么做热更最大的优势是可以灰度。我的做法是资源版本和代码版本都支持按用户 ID 或渠道分流。比如先给 10% 用户推新版本观察崩溃率和关键指标没问题再全量。YooAsset 的RemoteServices可以根据用户信息返回不同的资源地址实现分流。9.2 回滚机制热更出问题要能快速回滚。资源方面保留上一个版本的清单和文件出问题切回旧版本地址即可。代码方面热更 DLL 也保留旧版本版本号回退就加载旧的。关键是版本文件要能动态改不要写死在包里。9.3 监控与告警上线后要监控热更的成功率、下载耗时、崩溃率。我在关键节点埋了点启动开始、资源更新完成、代码加载完成、进入游戏。任何一个环节失败都上报后台能看到哪个版本、哪个环节出问题。这套监控帮我提前发现过好几次资源服务器配置错误。10. 一些零散但重要的实操心得热更这套东西文档看一遍觉得简单真上手全是细节。我最后再补几个零散但很关键的点。第一开发期一定要用 EditorSimulateMode改资源秒生效不要每次都打包否则迭代效率极低。打包只在提测和上线前做。第二热更 DLL 的编译要独立。我见过把热更代码和主包代码放一个 asmdef 的结果热更 DLL 里带了一堆主包代码包体暴涨还容易冲突。asmdef 划分清楚各管各的。第三测试热更流程要在真机跑。编辑器模拟和真机差异很大尤其是小游戏平台的文件系统和网络环境。我一般准备一个测试环境专门验证热更每次改动都跑一遍完整流程。第四版本号管理要规范。资源版本、代码版本、配置版本分开管理不要混在一起。我用一个version.json统一记录服务器和客户端都读这个文件避免版本对不上。第五补充元数据的 DLL 不要频繁变。它和 AOT 主包强相关主包不变的情况下补充元数据一般也不变。如果每次热更都重新生成可能导致和主包不匹配。我的做法是主包发版时才重新生成热更期间复用。这套 YooAsset HybridCLR 的组合我从去年用到现在经历了几个项目的上线和迭代稳定性是经得起考验的。刚开始接入会有点折腾尤其是补充元数据和裁剪那块但一旦跑通后续的迭代效率提升非常明显。策划改数值、程序修 bug当天就能推给用户不用再等发版周期。对于小游戏这种快节奏、重运营的品类热更能力基本是标配了。