Unity热更方案HybridCLR+YooAsset，纯c#开发热更，保姆级教程，从零开始

一、前言

unity热更有很多方案，各种lua热更，ILRuntime等，这里介绍的是YooAsset+HybridCLR的热更方案，HybridCLR负责更新c#代码，YooAsset负责更新资源。

简单来说，流程就是将c#代码打成dll，然后把dll当做一个资源，用YooAsset热更dll资源之后，动态加载dll程序集，然后执行新逻辑

HybridCLR相比其他代码热更方案而言，纯c#方便开发，更加符合开发者习惯，更新的代码执行效率也更好。

YooAsset热更资源，主要是省去了自己亲自管理ab包，ab包的管理挺繁琐，AssetBundle坑也很多，而且YooAsset有下载器，不用自己手写网络下载，也不用自己记录资源，比对资源列表来判定需要热更什么资源。

这里将从零开始，用一个空工程，展示YooAsset+HybridCLR热更的使用过程。

二、创建空工程

这里使用的版本是unity2022.3.17.f1c1

三、接入HybridCLR

unity必须添加了Windows Build Support(IL2CPP)或Mac Build Support(IL2CPP)模块

安装IDE及相关编译环境
Win
需要安装visual studio 2019或更高版本。安装时至少要包含使用Unity的游戏开发和使用c++的游戏开发组件。
安装git

Mac
要求MacOS版本 >= 12，xcode版本 >= 13，例如xcode 13.4.1， macos 12.4。
安装 git

添加ConsoleToScreen.cs脚本
和热更无关，主要在屏幕上显示log，代码如下：

