Unity 热更新:主流方案、原理设计与 HybridCLR + YooAsset 实践
一、为什么需要热更新
热更新是指不重新安装应用,从服务器下载新的代码和资源,让游戏获得更新。
- 绕过审核周期:应用商店审核需要时间,而线上 Bug 往往需要当天修复。
- 降低更新成本:玩家不用重新下载整包,更新量小,流失少。
- 持续运营:活动、新角色、新关卡可以随时上线。
热更新分为两部分:
| 资源热更 | 代码热更 | |
|---|---|---|
| 内容 | 模型、贴图、Prefab、配置表、音频等 | 游戏逻辑 |
| 难点 | 打包策略、依赖管理、差异下载、内存管理 | 在不能动态加载代码的平台上运行新代码 |
| 方案 | AssetBundle、Addressables、YooAsset | Lua、ILRuntime、PuerTS、HybridCLR |
资源热更 Unity 原生就能做(AssetBundle)。真正的难点在代码热更。
二、代码为什么不能直接热更
Mono 与 IL2CPP
C# 代码先编译成 IL(中间语言)放在 dll 中,运行时有两种执行方式:
- Mono(JIT):运行时把 IL 即时编译成机器码。可以在运行时
Assembly.Load一个新的 dll,天然支持热更。 - IL2CPP(AOT):打包时把 IL 转成 C++,再编译成机器码。运行时没有 IL 也没有 JIT,所有代码在打包时就固定了,新的 dll 加载进来也没有东西能执行它。IL2CPP 的编译流程和限制见 IL2CPP 与打包。
而 IL2CPP 是现在的主流:
- iOS 禁止 JIT:系统不允许应用在运行时生成并执行新的机器码,只能用 AOT。
- Android 的 64 位要求:Google Play 要求支持 64 位,而 Unity 的 Mono 后端不支持 ARM64,只能用 IL2CPP。
- IL2CPP 的运行性能也比 Mono 好。
所以在 IL2CPP 下热更代码,只剩一条路:解释执行。新代码不编译成机器码,而是由一个已经存在于包体中的解释器逐条读取执行。所有代码热更方案的区别,就在于”解释什么语言”和”解释器怎么和原有的 C# 代码交互”。
关于平台政策:苹果审核指南允许应用下载并执行解释型代码,前提是不改变应用的主要用途、不绕过审核去提供未经审核的功能。具体以最新的审核指南为准。
三、代码热更方案
Lua 系:xLua、toLua、sLua
原理:包体中嵌入 Lua 虚拟机(C 语言实现),热更的逻辑用 Lua 编写。Lua 脚本就是文本或字节码,可以像资源一样下载。C# 和 Lua 之间通过绑定层互相调用:为 C# 类型生成导出代码(Wrap),Lua 通过它访问 C# 对象。
- xLua(腾讯):目前 Lua 方案中最常用的。特色是 Hotfix:可以用 Lua 替换 C# 中已有方法的实现,用于修复线上 C# 代码的 Bug。原理是打包时向标记的 C# 方法注入 IL 代码,运行时检查是否有对应的 Lua 补丁。
- toLua、sLua:较早的方案,社区活跃度已不如 xLua。
Lua 本身的知识(元表、面向对象、GC、弱表)以及 xLua 交互的注意事项,见 Lua 核心知识。
| 优点 | 缺点 |
|---|---|
| 成熟稳定,大量上线项目验证 | 两种语言,团队要同时维护 C# 和 Lua |
| Lua 虚拟机小、解释执行快 | 跨语言调用有开销:参数转换、GC,频繁交互时明显 |
| 热更范围大,业务逻辑基本都能写在 Lua 中 | 动态类型,编译期发现不了错误,调试、重构困难 |
| C# 与 Lua 之间相互引用容易造成内存泄漏 |
PuerTS
原理:腾讯开源,嵌入 JavaScript 引擎(V8、QuickJS 等),业务逻辑用 TypeScript 编写,编译成 JS 后作为资源热更。
- 优点:TypeScript 有静态类型检查,开发体验比 Lua 好;JS 生态丰富。
- 缺点:同样是两种语言、跨语言调用有开销;V8 体积较大。
ILRuntime
原理:用 C# 实现了一个 IL 解释器。热更代码依然用 C# 编写,编译成 dll 后作为资源下载,由 ILRuntime 在运行时解释执行其中的 IL。
- 优点:只用 C# 一种语言。
- 缺点:
- 热更代码中的类型不是真正的 CLR 类型,而是 ILRuntime 自己模拟的类型实例。所以热更代码继承主工程的类或实现主工程的接口时,需要编写适配器(跨域继承)。
- 主工程调用热更代码、委托跨域传递都需要注册和转换。
- 性能一般,频繁调用 Unity API 需要生成 CLR 绑定代码来避免反射。
随着 HybridCLR 的出现,新项目已经很少选择 ILRuntime。
HybridCLR
原理:不是另外实现一个虚拟机,而是直接扩展 IL2CPP 的运行时,给它加上一个 IL 解释器。热更 dll 加载后,其中的类型和 AOT 编译的类型一样,是 IL2CPP 运行时中真正的类型,只是方法由解释器执行。
这带来的结果是:热更代码和主工程代码之间几乎没有边界,继承、接口、泛型、委托、反射都可以直接用,不需要适配器。后文详细介绍。
方案对比
| xLua | PuerTS | ILRuntime | HybridCLR | |
|---|---|---|---|---|
| 热更语言 | Lua | TypeScript / JS | C# | C# |
| 实现方式 | 嵌入 Lua 虚拟机 | 嵌入 JS 引擎 | C# 写的 IL 解释器 | 扩展 IL2CPP 运行时 |
| 与主工程交互 | 绑定层,有转换开销 | 绑定层,有转换开销 | 跨域需要适配器 | 无缝,类型是原生类型 |
| C# 特性支持 | - | - | 部分受限 | 几乎完整 |
| 开发体验 | 动态类型,调试难 | 静态类型,较好 | 与 C# 相同,但有限制 | 与 C# 相同 |
| 成熟度 | 非常成熟 | 较成熟 | 成熟,逐渐被替代 | 较新,发展快,已有大量项目上线 |
| 适合 | 团队熟悉 Lua 的项目、老项目 | 偏好 TS 的团队 | 老项目维护 | 新项目首选 |
四、资源热更方案
AssetBundle
Unity 原生的资源打包格式。把资源打成一个个 Bundle 文件,运行时从本地或远程加载。
- 依赖:资源之间有引用关系(Prefab 引用材质,材质引用贴图)。被多个 Bundle 共同引用、但没有单独指定打包的资源,会被复制进每一个引用它的 Bundle,造成冗余。所以打包策略需要规划公共资源。
- Manifest:打包后生成的清单,记录每个 Bundle 的依赖关系和哈希值。加载一个 Bundle 前,要先加载它依赖的所有 Bundle。
- 卸载:
AssetBundle.Unload(false/true)的区别见 Unity 内存构成。
直接使用 AssetBundle 需要自己处理依赖加载、引用计数、版本比对、下载、缓存,工作量很大,所以一般会使用封装好的框架。 AssetBundle 的文件结构、压缩方式、依赖和打包策略见 AssetBundle 原理与打包策略。
Addressables
Unity 官方基于 AssetBundle 的资源管理系统。
- 资源通过地址(Address)加载,不需要关心它在哪个 Bundle、是本地还是远程。
- 自动处理依赖和引用计数。
- 通过 Catalog(资源目录)记录资源和 Bundle 的对应关系,热更时先更新 Catalog,再下载变化的 Bundle。
- 内容更新的流程较为复杂:需要区分可更新和不可更新的分组,用 “Check for Content Update Restrictions” 检查改动,并保留每次打包生成的状态文件。
YooAsset
国内开源的资源管理和热更新框架,在国内项目中应用很广。相比 Addressables,概念更直观、可控性更强、更新流程更简单。后文详细介绍。
方案对比
| 原生 AssetBundle | Addressables | YooAsset | |
|---|---|---|---|
| 依赖与引用计数 | 自己实现 | 自动 | 自动 |
| 热更流程 | 自己实现 | 官方提供,较复杂 | 官方提供,较简单 |
| 打包规则配置 | 手动标记 | 分组 + 模板 | 可视化收集器 + 打包规则 |
| 分包下载 | 自己实现 | 标签 | 标签 |
| 学习成本 | 高(要自己造轮子) | 中 | 低 |
五、热更新的整体设计
启动流程
- 启动:初始化资源系统,显示启动界面。
- 检查版本:请求服务器的版本信息。如果当前整包版本低于最低兼容版本,引导玩家去应用商店下载新包,流程结束。
- 更新清单:下载最新版本的资源清单。
- 计算差异:对比本地缓存,得出需要下载的文件。有需要下载的,提示大小,下载并校验。
- 加载热更代码:补充 AOT 元数据,加载热更 dll。
- 进入游戏:调用热更层的入口,之后的逻辑都在热更层中运行。
分层:AOT 层与热更层
热更新架构最重要的设计,是把代码分成两层:
| AOT 层(启动层) | 热更层(业务层) | |
|---|---|---|
| 包含 | 启动器、热更流程、资源系统、网络底层、SDK 接入、平台相关代码、第三方库 | 游戏逻辑、UI、玩法、配置解析 |
| 能否热更 | 不能,只能随整包更新 | 能 |
| 设计原则 | 尽量少、尽量稳定,接口通用 | 绝大部分业务代码放在这里 |
| 引用关系 | 不能引用热更层 | 可以引用 AOT 层 |
AOT 层一旦出 Bug 只能发整包,所以它要尽量小,只放”热更流程本身”和”必须在原生层的东西”。启动器和热更界面要做得足够健壮,因为热更失败时,玩家只能看到这一层。
版本设计
- 整包版本(如 1.2.0):AOT 层变化、Unity 升级、原生 SDK 变化时,必须发整包。
- 热更版本(如 1.2.0 的第 15 次资源版本):只更新热更层代码和资源。
- 服务器的版本信息中要记录:每个整包版本对应的最新热更版本、最低兼容的整包版本(低于它就强制整包更新)。
- 资源放在 CDN 上,每个版本使用独立的路径,避免 CDN 缓存导致玩家拿到新旧混杂的文件,也便于回滚。
下载与校验
- 增量下载:清单中记录每个文件的哈希值,只下载本地缓存中没有的文件。
- 完整性校验:下载后校验大小和哈希值(或 CRC),不通过就删除重下。
- 失败重试、备用下载地址、断点续传。
- 下载前提示:告诉玩家下载大小,非 Wi-Fi 时让玩家确认。
- 磁盘空间检查。
- 首包资源:一部分资源随安装包放在 StreamingAssets 中,保证首次启动不用下载太多。
灰度与回滚
- 灰度发布:新版本先只推给一部分玩家(按白名单、渠道或比例),确认没有问题再全量。
- 回滚:出问题时,把服务器的版本信息指回上一个版本即可,因为旧版本的文件在 CDN 上仍然存在。
六、HybridCLR 详解
原理
IL2CPP 运行时(libil2cpp)负责管理类型元数据、对象、GC、方法调用等。正常情况下,它只认识打包时就编译好的 AOT 代码。
HybridCLR 修改了 libil2cpp,加入了:
- 动态加载程序集:让 IL2CPP 下的
Assembly.Load(byte[])真正生效,加载后的类型注册进运行时,和 AOT 类型同等对待。 - IL 解释器:热更程序集中的方法,由解释器执行。解释器会先把 IL 转换成自己的寄存器式指令,再执行,比直接解释 IL 快。
- AOT 与解释器之间的桥接:两边互相调用时(比如 AOT 代码调用热更类型重写的虚方法),通过预先生成的桥接函数转换参数和返回值。
因为热更类型是真正的运行时类型,所以:
- 热更代码可以直接继承 AOT 中的类、实现 AOT 中的接口,包括
MonoBehaviour。 - AOT 代码通过虚方法、接口、委托调用热更代码时,自动走解释器。
- 反射、泛型、async/await、Lambda 都能正常使用。
工程结构
Assets/├── Scripts/│ ├── Launcher/ ← AOT 层:启动器、热更流程,不能热更│ └── HotUpdate/ ← 热更层,用 asmdef 定义为独立程序集│ └── HotUpdate.asmdef- 热更代码必须放在独立的程序集中(用 asmdef 划分),在 HybridCLR 的设置中登记为热更程序集。
- AOT 程序集不能引用热更程序集,否则打包时它就会被当成 AOT 代码编译进去。
- 热更层的入口通过反射调用。
使用流程
一次性准备:
- 安装 HybridCLR 包,在菜单中执行 Installer,它会把修改过的 libil2cpp 安装到项目中。
- 在 HybridCLR Settings 中登记热更程序集。
- Player Settings 中脚本后端选择 IL2CPP。
每次打整包:
- 执行
HybridCLR/Generate/All,生成桥接函数、link.xml(防止 AOT 中被热更代码用到的类型被裁剪)等。 - 正常打包。
每次热更:
- 执行
HybridCLR/CompileDll/ActiveBuildTarget,编译出热更 dll。 - 把 dll 改名为
.bytes,作为资源打包上传(比如用 YooAsset 的原生文件)。
运行时加载:
// 1. 补充元数据(见下文"AOT 泛型问题")foreach (var aotDllName in AOTMetaAssemblyNames){ byte[] bytes = LoadBytes(aotDllName); RuntimeApi.LoadMetadataForAOTAssembly(bytes, HomologousImageMode.SuperSet);}
// 2. 加载热更程序集(编辑器下直接使用已加载的程序集)#if UNITY_EDITORAssembly hotUpdate = AppDomain.CurrentDomain.GetAssemblies() .First(a => a.GetName().Name == "HotUpdate");#elseAssembly hotUpdate = Assembly.Load(LoadBytes("HotUpdate.dll"));#endif
// 3. 通过反射调用热更层入口hotUpdate.GetType("GameEntry").GetMethod("Start").Invoke(null, null);AOT 泛型问题
这是 HybridCLR 最常见的坑。
IL2CPP 打包时,只会为代码中实际出现过的泛型实例生成机器码。比如 AOT 代码中用过 List<int>,就有 List<int> 的实现;但热更代码新写了一个 List<MyStruct>,打包时根本不知道它存在,就没有对应的机器码。
- 泛型参数是引用类型:IL2CPP 会让所有引用类型参数共享同一份实现(比如
List<object>的代码),所以没有问题。 - 泛型参数是值类型:每个值类型都需要单独的实现,就会缺失。
HybridCLR 的解决方法是补充元数据:把 AOT 程序集的元数据(打包时裁剪后的 AOT dll)加载进来,当找不到某个泛型实例的 AOT 实现时,解释器就根据元数据中的 IL 解释执行这个泛型方法。代价是这部分代码以解释方式运行,变慢。
新版本 Unity 的 IL2CPP 支持完全泛型共享,配合新版 HybridCLR,可以不再需要补充元数据。具体以所用 Unity 和 HybridCLR 版本的官方文档为准。
其他注意事项
- 挂在资源上的热更脚本:Prefab 上挂的热更 MonoBehaviour,必须在热更 dll 加载之后才能加载这个 Prefab,并且这个 Prefab 要打进热更资源(AB)中。主包场景里不能直接挂热更脚本。
- 性能:解释执行比 AOT 慢,计算密集的代码(寻路、战斗数值计算、大量循环)尽量放在 AOT 层。
- AOT 层无法修复:社区版中,AOT 层的代码改了只能发整包。官方的商业版本提供 DHE(差分混合执行):只有改动过的函数走解释器,没改动的仍以 AOT 方式运行,可以热更 AOT 代码且性能损失很小。
- 原生回调:要把委托传给原生代码作为回调(
MonoPInvokeCallback)时,需要额外的配置预留桥接函数。
七、YooAsset 详解
核心概念
| 概念 | 说明 |
|---|---|
| 资源包裹(Package) | 一组独立管理、独立版本的资源。可以按需划分多个包裹,比如主包裹、DLC 包裹 |
| 资源收集器(Collector) | 编辑器中的可视化配置,指定哪些目录的资源要打包、按什么规则打包 |
| 打包规则(PackRule) | 决定资源怎么分到 Bundle 中:每个文件一个 Bundle、按文件夹打包、整个收集器打成一个,或者作为原生文件不打包 |
| 地址(Address) | 可以用简短的地址(如文件名)加载资源,而不必用完整路径 |
| 标签(Tag) | 给资源打标签,按标签分批下载,比如首次只下载”基础”标签 |
| 资源清单(Manifest) | 记录包裹中所有资源、Bundle、依赖关系和哈希值,热更时先下载它 |
打包
- 构建管线:内置管线(
BuildPipeline.BuildAssetBundles)、可编程构建管线 SBP(推荐)、原生文件管线(不打成 AB,直接复制,用于热更 dll、配置表、视频等)。 - 输出产物:
- 若干 Bundle 文件;
- 资源清单
PackageManifest_{包裹名}_{版本}.bytes; - 版本文件
PackageManifest_{包裹名}.version,内容就是当前的版本号。
- 首包资源:可以选择把一部分或全部资源复制到 StreamingAssets,随安装包发布。
把输出目录上传到 CDN 的对应版本路径下,就完成了一次资源发布。
运行模式
| 模式 | 用途 |
|---|---|
| 编辑器模拟模式 | 开发时直接加载 Assets 下的资源,不用打包 |
| 单机模式(Offline) | 资源全部在安装包内,没有热更 |
| 联机模式(Host) | 首包资源 + 远程下载,正式的热更模式 |
| Web 模式 | WebGL 平台 |
热更流程
YooAsset 2.x 的大致写法(不同小版本的参数略有差异):
// 1. 初始化YooAssets.Initialize();var package = YooAssets.CreatePackage("DefaultPackage");YooAssets.SetDefaultPackage(package);
var initParams = new HostPlayModeParameters();// 配置首包文件系统和缓存文件系统,后者需要传入远程地址服务(IRemoteServices)// initParams.BuildinFileSystemParameters = ...;// initParams.CacheFileSystemParameters = ...;yield return package.InitializeAsync(initParams);
// 2. 请求远程的最新版本号var versionOp = package.RequestPackageVersionAsync();yield return versionOp;string version = versionOp.PackageVersion;
// 3. 下载并加载这个版本的资源清单var manifestOp = package.UpdatePackageManifestAsync(version);yield return manifestOp;
// 4. 根据清单计算需要下载的文件var downloader = package.CreateResourceDownloader(downloadingMaxNumber: 10, failedTryAgain: 3);if (downloader.TotalDownloadCount > 0){ // 提示玩家:downloader.TotalDownloadBytes downloader.BeginDownload(); yield return downloader;}差异下载的原理:新清单中记录了每个 Bundle 的哈希值。YooAsset 检查本地缓存目录(沙盒)和首包资源中是否已有相同哈希的文件,只有都没有的才需要下载。资源没变化的 Bundle 哈希不变,自然不会重复下载。
加载时的查找顺序:缓存目录 → 首包资源 → 远程下载(联机模式下可以边玩边下)。
分包下载:CreateResourceDownloader 可以传入标签,只下载带这些标签的资源,其余的在需要时再下载。
加载与卸载
// 加载资源var handle = package.LoadAssetAsync<GameObject>("Hero");yield return handle;var go = handle.InstantiateSync();
// 不再使用时释放句柄(引用计数减一)handle.Release();
// 卸载引用计数为 0 的资源和 Bundlepackage.UnloadUnusedAssetsAsync();
// 加载原生文件(如 HybridCLR 的热更 dll)var rawHandle = package.LoadRawFileAsync("HotUpdate.dll");yield return rawHandle;byte[] dllBytes = rawHandle.GetRawFileData();- 每次加载返回一个句柄,YooAsset 内部基于句柄做引用计数。
- 关键是每个句柄都要释放:句柄不释放,资源就永远不会被卸载,这是使用 YooAsset 时最常见的内存泄漏。可以在业务层封装一层,让界面、实体在销毁时自动释放自己加载的所有句柄。
其他功能
- 加密:实现
IEncryptionServices(打包时)和IDecryptionServices(运行时),可以对 Bundle 做偏移或流加密,防止资源被直接解包。 - 多包裹:不同包裹独立初始化、独立更新,适合 DLC 或按玩法拆分。
- 调试窗口:可以在运行时查看所有已加载的资源、Bundle 及其引用计数。
八、HybridCLR + YooAsset 组合
两者分工清晰,是目前国内新项目的常见组合:
AOT 层(启动器) ├── 用 YooAsset 初始化资源系统、检查版本、下载更新 ├── 用 YooAsset 以原生文件方式加载热更 dll 和 AOT 元数据 dll ├── 用 HybridCLR 补充元数据、Assembly.Load 热更 dll └── 反射调用热更层入口热更层 └── 游戏业务,继续通过 YooAsset 加载资源发布一次热更的步骤:
- 编译热更 dll(HybridCLR CompileDll),复制到原生文件的收集目录中。
- 用 YooAsset 打包资源,生成新的版本号。
- 上传到 CDN 的新版本目录。
- 修改服务器的版本信息,指向新版本(可以先灰度)。
常见追问
为什么 IL2CPP 不能直接热更 C# 代码? IL2CPP 是 AOT:打包时就把 IL 编译成机器码,运行时没有 JIT,新的 IL 没有东西执行。iOS 也禁止运行时生成机器码。所以只能靠解释器。
Lua 热更和 HybridCLR 有什么区别? Lua 是嵌入另一门语言的虚拟机,通过绑定层和 C# 交互,有转换开销,需要维护两种语言。HybridCLR 扩展了 IL2CPP 运行时,热更代码仍是 C#,类型和 AOT 类型同等对待,交互无缝。
ILRuntime 和 HybridCLR 有什么区别? ILRuntime 是用 C# 实现的独立解释器,热更类型不是真正的运行时类型,跨域继承要写适配器。HybridCLR 直接集成在 IL2CPP 运行时中,热更类型就是原生类型,不需要适配器,性能也更好。
HybridCLR 的 AOT 泛型问题是什么?怎么解决?
热更代码中用到了 AOT 中从未实例化过的值类型泛型(如 List<MyStruct>),没有对应机器码。通过补充元数据让解释器执行这部分泛型代码,新版本可借助完全泛型共享解决。
热更新架构中,哪些代码放 AOT 层,哪些放热更层? AOT 层只放启动器、热更流程、资源系统、SDK 等必须原生且稳定的部分,尽量少;业务逻辑、UI 都放热更层。AOT 层不能引用热更层。
资源热更怎么做到只下载变化的部分? 资源清单记录每个文件的哈希值,客户端对比本地缓存,只下载哈希不存在的文件。
AssetBundle 的资源冗余是怎么产生的? 多个 Bundle 引用了同一个资源,而这个资源没有被单独打包,它就会被复制进每个引用它的 Bundle。
YooAsset 中资源为什么没有被卸载? 加载返回的句柄没有释放,引用计数不为 0。
CDN 上的热更文件为什么要按版本放在不同目录? 避免 CDN 缓存导致新旧文件混杂;旧版本文件保留,方便回滚。
文章分享
如果这篇文章对你有帮助,欢迎分享给更多人!