using System.Collections.Generic;
using UnityEngine;public class ConsoleToScreen : MonoBehaviour
{const int maxLines = 50;const int maxLineLength = 120;private string _logStr = "";private readonly List<string> _lines = new();public int fontSize = 15;void OnEnable() { Application.logMessageReceived += Log; }void OnDisable() { Application.logMessageReceived -= Log; }public void Log(string logString, string stackTrace, LogType type){foreach (var line in logString.Split('\n')){if (line.Length <= maxLineLength){_lines.Add(line);continue;}var lineCount = line.Length / maxLineLength + 1;for (int i = 0; i < lineCount; i++){if ((i + 1) * maxLineLength <= line.Length){_lines.Add(line.Substring(i * maxLineLength, maxLineLength));}else{_lines.Add(line.Substring(i * maxLineLength, line.Length - i * maxLineLength));}}}if (_lines.Count > maxLines){_lines.RemoveRange(0, _lines.Count - maxLines);}// _lines.Add(stackTrace);_logStr = string.Join("\n", _lines);}void OnGUI(){GUI.matrix = Matrix4x4.TRS(Vector3.zero, Quaternion.identity,new Vector3(Screen.width / 1200.0f, Screen.height / 800.0f, 1.0f));GUI.Label(new Rect(10, 10, 800, 370), _logStr, new GUIStyle { fontSize = 10 });}
}

工程初始设置
创建Main场景
将ConsoleToScreen挂载一个创建的空物体上
菜单栏 File/BuildSettings添加Main场景
创建Assets/HotUpdate目录

创建热更程序集
在HotUpdate目录下 右键 Create/Assembly Definition，创建一个名为HotUpdate的程序集模块

安装HybridCLR
主菜单中点击Windows/Package Manager
Add package from git URL…
填入：https://gitee.com/focus-creative-games/hybridclr_unity.git
如下：

初始化HybridCLR
打开菜单HybridCLR/Installer…， 点击Install按钮进行安装。 耐心等待30s左右，安装完成后会在最后打印 安装成功日志。

配置HybridCLR
打开菜单 HybridCLR/Settings， 在热更新Assembly Definitions配置项中添加HotUpdate程序集。

设置PlayerSettings
打开菜单Edit/Project Setting，在Player选项中，设置如下几个配置：
Scripting Backend 切换为 IL2CPP。
Api Compatability Level 切换为 .Net 4.x(Unity 2019-2020) 或.Net Framework（Unity 2021+）

HybridCLR方面的操作告一段落，接下来接入YooAsset

四、接入YooAsset

安装YooAsset
打开菜单Edit/Project Settings/Package Manager
在Package Manager选项找那个，输入如下内容，点击save：

（国际版）
Name: package.openupm.com
URL: https://package.openupm.com
Scope(s): com.tuyoogame.yooasset

（中国版）
Name: package.openupm.cn
URL: https://package.openupm.cn
Scope(s): com.tuyoogame.yooasset
(这个配置好像报错了，我用的上面国际版的地址)

打开菜单Windows/Package Manager
Packages选择My Registries,出现了YooAsset，点击Install安装。

五、搭建本地资源服务器Nginx

为了模拟热更流程，需要一个服务器作为热更资源的下载，我们可以在本机搭建一个资源服务器。我这里用的是Nginx。
下载地址：https://nginx.org/en/download.html

随便下一个，下载之后是个zip包，解压之后如下：

注意：端口冲突时，更改端口：打开文件：conf-nginx.conf,修改第36行的listen，我改的是8084，自己随意
然后运行nginx.exe即可

现在打开网址http://127.0.0.1:8084如下：

html文件夹下，就可以放需要热更的资源，比如我准备打包测试的是pc平台，我就在html文件夹下建了个TestProject文件夹，在里面再建个PC文件夹，TestProject是项目名，PC是平台名，用以放接下来要热更的资源

六、实战

创建热更目录
之前的HotUpdate文件夹是为了放c#代码，用以生成程序集的，接下来创建的目录，是为了热更资源的（包括c#代码的dll资源，dll也是一种资源），创建如下目录：

准备工作
在HotUpdate文件夹下创建InstantiateByAsset.cs，这是会被热更的代码：

using UnityEngine;public class InstantiateByAsset : MonoBehaviour
{void Start(){Debug.Log("原始代码");}
}

创建一个cube预制体，挂载InstantiateByAsset组件，放入MyAsset/Prefabs中

收集热更资源

创建Resources文件夹，在Resources文件夹内通过右键创建配置文件（Project窗体内右键 -> Create -> YooAsset -> Create Setting），将配置文件放在Resources文件夹下

打开菜单YooAsset/AssetBundle Collector，点击ShowPackages，再点击+号，创建packages，再点击ShowPackages，只显示Groups就行，方便操作

打开Enable Addressable
添加code和prefab分组，具体设置如下：

选项含义如下，其他含义，请看官网

编写LoadDll.cs
编写代码初始化YooAsset，从资源服加载热更资源，加载热更程序集，将LoadDll.cs挂在Main场景的Main Camera上。

整个代码流程就是先初始化，然后下载热更资源，然后补充元数据，然后开始执行热更代码。
关于补充元数据，通俗的理解，举个例子：

由于Unity IL2CPP打包的代码裁剪，假设在打包时的代码，从来没有用过List泛型，打包时，List的元数据会被裁掉了。到玩家手机的APP上，根本不存在List的程序定义等关键信息。当玩家运行app时，在运行前预编译这个app的代码时，是不存在List的相关定义的，编译完成后，在运行时，热更逻辑中，使用了List，虽然这个热更的dll中有List的程序定义，但是已经过了编译阶段，现在是执行阶段，执行阶段是直接找预编译时的程序定义去进行实例化。所以在动态执行包含有List的代码时，由于编译阶段缺失了List的程序定义相关的元数据，无法对其进行实例化。所以在运行包含了List的热更代码时，先补齐编译阶段缺失的List元数据，之后才能正常运行和实例化热更中的包含了List的代码。

常见的需要补充的元数据如：mscorlib.dll, System.dll, System.Core.dll

详细信息原理请浏览官网

代码如下：

using HybridCLR;
using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;
using System.Reflection;
using UnityEngine;
using YooAsset;/// <summary>
/// 脚本工作流程：
/// 1.下载资源，用yooAsset资源框架进行下载
///    1.资源文件，ab包
///    2.热更新dll
/// 2.给AOT DLL补充元素据，通过RuntimeApi.LoadMetadataForAOTAssembly
/// 3.通过实例化prefab，运行热更代码
/// </summary>
public class LoadDll : MonoBehaviour
{/// <summary>/// 资源系统运行模式/// </summary>public EPlayMode PlayMode = EPlayMode.HostPlayMode;private ResourcePackage _defaultPackage;void Start(){StartCoroutine(InitYooAssets(StartGame));}#region YooAsset初始化IEnumerator InitYooAssets(Action onDownloadComplete){// 1.初始化资源系统YooAssets.Initialize();string packageName = "DefaultPackage";var package = YooAssets.TryGetPackage(packageName) ?? YooAssets.CreatePackage(packageName);YooAssets.SetDefaultPackage(package);if (PlayMode == EPlayMode.EditorSimulateMode){//编辑器模拟模式var initParameters = new EditorSimulateModeParameters { SimulateManifestFilePath = EditorSimulateModeHelper.SimulateBuild(EDefaultBuildPipeline.BuiltinBuildPipeline, "DefaultPackage") };yield return package.InitializeAsync(initParameters);}else if (PlayMode == EPlayMode.HostPlayMode){//联机运行模式string defaultHostServer = GetHostServerURL();string fallbackHostServer = GetHostServerURL();Debug.Log(defaultHostServer);var initParameters = new HostPlayModeParameters();initParameters.BuildinQueryServices = new GameQueryServices();// initParameters.DecryptionServices = new GameDecryptionServices();// initParameters.DeliveryQueryServices = new DefaultDeliveryQueryServices();initParameters.RemoteServices = new RemoteServices(defaultHostServer, fallbackHostServer);var initOperation = package.InitializeAsync(initParameters);yield return initOperation;if (initOperation.Status == EOperationStatus.Succeed){Debug.Log("资源包初始化成功！");}else{Debug.LogError($"资源包初始化失败：{initOperation.Error}");}}//2.获取资源版本var operation = package.UpdatePackageVersionAsync();yield return operation;if (operation.Status != EOperationStatus.Succeed){//更新失败Debug.LogError(operation.Error);yield break;}string packageVersion = operation.PackageVersion;Debug.Log($"Updated package Version : {packageVersion}");//3.更新补丁清单// 更新成功后自动保存版本号，作为下次初始化的版本。// 也可以通过operation.SavePackageVersion()方法保存。var operation2 = package.UpdatePackageManifestAsync(packageVersion);yield return operation2;if (operation2.Status != EOperationStatus.Succeed){//更新失败Debug.LogError(operation2.Error);yield break;}//4.下载补丁包yield return Download();//判断是否下载成功var assets = new List<string> { "HotUpdate.dll" }.Concat(AOTMetaAssemblyFiles);foreach (var asset in assets){var handle = package.LoadAssetAsync<TextAsset>(asset);yield return handle;var assetObj = handle.AssetObject as TextAsset;s_assetDatas[asset] = assetObj;Debug.Log($"dll:{asset}   {assetObj == null}");}_defaultPackage = package;onDownloadComplete();}private string GetHostServerURL(){//模拟下载地址，8084为Nginx里面设置的端口号，项目名，平台名return "http://127.0.0.1:8084/TestProject/PC";}/// <summary>/// 远端资源地址查询服务类/// </summary>private class RemoteServices : IRemoteServices{private readonly string _defaultHostServer;private readonly string _fallbackHostServer;public RemoteServices(string defaultHostServer, string fallbackHostServer){_defaultHostServer = defaultHostServer;_fallbackHostServer = fallbackHostServer;}string IRemoteServices.GetRemoteMainURL(string fileName){return $"{_defaultHostServer}/{fileName}";}string IRemoteServices.GetRemoteFallbackURL(string fileName){return $"{_fallbackHostServer}/{fileName}";}}/// <summary>/// 资源文件查询服务类/// </summary>internal class GameQueryServices : IBuildinQueryServices{public bool Query(string packageName, string fileName, string fileCRC){
#if UNITY_IPHONEthrow new Exception("Ios平台需要内置资源");return false;
#elsereturn false;
#endif}}#endregion#region 下载热更资源IEnumerator Download(){int downloadingMaxNum = 10;int failedTryAgain = 3;var package = YooAssets.GetPackage("DefaultPackage");var downloader = package.CreateResourceDownloader(downloadingMaxNum, failedTryAgain);//没有需要下载的资源if (downloader.TotalDownloadCount == 0){yield break;}//需要下载的文件总数和总大小int totalDownloadCount = downloader.TotalDownloadCount;long totalDownloadBytes = downloader.TotalDownloadBytes;//注册回调方法downloader.OnDownloadErrorCallback = OnDownloadErrorFunction;downloader.OnDownloadProgressCallback = OnDownloadProgressUpdateFunction;downloader.OnDownloadOverCallback = OnDownloadOverFunction;downloader.OnStartDownloadFileCallback = OnStartDownloadFileFunction;//开启下载downloader.BeginDownload();yield return downloader;//检测下载结果if (downloader.Status == EOperationStatus.Succeed){//下载成功Debug.Log("更新完成");}else{//下载失败Debug.Log("更新失败");}}/// <summary>/// 开始下载/// </summary>/// <param name="fileName"></param>/// <param name="sizeBytes"></param>private void OnStartDownloadFileFunction(string fileName, long sizeBytes){Debug.Log(string.Format("开始下载：文件名：{0}，文件大小：{1}", fileName, sizeBytes));}/// <summary>/// 下载完成/// </summary>/// <param name="isSucceed"></param>private void OnDownloadOverFunction(bool isSucceed){Debug.Log("下载" + (isSucceed ? "成功" : "失败"));}/// <summary>/// 更新中/// </summary>/// <param name="totalDownloadCount"></param>/// <param name="currentDownloadCount"></param>/// <param name="totalDownloadBytes"></param>/// <param name="currentDownloadBytes"></param>private void OnDownloadProgressUpdateFunction(int totalDownloadCount, int currentDownloadCount, long totalDownloadBytes, long currentDownloadBytes){Debug.Log(string.Format("文件总数：{0}，已下载文件数：{1}，下载总大小：{2}，已下载大小{3}", totalDownloadCount, currentDownloadCount, totalDownloadBytes, currentDownloadBytes));}/// <summary>/// 下载出错/// </summary>/// <param name="fileName"></param>/// <param name="error"></param>private void OnDownloadErrorFunction(string fileName, string error){Debug.Log(string.Format("下载出错：文件名：{0}，错误信息：{1}", fileName, error));}#endregion#region 补充元数据//补充元数据dll的列表//通过RuntimeApi.LoadMetadataForAOTAssembly()函数来补充AOT泛型的原始元数据private static List<string> AOTMetaAssemblyFiles { get; } = new() { "mscorlib.dll", "System.dll", "System.Core.dll", };private static Dictionary<string, TextAsset> s_assetDatas = new Dictionary<string, TextAsset>();private static Assembly _hotUpdateAss;public static byte[] ReadBytesFromStreamingAssets(string dllName){if (s_assetDatas.ContainsKey(dllName)){return s_assetDatas[dllName].bytes;}return Array.Empty<byte>();}/// <summary>/// 为aot assembly加载原始metadata， 这个代码放aot或者热更新都行。/// 一旦加载后，如果AOT泛型函数对应native实现不存在，则自动替换为解释模式执行/// </summary>private static void LoadMetadataForAOTAssemblies(){/// 注意，补充元数据是给AOT dll补充元数据，而不是给热更新dll补充元数据。/// 热更新dll不缺元数据，不需要补充，如果调用LoadMetadataForAOTAssembly会返回错误HomologousImageMode mode = HomologousImageMode.SuperSet;foreach (var aotDllName in AOTMetaAssemblyFiles){byte[] dllBytes = ReadBytesFromStreamingAssets(aotDllName);// 加载assembly对应的dll，会自动为它hook。一旦aot泛型函数的native函数不存在，用解释器版本代码LoadImageErrorCode err = RuntimeApi.LoadMetadataForAOTAssembly(dllBytes, mode);Debug.Log($"LoadMetadataForAOTAssembly:{aotDllName}. mode:{mode} ret:{err}");}}#endregion#region 运行测试void StartGame(){// 加载AOT dll的元数据LoadMetadataForAOTAssemblies();// 加载热更dll
#if !UNITY_EDITOR_hotUpdateAss = Assembly.Load(ReadBytesFromStreamingAssets("HotUpdate.dll"));
#else_hotUpdateAss = System.AppDomain.CurrentDomain.GetAssemblies().First(a => a.GetName().Name == "HotUpdate");
#endifDebug.Log("运行热更代码");StartCoroutine(Run_InstantiateComponentByAsset());}IEnumerator Run_InstantiateComponentByAsset(){// 通过实例化assetbundle中的资源，还原资源上的热更新脚本var package = YooAssets.GetPackage("DefaultPackage");var handle = package.LoadAssetAsync<GameObject>("Cube");yield return handle;handle.Completed += Handle_Completed;}private void Handle_Completed(AssetHandle obj){Debug.Log("准备实例化");GameObject go = obj.InstantiateSync();Debug.Log($"Prefab name is {go.name}");}#endregion
}
//PS:版本不同可能有一些类名发生变化，请参照现阶段版本自行修改，官网可能更新不及时。

打包阶段
（这里演示的是pc平台）
打开菜单 HybridCLR/Generate/All，耐心等待之后，
回到Assets同级目录，将HybridCLRData/HotUpdateDlls/StandaloneWindows64/HotUpdate.dll复制到Assets/MyAssset/Codes内，并且加上后缀.bytes，这是包含热更逻辑代码的dll

再将HybridCLRData/AssembliesPostIl2CppStrip/StandaloneWindows64目录下的mscorlib.dll, System.dll, System.Core.dll这三个dll复制到Assets/MyAssset/Codes内，并且加上后缀.bytes，这是包含补充元数据的dll

打开菜单YooAsset/AssetBundle Builder，BuildModel选ForceRebuild，全量构建。一般第一次选这个，后面IncrementalBuild热更选增量构建,点击ClickBuild

构建完之后会自动打开构建后的资源目录，在Asset同级目录下的Bundles/StandaloneWindows64/DefaultPackage/2024-06-27-1194（构建时的版本号）

把里面的所有东西，放在本地资源服务器Nginx的目录下，之前代码里访问的地址：http://127.0.0.1:8084/TestProject/PC就是这里了，到时候热更就是从这里下载最新的资源

操作完上述之后，打开菜单 File/Build Settings/Build先把.exe打出来，双击运行，能看到先从http://127.0.0.1:8084/TestProject/PC路径下下载资源包，然后补充元数据，然后实例化了Cube预制体，执行了预制体上的代码，打印了“原始代码”。

开始热更
终于到了激动人心的热更环节，前面搞了那么多就是为了热更代码和资源。接下来我们把cube预制体尺寸x改为10，将InstantiateByAsset脚本的输出从“原始代码”改为“热更后的代码”。

点击菜单 HybridCLR/CompileDll/ActiveBuildTarget，把新的HotUpdate.dll复制替换掉MyAsset里面原来的HotUpdate.dll，记得加后缀.bytes，另外三个mscorlib.dll, System.dll, System.Core.dll也复制替换过去记得加后缀.bytes。

打开菜单YooAsset/AssetBundle Builder，BuildModel选IncrementalBuild，增量构建，点击ClickBuild，然后自动打开了生成的资源所在的文件夹，把这一堆生成的东西，复制到本地资源服务器Nginx的TestProject/PC目录下，之前的旧资源删掉。

然后重新打开之前的exe程序，看到代码和资源都热更了，大功告成！！！

七、最后

至于其他的更多细节，比如加密解密，资源收集设置等待，可以多多浏览官网以及官网的示例项目。
HybridCLR
YooAsset