戰(zhàn)：原理、接入順序與真機(jī)排坑)
我到現(xiàn)在都記得第一次線上事故的場(chǎng)景一個(gè)已經(jīng)過審上架的手游運(yùn)營活動(dòng)發(fā)獎(jiǎng)勵(lì)的數(shù)值公式少取了一次隨機(jī)數(shù)玩家領(lǐng)到的獎(jiǎng)勵(lì)高了兩倍。服務(wù)端立刻封住漏洞但已經(jīng)安裝的客戶端代碼是死的發(fā)新版要走渠道審核少則一天多則一周那幾天項(xiàng)目組每個(gè)人臉上都寫著焦慮。那次之后我們整個(gè)團(tuán)隊(duì)把“代碼熱更新”從“以后再說”提到了“下周必須驗(yàn)證”的優(yōu)先級(jí)。最后選型、驗(yàn)證、接入的方案就是今天這篇要聊的 Unity HybridCLR 熱更新。如果只用一句話介紹HybridCLR 是一個(gè)基于 IL2CPP 的 C# 熱更新方案它能讓你的 Unity 項(xiàng)目在不重新打包上架、玩家不重新下載安裝包的情況下通過加載一段新的 C# 程序集來更新游戲邏輯。這篇文章是我自己從零把一個(gè) Demo 工程接入 HybridCLR再逐步推進(jìn)到真實(shí)項(xiàng)目的完整記錄。重點(diǎn)不是重復(fù)官方文檔而是告訴你接入順序、依賴方向、AOT 泛型問題這些文檔里不容易一次講透的東西以及我踩過的坑長什么樣。如果你是想評(píng)估熱更新方案的技術(shù)負(fù)責(zé)人、正在給老項(xiàng)目接熱更的 Unity 客戶端同學(xué)或者剛被分配要驗(yàn)證 HybridCLR 可行性的新手這篇應(yīng)該能幫你省下不少試錯(cuò)時(shí)間。讀完你應(yīng)該能知道它和 Lua 熱更、和 IDE 里的熱重載到底什么關(guān)系接入前工程要做什么體檢真機(jī)上跑通一個(gè)最小熱更工程需要哪幾步以及第一輪真機(jī)崩潰該怎么查。1. 為什么是 HybridCLR而不是 Lua 或者熱重載1.1 IL2CPP 把代碼焊死在哪里要理解 HybridCLR 的價(jià)值先得知道 Unity 的 IL2CPP 到底做了什么。在沒有 IL2CPP 的 Mono 時(shí)代C# 代碼會(huì)被編譯成 IL運(yùn)行時(shí)由 Mono 虛擬機(jī)解釋或 JIT 編譯執(zhí)行。那個(gè)年代想在 iOS 上做熱更新很麻煩因?yàn)樘O果明確禁止應(yīng)用在自己的沙盒里動(dòng)態(tài)生成可執(zhí)行代碼JIT 這條路在 iOS 上基本是堵死的。IL2CPP 是把 C# 先編譯成 IL再在構(gòu)建階段把 IL 轉(zhuǎn)成 C最后隨原生工程一起編譯成目標(biāo)平臺(tái)的機(jī)器碼。好處是啟動(dòng)快、性能好、代碼不容易被直接反編譯成原始 C#壞處也藏在這里所有 C# 邏輯都在編譯期被翻譯并“焊死”進(jìn)了原生二進(jìn)制運(yùn)行時(shí)已經(jīng)沒有一套能把新 IL 編譯成機(jī)器碼的機(jī)制了。這就好比你把菜譜都刻成了石碑讀者只能照著石碑做菜現(xiàn)在你拿到一張新菜譜卻沒有火源也沒有翻譯想按新菜譜做菜根本無從下手。HybridCLR 做的是在 IL2CPP 旁邊補(bǔ)了一個(gè)“解釋執(zhí)行器”讓新拿到的 C# 程序集也就是熱更 dll里的 IL 字節(jié)碼不經(jīng)過 JIT 也能被逐條解釋執(zhí)行。1.2 它和 xLua、ILRuntime 的本質(zhì)差異很多團(tuán)隊(duì)第一次聊熱更新聽到的往往是 xLua、tolua或者純 C# 的 ILRuntime。這里我直接按實(shí)際感受做個(gè)比較。Lua 方案的核心是“換語言”業(yè)務(wù)邏輯不寫在 C# 里而是寫 Lua運(yùn)行時(shí)由 C# 側(cè)的虛擬機(jī)解釋執(zhí)行。好處是生態(tài)成熟、很多老項(xiàng)目都在用代價(jià)是整個(gè)項(xiàng)目的核心玩法可能要從 C# 平移成 Lua維護(hù)一套雙語言邏輯團(tuán)隊(duì)里每個(gè)人都要會(huì) Lua出問題時(shí)要跨語言查堆棧代碼補(bǔ)全和重構(gòu)也不夠舒服。ILRuntime 是純 C# 的解釋器方案不需要換語言但它和 Unity 的 AOT 世界之間隔了一層自己的運(yùn)行時(shí)對(duì)某些 C# 特性的支持以及對(duì) Unity 引擎調(diào)用、泛型、值類型結(jié)構(gòu)的處理需要開發(fā)者額外注意。性能和兼容性一直在進(jìn)步但遇到冷門邊界總有“為什么這里不行”的疑惑。HybridCLR 選擇的是另一條路線盡可能貼近原生 CLR 的實(shí)現(xiàn)方式在 IL2CPP 的 AOT 基礎(chǔ)上加一個(gè)解釋器模塊并且用“補(bǔ)充元數(shù)據(jù)”的方式解決 AOT 泛型缺失的經(jīng)典問題。用下來最直觀的感受是它不是讓你把邏輯翻譯成另一種語言而是讓熱更 dll 里的 C# 代碼自己跑起來和主工程的 C# 代碼寫法差別不大。對(duì)比項(xiàng)Lua 系方案ILRuntimeHybridCLR業(yè)務(wù)語言Lua C#C#C#與 IL2CPP 關(guān)系獨(dú)立虛擬機(jī)獨(dú)立解釋器基于 IL2CPP 補(bǔ)充解釋能力學(xué)習(xí)成本需要掌握 Lua較低但邊界概念多較低重點(diǎn)是理解 AOT 與熱更分界泛型等邊界問題不受 IL2CPP 泛型影響有自己的處理通過補(bǔ)充元數(shù)據(jù)解決大多數(shù)社區(qū)活躍度高但偏向舊項(xiàng)目中高近幾年增長很快需要客觀說的是HybridCLR 本質(zhì)上是修改了 Unity 的 IL2CPP 構(gòu)建鏈路Unity 版本升級(jí)、IL2CPP 內(nèi)部實(shí)現(xiàn)調(diào)整都有可能影響它。所以它不是一個(gè)“裝一次永遠(yuǎn)不用管”的方案每次 Unity 升級(jí)或 HybridCLR 升級(jí)都要做回歸驗(yàn)證。這點(diǎn)后面章節(jié)會(huì)細(xì)說。1.3 先理清“熱更新”和“熱重載”不是一回事熱搜詞里出現(xiàn)了不少和熱更新相關(guān)的詞比如 Flutter 熱重載、IDEA 修改代碼熱更新、Nacos 配置熱更新。這些詞經(jīng)常被混在一起但它們解決的問題完全不同。Flutter 的熱重載本質(zhì)是開發(fā)期工具改完代碼按一下 R開發(fā)進(jìn)程把新的 widget 樹推給正在運(yùn)行的調(diào)試 App幫開發(fā)者快速看 UI 效果。它不面向線上玩家代碼改動(dòng)只在開發(fā)環(huán)境里生效。IDEA 里修改 Java 代碼后的熱更新是讓本地開發(fā)服務(wù)器不用重啟就能加載新類屬于開發(fā)效率工具的范圍。Nacos 配置熱更新更新的是配置項(xiàng)不是程序邏輯本身。而 Unity 項(xiàng)目里說的“代碼熱更新”指的是已經(jīng)安裝到玩家手機(jī)上的 App在不發(fā)新包的前提下從服務(wù)器拉取新的 C# 程序集并在本地執(zhí)行新邏輯。這是玩家可見的能力直接關(guān)系到線上事故的處理速度和上面那些開發(fā)期工具完全不是一個(gè)維度。所以有些同學(xué)問“我項(xiàng)目里用 IDE 熱重載很順是不是就不用 HybridCLR 了”答案顯然是否定的。2. 接入前先給工程“體檢”程序集、依賴方向、泛型用法2.1 依賴方向熱更代碼能引用什么不能引用什么接入 HybridCLR 最容易犯的錯(cuò)是直接拿一個(gè)已經(jīng)寫了兩三年的老工程把所有代碼都掃進(jìn)熱更程序集然后開始打包。正確的第一步是給工程劃分程序集邊界。Unity 項(xiàng)目里用 asmdef 把代碼分成多個(gè)程序集主工程里有一套專門給熱更代碼用的接口和公共代碼熱更代碼所在的程序集可以引用主工程的公共程序集但主工程的 AOT 代碼絕對(duì)不能反過來引用熱更程序集里的類型。一旦主工程靜態(tài)引用了熱更代碼里的類打 IL2CPP 包時(shí)就會(huì)把熱更代碼一起編進(jìn)去后續(xù)想替換邏輯就會(huì)非常別扭。我在項(xiàng)目里習(xí)慣的分層是這樣的AOT 主程序集啟動(dòng)流程、SDK 對(duì)接、資源管理、渲染相關(guān)、游戲的底層框架。AOT 公共接口層純接口和 DTO 定義比如戰(zhàn)斗結(jié)算接口、活動(dòng)模板接口供熱更代碼實(shí)現(xiàn)或調(diào)用。熱更程序集賽季玩法、活動(dòng)界面、數(shù)值表現(xiàn)、任務(wù)系統(tǒng)這類需要頻繁調(diào)整的邏輯。依賴方向是熱更層可以引用 AOT 公共接口層AOT 公共接口層不能引用熱更層。因?yàn)闊岣鼘邮沁\(yùn)行時(shí)才被加載的AOT 側(cè)的代碼在編譯期根本不知道它的存在兩者之間只能靠接口或反射溝通。2.2 重點(diǎn)檢查一遍泛型使用習(xí)慣體檢時(shí)另一個(gè)重點(diǎn)是泛型。C# 泛型在 AOT 編譯下有個(gè)天然矛盾IL2CPP 編譯器在打包時(shí)只會(huì)為主工程代碼里“顯式出現(xiàn)過的泛型實(shí)例化”生成機(jī)器碼。如果熱更代碼運(yùn)行時(shí)突然出現(xiàn)一個(gè) AOT 模塊里從未實(shí)例化過的泛型組合比如DictionaryMyStruct, intIL2CPP 那邊并沒有對(duì)應(yīng)的目標(biāo)代碼運(yùn)行時(shí)就會(huì)報(bào)類似AOT generic method can not be instantiated的錯(cuò)誤。HybridCLR 的解法是“補(bǔ)充元數(shù)據(jù) 解釋器兜底”。打包時(shí)項(xiàng)目會(huì)帶上 AOT 必需 dll比如 mscorlib、System、UnityEngine.CoreModule 這些的元數(shù)據(jù)運(yùn)行時(shí)先加載這些元數(shù)據(jù)讓解釋器能夠自己解析泛型方法的 IL 并執(zhí)行而不是必須依賴 IL2CPP 現(xiàn)成的機(jī)器碼。這并不代表你可以完全無視泛型。我建議在接入前把項(xiàng)目里“值類型 泛型容器混用”的地方掃一遍。比如大量使用Listint、Dictionaryint, MyEnum、Dictionarylong, MyStruct尤其是這些結(jié)構(gòu)體是活動(dòng)邏輯里臨時(shí)定義的時(shí)候要格外留意。這里不是說不能用而是你要意識(shí)到這類代碼會(huì)觸發(fā) AOT 泛型補(bǔ)充機(jī)制線上報(bào)錯(cuò)后排查成本會(huì)高一些。2.3 確認(rèn)版本兼容與目標(biāo)平臺(tái)體檢還包括兩個(gè)基礎(chǔ)問題項(xiàng)目用的 Unity 版本以及 Scripting Backend 是否已經(jīng)是 IL2CPP。HybridCLR 只支持 IL2CPPMono 后端不在討論范圍內(nèi)。Android 項(xiàng)目由于現(xiàn)在 Google Play 和國內(nèi)渠道對(duì) Target API Level 的要求越來越高很多項(xiàng)目把target API level提到了 33、34、35這個(gè)過程中只要正常使用 IL2CPP 并勾選 ARM64不會(huì)和 HybridCLR 產(chǎn)生直接沖突。但如果是很老的項(xiàng)目一直跑在 ARMv7 或 Mono 上最好先把構(gòu)建鏈路切干凈再談熱更。Unity 版本建議盡量用 LTS比如 2021.3 LTS、2022.3 LTS 或官方文檔當(dāng)前明確支持的版本。HybridCLR 的發(fā)布節(jié)奏通常能跟上主流 LTS用非 LTS 版本容易遭遇兼容性盲區(qū)。安裝時(shí)下載的是focus-creative-games/hybridclr_unity這份 Unity 側(cè)工程代碼版本要和項(xiàng)目 Unity 版本匹配別隨手拉最新版就往老項(xiàng)目里塞。3. 真機(jī)跑通全流程一個(gè)最小可熱更工程的搭建記錄3.1 安裝包和 Installer 到底做了什么接入時(shí)首先通過 Unity Package Manager 用 Git URL 把 HybridCLR 的 Unity 包加到工程里。拉取成功后菜單欄會(huì)出現(xiàn) HybridCLR 相關(guān)的入口。接下來執(zhí)行的是 HybridCLR - Installer這一步會(huì)往工程里寫一些必要的代碼更關(guān)鍵的是它會(huì)修改本地的 IL2CPP把解釋器相關(guān)模塊合入 il2cpp 的構(gòu)建鏈。也就是說它不只是往 Assets 里加幾個(gè)腳本還動(dòng)到了 Unity 編輯器安裝目錄下的 il2cpp 相關(guān)文件。這里有兩個(gè)容易踩的點(diǎn)。第一Installer 執(zhí)行時(shí)如果 Unity 正在占用相關(guān)文件或者殺毒軟件攔截了對(duì)安裝目錄的修改安裝可能“假成功”。我遇到過安裝后 Generate 時(shí)各種詭異報(bào)錯(cuò)重裝一次 HybridCLR 就好了。建議執(zhí)行完 Installer 后先做一次簡單的生成操作驗(yàn)證而不是直接開始打大包。第二升級(jí) Unity 小版本后最好重新執(zhí)行 Installer。IL2CPP 內(nèi)部文件結(jié)構(gòu)會(huì)隨版本變化舊的補(bǔ)丁不一定還能用。我們項(xiàng)目從 Unity 2021.3.16 升到 2021.3.31 時(shí)因?yàn)槁┝诉@一步打出來的包初始化階段直接崩潰排查了半天才發(fā)現(xiàn)是 installer 沒重跑。3.2 創(chuàng)建熱更程序集并在 Settings 里登記HybridCLR 需要知道哪些程序集要被當(dāng)作熱更程序集處理。官方推薦用 asmdef 組織但不是把文件夾命名為 HotUpdate 就行而是在工程里建一個(gè)真正的 Assembly Definition。我的做法是在 Assets 下建兩個(gè)目錄Assets/Scripts/Main主工程邏輯里面放Main.asmdef。Assets/Scripts/HotUpdate熱更邏輯里面放HotUpdate.asmdef。由于 HotUpdate 需要引用 Main 里定義的類型和接口在HotUpdate.asmdef的 Assembly Definition References 里加上 Main反之 Main 里不要引用 HotUpdate。這樣主工程干凈熱更程序集可以隨意引用它依賴的 AOT 庫。創(chuàng)建好 asmdef 后打開菜單HybridCLR - Settings把 HotUpdate 加進(jìn)熱更新程序集列表。Install 時(shí)官方腳本會(huì)自動(dòng)生成一套默認(rèn)配置里面通常已經(jīng)預(yù)設(shè)了 compile 用的 AOT 程序集列表和補(bǔ)充元數(shù)據(jù)列表。新工程用默認(rèn)配置其實(shí)就能跑通不需要一開始就手動(dòng)維護(hù)一堆列表。3.3 初始化的核心代碼補(bǔ)充元數(shù)據(jù)再加載熱更程序集接入代碼最核心的只有兩步先補(bǔ)充 AOT 元數(shù)據(jù)再Assembly.Load熱更 dll。補(bǔ)充元數(shù)據(jù)這一步是用HybridCLR.RuntimeApi.LoadMetadataForAOTAssembly把 AOT dll 的元數(shù)據(jù)喂給解釋器。注意每個(gè) dll 要單獨(dú)調(diào)用一次不能把多個(gè) dll 拼成一個(gè) byte 數(shù)組一次性傳進(jìn)去。這里直接放一份可運(yùn)行的初始化思路using System; using System.Reflection; using HybridCLR; using UnityEngine; public static class HotfixBootstrap { // 假設(shè)這些 dll 都已經(jīng)被打進(jìn)同一個(gè) AssetBundle // 并且以 TextAsset 形式加載 private static readonly string[] AotDllNames { mscorlib.dll, System.dll, System.Core.dll, UnityEngine.CoreModule.dll, Main.dll, }; private const string HotUpdateDllName HotUpdate.dll; public static void Start() { try { LoadAotMetadata(); LoadHotUpdateAssembly(); } catch (Exception e) { Debug.LogError($[Hotfix] 熱更啟動(dòng)失敗走 AOT 兜底邏輯. {e}); FallbackToAOT(); } } private static void LoadAotMetadata() { AssetBundle ab AssetBundle.LoadFromFile(GetBundlePath()); foreach (string dllName in AotDllNames) { TextAsset ta ab.LoadAssetTextAsset(dllName); if (ta null) { Debug.LogError($[Hotfix] 缺少 AOT 元數(shù)據(jù): {dllName}); continue; } // 補(bǔ)充元數(shù)據(jù)必須發(fā)生在熱更代碼調(diào)用相關(guān) AOT 泛型之前 RuntimeApi.LoadMetadataForAOTAssembly(ta.bytes, HomologousImageMode.SuperSet); } ab.Unload(false); } private static void LoadHotUpdateAssembly() { AssetBundle ab AssetBundle.LoadFromFile(GetBundlePath()); TextAsset dll ab.LoadAssetTextAsset(HotUpdateDllName); Assembly hotUpdateAssembly Assembly.Load(dll.bytes); Type entry hotUpdateAssembly.GetType(HotUpdate.GameMain); if (entry null) { Debug.LogError([Hotfix] 熱更入口類型不存在); return; } MethodInfo start entry.GetMethod(StartEntry); start?.Invoke(null, null); ab.Unload(false); } private static string GetBundlePath() { // 首包資源在 StreamingAssets后續(xù)更新資源在 persistentDataPath // 這里根據(jù)項(xiàng)目策略自行切換 return Application.streamingAssetsPath /hotupdate; } private static void FallbackToAOT() { // 你原有的啟動(dòng)邏輯 AOTMain.Start(); } }有幾個(gè)細(xì)節(jié)需要說明。HomologousImageMode.SuperSet是官方示例里很常用的模式意思是用包含超集信息的方式加載元數(shù)據(jù)對(duì)裁剪后的 dll 兼容性更好。如果你的 dll 完全沒裁剪可以用 Consistent 模式但項(xiàng)目一旦開了 Strip Engine Code經(jīng)常會(huì)出現(xiàn)某些類型被裁掉的情況所以用 SuperSet 在實(shí)際項(xiàng)目里更省心。補(bǔ)充元數(shù)據(jù)的順序一定要在加載熱更 dll 之前。你在熱更 dll 里寫的代碼可能用到了主工程的泛型方法解釋器在執(zhí)行時(shí)如果 AOT 側(cè)沒有現(xiàn)成函數(shù)實(shí)現(xiàn)就需要通過補(bǔ)充元數(shù)據(jù)去解析對(duì)應(yīng) IL。這個(gè)動(dòng)作發(fā)生得越晚越容易在詭異的位置拋出異常。不要直接在主工程里靜態(tài)調(diào)用熱更程序集里的類。上面代碼用反射拿HotUpdate.GameMain再調(diào)方法是我推薦的最小實(shí)現(xiàn)。真實(shí)項(xiàng)目里可以把這個(gè)入口抽象成一個(gè)接口放到 AOT 公共層熱更代碼提供一個(gè)實(shí)現(xiàn)這樣主工程只需要按需求反射加載熱更程序集再轉(zhuǎn)換成約定接口去調(diào)用比純反射更舒服。3.4 從 Generate/All 到 Android 打包代碼寫好后HybridCLR 的構(gòu)建流程不是直接點(diǎn) Unity 的 Build Player而是先執(zhí)行HybridCLR - Generate/All。這一步會(huì)完成幾件事把熱更程序集編譯成 dll、掃描代碼生成必要的橋接代碼、生成 AOT 泛型補(bǔ)充列表。也就是說橋接代碼和泛型列表不是純手工維護(hù)的而是在 Generate 階段自動(dòng)生成的。每次修改熱更代碼后如果你直接打包而忘了重新執(zhí)行 Generate/All很可能打出來的包運(yùn)行后行為異常因?yàn)闃蚪有畔]有同步過來。命令行構(gòu)建時(shí)也需要在打包前調(diào)用對(duì)應(yīng)接口常見寫法是using HybridCLR.Editor.Commands; using UnityEditor; using UnityEditor.Build; public static class BuildEntry { public static void BuildAndroid() { PrebuildCommand.GenerateAll(); BuildPlayerOptions options new BuildPlayerOptions(); options.scenes new[] { Assets/Scenes/Main.unity }; options.locationPathName Build/Android/demo.apk; options.target BuildTarget.Android; options.options BuildOptions.None; BuildPipeline.BuildPlayer(options); } }真機(jī)驗(yàn)證時(shí)Player Settings 里注意三點(diǎn)Scripting Backend 必須選 IL2CPPTarget Architecture 要勾選 ARM64很多中低端新機(jī)也已經(jīng)只有 64 位庫了至少你要保證包含 ARM64Strip Engine Code 可以暫時(shí)開著但首輪驗(yàn)證如果出現(xiàn)異常建議先關(guān)掉一次對(duì)比排查確認(rèn)是熱更鏈路問題還是裁剪問題。3.5 驗(yàn)證一次真正的不重裝更新首包裝完后寫一個(gè)最簡單的熱更驗(yàn)證入口在熱更程序集里做這樣一件事在屏幕中央顯示HotUpdate Version 1。裝到手機(jī)上確認(rèn)顯示正確。然后把代碼里的版本號(hào)改成HotUpdate Version 2重新 Generate/All重新打 AssetBundle但不要重新打 APK。把新的 AB 放到下載源手機(jī) App 啟動(dòng)后下載新 AB再次加載時(shí)如果屏幕顯示Version 2說明熱更已經(jīng)跑通。這一步是整個(gè)接入的“成人禮”。只要這個(gè)鏈路通了后面要做的就是把下載、校驗(yàn)、解壓、加載打磨成正式框架。我見過不少項(xiàng)目卡在“編輯器里改了代碼直接運(yùn)行是新的但熱更鏈路沒通”核心原因就是忘了驗(yàn)證從 AB 里加載的還是不是最新那版 dll。打包 AB 之前建議在 AB 文件名或 dll 里寫入版本號(hào)標(biāo)識(shí)啟動(dòng)時(shí)打印出來避免新舊資源混淆。4. 首包之后躲不開的坑元數(shù)據(jù)缺失、AOT 泛型與裁剪4.1 真機(jī) MissingMethodException 的排查路徑能把 Demo 跑通只代表最小鏈路沒問題。真實(shí)項(xiàng)目的第一個(gè)坎往往出現(xiàn)在把一部分業(yè)務(wù)代碼挪進(jìn)熱更程序集之后。我印象最深的一次報(bào)錯(cuò)是 Android 真機(jī)進(jìn)入某個(gè)界面直接拋ExecutionEngineException: Attempting to call method xxx for which no ahead of time (AOT) code was generated。在編輯器里怎么跑都沒事一上 IL2CPP 就崩。遇到這類錯(cuò)誤第一反應(yīng)不要只盯著報(bào)錯(cuò)的那一行函數(shù)而是按照這個(gè)順序排查初始化代碼是否真的執(zhí)行了。真機(jī)上熱更初始化可能被 SDK 或啟動(dòng)順序問題跳過先打日志確認(rèn)LoadMetadataForAOTAssembly每個(gè) dll 都成功了。元數(shù)據(jù)列表是否完整。報(bào)錯(cuò)類型如果是System.Collections.Generic.Dictionaryint, MyStruct之類的 AOT 泛型先查 System.dll、mscorlib.dll 的元數(shù)據(jù)是否被加載。報(bào)錯(cuò)方法是不是定義在熱更 dll 里但實(shí)現(xiàn)需要調(diào)用 AOT 側(cè)的泛型特化。這是最常見的情況。是否開啟了代碼裁剪裁剪把需要用到的元數(shù)據(jù)當(dāng)成“無用數(shù)據(jù)”干掉了。不要一上來就想著用“AOT 泛型引用列表”硬補(bǔ)。先搞清楚報(bào)錯(cuò)方法屬于哪個(gè)程序集、是不是泛型、泛型參數(shù)是不是值類型排查方向會(huì)清晰很多。4.2 AOT 泛型為什么不能靠事前祈禱規(guī)避AOT 泛型問題的本質(zhì)是編譯期和運(yùn)行期的信息不對(duì)等。IL2CPP 打包時(shí)只會(huì)把主工程代碼里實(shí)際引用過的泛型特化編譯出來。假如你有一個(gè)MyStruct只在熱更 dll 里出現(xiàn)了ListMyStruct而主工程從來沒有實(shí)例化過這個(gè)組合那么在 AOT 的機(jī)器碼里就真的沒有ListMyStruct的實(shí)現(xiàn)。程序運(yùn)行時(shí)發(fā)現(xiàn)需要它無論怎么找都找不到現(xiàn)成代碼。HybridCLR 給出的路徑是你想不到那我們就在運(yùn)行時(shí)讓解釋器去現(xiàn)讀 IL、現(xiàn)解釋執(zhí)行。所以補(bǔ)充元數(shù)據(jù)不只是湊個(gè)數(shù)它是給解釋器提供了“原料”。只要元數(shù)據(jù)里包含那個(gè)泛型方法的 IL解釋器就能自己把它跑起來不依賴 IL2CPP 現(xiàn)成機(jī)器碼。但在實(shí)際項(xiàng)目里我遇到過需要補(bǔ)充的元數(shù)據(jù)太多導(dǎo)致啟動(dòng)階段加載耗時(shí)上升的情況。后來我們做了個(gè)折中對(duì)性能敏感、且只在固定幾個(gè)類型之間使用的泛型盡量在主工程的 AOT 側(cè)提前打一次“引用錨點(diǎn)”讓它被 IL2CPP 編譯出來對(duì)業(yè)務(wù)里零散的泛型用法交給補(bǔ)充元數(shù)據(jù)解釋執(zhí)行。這樣既不出錯(cuò)性能也可控。4.3 link.xml 裁剪與混淆帶來的一連串問題元數(shù)據(jù)有了但如果構(gòu)建時(shí)裁剪器把 dll 里的元數(shù)據(jù)當(dāng)成“沒被引用”的垃圾裁掉加載元數(shù)據(jù)時(shí)一樣會(huì)失敗。HybridCLR 官方工程里通常會(huì)帶一份 link.xml 或者在 Installer 時(shí)配置好 keep 規(guī)則如果你是自己創(chuàng)建的新工程注意保留 AOT 程序集的相關(guān)節(jié)點(diǎn)。我們的教訓(xùn)是某次為了減包重打開 Strip Engine Code結(jié)果線上部分低端機(jī)開始隨機(jī)出現(xiàn)加載失敗。后來檢查發(fā)現(xiàn)裁剪配置沒有把第三方 SDK 里被熱更代碼反射調(diào)用的類型排除出去反射調(diào)用在 IL2CPP 裁剪后找不到類型。排查時(shí)可以先試著把Managed Stripping Level調(diào)到最低確認(rèn)問題消失再逐步調(diào)高裁減等級(jí)定位是哪個(gè)規(guī)則誤傷了類型。如果項(xiàng)目用了混淆或加固尤其是對(duì) dll 做二次處理的方案要和熱更鏈路分開對(duì)待。熱更 dll 自己可以加密混淆運(yùn)行時(shí)解密再Assembly.Load沒問題但 AOT 元數(shù)據(jù)那批 dll 盡量不要做會(huì)影響元數(shù)據(jù)結(jié)構(gòu)的混淆否則LoadMetadataForAOTAssembly時(shí)的模式校驗(yàn)可能直接不通過。排查這類問題有個(gè)技巧關(guān)閉混淆打一個(gè)包如果不再報(bào)錯(cuò)基本就是混淆規(guī)則或順序的問題。4.4 一次真實(shí)排查字典泛型在熱更里爆炸當(dāng)初我們把任務(wù)系統(tǒng)挪進(jìn)熱更程序集時(shí)熱更代碼里有這么一段Dictionaryint, TaskReward rewardMap new Dictionaryint, TaskReward();TaskReward是熱更程序集里的一個(gè)普通類int是值類型。這個(gè)寫法在 C# 里再普通不過但在 IL2CPP 熱更環(huán)境下它是一個(gè)典型的泛型特化組合主工程 AOT 側(cè)從來沒寫過Dictionaryint, TaskReward所以沒有現(xiàn)成 AOT 代碼。最終是靠補(bǔ)充元數(shù)據(jù)解決的。我們?cè)?AOT 元數(shù)據(jù)列表里帶上 System.dll字典泛型的實(shí)現(xiàn)定義在這里并在加載熱更 dll 之前調(diào)用LoadMetadataForAOTAssembly加載它解釋器拿到元數(shù)據(jù)后就能自己解釋執(zhí)行這個(gè)泛型方法。如果你也想臨時(shí)驗(yàn)證某個(gè)泛型問題是不是補(bǔ)充元數(shù)據(jù)能解決可以寫一段只包含該泛型操作的測(cè)試熱更代碼真機(jī)跑一次比在論壇上猜快得多。5. 與項(xiàng)目框架配套AB 打包、啟動(dòng)更新和版本保護(hù)5.1 熱更 dll 放 AssetBundle元數(shù)據(jù)放哪里熱更 dll 本質(zhì)上是一個(gè)二進(jìn)制文件你可以直接放服務(wù)器讓客戶端下載后寫到 persistentDataPath也可以塞進(jìn) AssetBundle。實(shí)戰(zhàn)上我更推薦塞 AssetBundle原因不是放不下一個(gè) dll而是項(xiàng)目本來就有資源更新鏈路復(fù)用同一套下載、校驗(yàn)、加載邏輯比另起一套文件下載穩(wěn)定得多。有一點(diǎn)經(jīng)驗(yàn)很重要不要把熱更 dll 用 Unity 的 TextAsset 直接打進(jìn) ResourcesResources 里的東西在包發(fā)布后是不能動(dòng)態(tài)替換的只適合放“永遠(yuǎn)不會(huì)變的 AOT 兜底版本”或某個(gè)基礎(chǔ)元數(shù)據(jù)。真正要更新的是放在 AssetBundle 里的那份 dll首包時(shí)可以把這個(gè) AB 同時(shí)放到 StreamingAssets Unity HybridCLR熱更新實(shí)戰(zhàn)：原理、接入順序與真機(jī)排坑
我到現(xiàn)在都記得第一次線上事故的場(chǎng)景一個(gè)已經(jīng)過審上架的手游運(yùn)營活動(dòng)發(fā)獎(jiǎng)勵(lì)的數(shù)值公式少取了一次隨機(jī)數(shù)玩家領(lǐng)到的獎(jiǎng)勵(lì)高了兩倍。服務(wù)端立刻封住漏洞但已經(jīng)安裝的客戶端代碼是死的發(fā)新版要走渠道審核少則一天多則一周那幾天項(xiàng)目組每個(gè)人臉上都寫著焦慮。那次之后我們整個(gè)團(tuán)隊(duì)把“代碼熱更新”從“以后再說”提到了“下周必須驗(yàn)證”的優(yōu)先級(jí)。最后選型、驗(yàn)證、接入的方案就是今天這篇要聊的 Unity HybridCLR 熱更新。如果只用一句話介紹HybridCLR 是一個(gè)基于 IL2CPP 的 C# 熱更新方案它能讓你的 Unity 項(xiàng)目在不重新打包上架、玩家不重新下載安裝包的情況下通過加載一段新的 C# 程序集來更新游戲邏輯。這篇文章是我自己從零把一個(gè) Demo 工程接入 HybridCLR再逐步推進(jìn)到真實(shí)項(xiàng)目的完整記錄。重點(diǎn)不是重復(fù)官方文檔而是告訴你接入順序、依賴方向、AOT 泛型問題這些文檔里不容易一次講透的東西以及我踩過的坑長什么樣。如果你是想評(píng)估熱更新方案的技術(shù)負(fù)責(zé)人、正在給老項(xiàng)目接熱更的 Unity 客戶端同學(xué)或者剛被分配要驗(yàn)證 HybridCLR 可行性的新手這篇應(yīng)該能幫你省下不少試錯(cuò)時(shí)間。讀完你應(yīng)該能知道它和 Lua 熱更、和 IDE 里的熱重載到底什么關(guān)系接入前工程要做什么體檢真機(jī)上跑通一個(gè)最小熱更工程需要哪幾步以及第一輪真機(jī)崩潰該怎么查。1. 為什么是 HybridCLR而不是 Lua 或者熱重載1.1 IL2CPP 把代碼焊死在哪里要理解 HybridCLR 的價(jià)值先得知道 Unity 的 IL2CPP 到底做了什么。在沒有 IL2CPP 的 Mono 時(shí)代C# 代碼會(huì)被編譯成 IL運(yùn)行時(shí)由 Mono 虛擬機(jī)解釋或 JIT 編譯執(zhí)行。那個(gè)年代想在 iOS 上做熱更新很麻煩因?yàn)樘O果明確禁止應(yīng)用在自己的沙盒里動(dòng)態(tài)生成可執(zhí)行代碼JIT 這條路在 iOS 上基本是堵死的。IL2CPP 是把 C# 先編譯成 IL再在構(gòu)建階段把 IL 轉(zhuǎn)成 C最后隨原生工程一起編譯成目標(biāo)平臺(tái)的機(jī)器碼。好處是啟動(dòng)快、性能好、代碼不容易被直接反編譯成原始 C#壞處也藏在這里所有 C# 邏輯都在編譯期被翻譯并“焊死”進(jìn)了原生二進(jìn)制運(yùn)行時(shí)已經(jīng)沒有一套能把新 IL 編譯成機(jī)器碼的機(jī)制了。這就好比你把菜譜都刻成了石碑讀者只能照著石碑做菜現(xiàn)在你拿到一張新菜譜卻沒有火源也沒有翻譯想按新菜譜做菜根本無從下手。HybridCLR 做的是在 IL2CPP 旁邊補(bǔ)了一個(gè)“解釋執(zhí)行器”讓新拿到的 C# 程序集也就是熱更 dll里的 IL 字節(jié)碼不經(jīng)過 JIT 也能被逐條解釋執(zhí)行。1.2 它和 xLua、ILRuntime 的本質(zhì)差異很多團(tuán)隊(duì)第一次聊熱更新聽到的往往是 xLua、tolua或者純 C# 的 ILRuntime。這里我直接按實(shí)際感受做個(gè)比較。Lua 方案的核心是“換語言”業(yè)務(wù)邏輯不寫在 C# 里而是寫 Lua運(yùn)行時(shí)由 C# 側(cè)的虛擬機(jī)解釋執(zhí)行。好處是生態(tài)成熟、很多老項(xiàng)目都在用代價(jià)是整個(gè)項(xiàng)目的核心玩法可能要從 C# 平移成 Lua維護(hù)一套雙語言邏輯團(tuán)隊(duì)里每個(gè)人都要會(huì) Lua出問題時(shí)要跨語言查堆棧代碼補(bǔ)全和重構(gòu)也不夠舒服。ILRuntime 是純 C# 的解釋器方案不需要換語言但它和 Unity 的 AOT 世界之間隔了一層自己的運(yùn)行時(shí)對(duì)某些 C# 特性的支持以及對(duì) Unity 引擎調(diào)用、泛型、值類型結(jié)構(gòu)的處理需要開發(fā)者額外注意。性能和兼容性一直在進(jìn)步但遇到冷門邊界總有“為什么這里不行”的疑惑。HybridCLR 選擇的是另一條路線盡可能貼近原生 CLR 的實(shí)現(xiàn)方式在 IL2CPP 的 AOT 基礎(chǔ)上加一個(gè)解釋器模塊并且用“補(bǔ)充元數(shù)據(jù)”的方式解決 AOT 泛型缺失的經(jīng)典問題。用下來最直觀的感受是它不是讓你把邏輯翻譯成另一種語言而是讓熱更 dll 里的 C# 代碼自己跑起來和主工程的 C# 代碼寫法差別不大。對(duì)比項(xiàng)Lua 系方案ILRuntimeHybridCLR業(yè)務(wù)語言Lua C#C#C#與 IL2CPP 關(guān)系獨(dú)立虛擬機(jī)獨(dú)立解釋器基于 IL2CPP 補(bǔ)充解釋能力學(xué)習(xí)成本需要掌握 Lua較低但邊界概念多較低重點(diǎn)是理解 AOT 與熱更分界泛型等邊界問題不受 IL2CPP 泛型影響有自己的處理通過補(bǔ)充元數(shù)據(jù)解決大多數(shù)社區(qū)活躍度高但偏向舊項(xiàng)目中高近幾年增長很快需要客觀說的是HybridCLR 本質(zhì)上是修改了 Unity 的 IL2CPP 構(gòu)建鏈路Unity 版本升級(jí)、IL2CPP 內(nèi)部實(shí)現(xiàn)調(diào)整都有可能影響它。所以它不是一個(gè)“裝一次永遠(yuǎn)不用管”的方案每次 Unity 升級(jí)或 HybridCLR 升級(jí)都要做回歸驗(yàn)證。這點(diǎn)后面章節(jié)會(huì)細(xì)說。1.3 先理清“熱更新”和“熱重載”不是一回事熱搜詞里出現(xiàn)了不少和熱更新相關(guān)的詞比如 Flutter 熱重載、IDEA 修改代碼熱更新、Nacos 配置熱更新。這些詞經(jīng)常被混在一起但它們解決的問題完全不同。Flutter 的熱重載本質(zhì)是開發(fā)期工具改完代碼按一下 R開發(fā)進(jìn)程把新的 widget 樹推給正在運(yùn)行的調(diào)試 App幫開發(fā)者快速看 UI 效果。它不面向線上玩家代碼改動(dòng)只在開發(fā)環(huán)境里生效。IDEA 里修改 Java 代碼后的熱更新是讓本地開發(fā)服務(wù)器不用重啟就能加載新類屬于開發(fā)效率工具的范圍。Nacos 配置熱更新更新的是配置項(xiàng)不是程序邏輯本身。而 Unity 項(xiàng)目里說的“代碼熱更新”指的是已經(jīng)安裝到玩家手機(jī)上的 App在不發(fā)新包的前提下從服務(wù)器拉取新的 C# 程序集并在本地執(zhí)行新邏輯。這是玩家可見的能力直接關(guān)系到線上事故的處理速度和上面那些開發(fā)期工具完全不是一個(gè)維度。所以有些同學(xué)問“我項(xiàng)目里用 IDE 熱重載很順是不是就不用 HybridCLR 了”答案顯然是否定的。2. 接入前先給工程“體檢”程序集、依賴方向、泛型用法2.1 依賴方向熱更代碼能引用什么不能引用什么接入 HybridCLR 最容易犯的錯(cuò)是直接拿一個(gè)已經(jīng)寫了兩三年的老工程把所有代碼都掃進(jìn)熱更程序集然后開始打包。正確的第一步是給工程劃分程序集邊界。Unity 項(xiàng)目里用 asmdef 把代碼分成多個(gè)程序集主工程里有一套專門給熱更代碼用的接口和公共代碼熱更代碼所在的程序集可以引用主工程的公共程序集但主工程的 AOT 代碼絕對(duì)不能反過來引用熱更程序集里的類型。一旦主工程靜態(tài)引用了熱更代碼里的類打 IL2CPP 包時(shí)就會(huì)把熱更代碼一起編進(jìn)去后續(xù)想替換邏輯就會(huì)非常別扭。我在項(xiàng)目里習(xí)慣的分層是這樣的AOT 主程序集啟動(dòng)流程、SDK 對(duì)接、資源管理、渲染相關(guān)、游戲的底層框架。AOT 公共接口層純接口和 DTO 定義比如戰(zhàn)斗結(jié)算接口、活動(dòng)模板接口供熱更代碼實(shí)現(xiàn)或調(diào)用。熱更程序集賽季玩法、活動(dòng)界面、數(shù)值表現(xiàn)、任務(wù)系統(tǒng)這類需要頻繁調(diào)整的邏輯。依賴方向是熱更層可以引用 AOT 公共接口層AOT 公共接口層不能引用熱更層。因?yàn)闊岣鼘邮沁\(yùn)行時(shí)才被加載的AOT 側(cè)的代碼在編譯期根本不知道它的存在兩者之間只能靠接口或反射溝通。2.2 重點(diǎn)檢查一遍泛型使用習(xí)慣體檢時(shí)另一個(gè)重點(diǎn)是泛型。C# 泛型在 AOT 編譯下有個(gè)天然矛盾IL2CPP 編譯器在打包時(shí)只會(huì)為主工程代碼里“顯式出現(xiàn)過的泛型實(shí)例化”生成機(jī)器碼。如果熱更代碼運(yùn)行時(shí)突然出現(xiàn)一個(gè) AOT 模塊里從未實(shí)例化過的泛型組合比如DictionaryMyStruct, intIL2CPP 那邊并沒有對(duì)應(yīng)的目標(biāo)代碼運(yùn)行時(shí)就會(huì)報(bào)類似AOT generic method can not be instantiated的錯(cuò)誤。HybridCLR 的解法是“補(bǔ)充元數(shù)據(jù) 解釋器兜底”。打包時(shí)項(xiàng)目會(huì)帶上 AOT 必需 dll比如 mscorlib、System、UnityEngine.CoreModule 這些的元數(shù)據(jù)運(yùn)行時(shí)先加載這些元數(shù)據(jù)讓解釋器能夠自己解析泛型方法的 IL 并執(zhí)行而不是必須依賴 IL2CPP 現(xiàn)成的機(jī)器碼。這并不代表你可以完全無視泛型。我建議在接入前把項(xiàng)目里“值類型 泛型容器混用”的地方掃一遍。比如大量使用Listint、Dictionaryint, MyEnum、Dictionarylong, MyStruct尤其是這些結(jié)構(gòu)體是活動(dòng)邏輯里臨時(shí)定義的時(shí)候要格外留意。這里不是說不能用而是你要意識(shí)到這類代碼會(huì)觸發(fā) AOT 泛型補(bǔ)充機(jī)制線上報(bào)錯(cuò)后排查成本會(huì)高一些。2.3 確認(rèn)版本兼容與目標(biāo)平臺(tái)體檢還包括兩個(gè)基礎(chǔ)問題項(xiàng)目用的 Unity 版本以及 Scripting Backend 是否已經(jīng)是 IL2CPP。HybridCLR 只支持 IL2CPPMono 后端不在討論范圍內(nèi)。Android 項(xiàng)目由于現(xiàn)在 Google Play 和國內(nèi)渠道對(duì) Target API Level 的要求越來越高很多項(xiàng)目把target API level提到了 33、34、35這個(gè)過程中只要正常使用 IL2CPP 并勾選 ARM64不會(huì)和 HybridCLR 產(chǎn)生直接沖突。但如果是很老的項(xiàng)目一直跑在 ARMv7 或 Mono 上最好先把構(gòu)建鏈路切干凈再談熱更。Unity 版本建議盡量用 LTS比如 2021.3 LTS、2022.3 LTS 或官方文檔當(dāng)前明確支持的版本。HybridCLR 的發(fā)布節(jié)奏通常能跟上主流 LTS用非 LTS 版本容易遭遇兼容性盲區(qū)。安裝時(shí)下載的是focus-creative-games/hybridclr_unity這份 Unity 側(cè)工程代碼版本要和項(xiàng)目 Unity 版本匹配別隨手拉最新版就往老項(xiàng)目里塞。3. 真機(jī)跑通全流程一個(gè)最小可熱更工程的搭建記錄3.1 安裝包和 Installer 到底做了什么接入時(shí)首先通過 Unity Package Manager 用 Git URL 把 HybridCLR 的 Unity 包加到工程里。拉取成功后菜單欄會(huì)出現(xiàn) HybridCLR 相關(guān)的入口。接下來執(zhí)行的是 HybridCLR - Installer這一步會(huì)往工程里寫一些必要的代碼更關(guān)鍵的是它會(huì)修改本地的 IL2CPP把解釋器相關(guān)模塊合入 il2cpp 的構(gòu)建鏈。也就是說它不只是往 Assets 里加幾個(gè)腳本還動(dòng)到了 Unity 編輯器安裝目錄下的 il2cpp 相關(guān)文件。這里有兩個(gè)容易踩的點(diǎn)。第一Installer 執(zhí)行時(shí)如果 Unity 正在占用相關(guān)文件或者殺毒軟件攔截了對(duì)安裝目錄的修改安裝可能“假成功”。我遇到過安裝后 Generate 時(shí)各種詭異報(bào)錯(cuò)重裝一次 HybridCLR 就好了。建議執(zhí)行完 Installer 后先做一次簡單的生成操作驗(yàn)證而不是直接開始打大包。第二升級(jí) Unity 小版本后最好重新執(zhí)行 Installer。IL2CPP 內(nèi)部文件結(jié)構(gòu)會(huì)隨版本變化舊的補(bǔ)丁不一定還能用。我們項(xiàng)目從 Unity 2021.3.16 升到 2021.3.31 時(shí)因?yàn)槁┝诉@一步打出來的包初始化階段直接崩潰排查了半天才發(fā)現(xiàn)是 installer 沒重跑。3.2 創(chuàng)建熱更程序集并在 Settings 里登記HybridCLR 需要知道哪些程序集要被當(dāng)作熱更程序集處理。官方推薦用 asmdef 組織但不是把文件夾命名為 HotUpdate 就行而是在工程里建一個(gè)真正的 Assembly Definition。我的做法是在 Assets 下建兩個(gè)目錄Assets/Scripts/Main主工程邏輯里面放Main.asmdef。Assets/Scripts/HotUpdate熱更邏輯里面放HotUpdate.asmdef。由于 HotUpdate 需要引用 Main 里定義的類型和接口在HotUpdate.asmdef的 Assembly Definition References 里加上 Main反之 Main 里不要引用 HotUpdate。這樣主工程干凈熱更程序集可以隨意引用它依賴的 AOT 庫。創(chuàng)建好 asmdef 后打開菜單HybridCLR - Settings把 HotUpdate 加進(jìn)熱更新程序集列表。Install 時(shí)官方腳本會(huì)自動(dòng)生成一套默認(rèn)配置里面通常已經(jīng)預(yù)設(shè)了 compile 用的 AOT 程序集列表和補(bǔ)充元數(shù)據(jù)列表。新工程用默認(rèn)配置其實(shí)就能跑通不需要一開始就手動(dòng)維護(hù)一堆列表。3.3 初始化的核心代碼補(bǔ)充元數(shù)據(jù)再加載熱更程序集接入代碼最核心的只有兩步先補(bǔ)充 AOT 元數(shù)據(jù)再Assembly.Load熱更 dll。補(bǔ)充元數(shù)據(jù)這一步是用HybridCLR.RuntimeApi.LoadMetadataForAOTAssembly把 AOT dll 的元數(shù)據(jù)喂給解釋器。注意每個(gè) dll 要單獨(dú)調(diào)用一次不能把多個(gè) dll 拼成一個(gè) byte 數(shù)組一次性傳進(jìn)去。這里直接放一份可運(yùn)行的初始化思路using System; using System.Reflection; using HybridCLR; using UnityEngine; public static class HotfixBootstrap { // 假設(shè)這些 dll 都已經(jīng)被打進(jìn)同一個(gè) AssetBundle // 并且以 TextAsset 形式加載 private static readonly string[] AotDllNames { mscorlib.dll, System.dll, System.Core.dll, UnityEngine.CoreModule.dll, Main.dll, }; private const string HotUpdateDllName HotUpdate.dll; public static void Start() { try { LoadAotMetadata(); LoadHotUpdateAssembly(); } catch (Exception e) { Debug.LogError($[Hotfix] 熱更啟動(dòng)失敗走 AOT 兜底邏輯. {e}); FallbackToAOT(); } } private static void LoadAotMetadata() { AssetBundle ab AssetBundle.LoadFromFile(GetBundlePath()); foreach (string dllName in AotDllNames) { TextAsset ta ab.LoadAssetTextAsset(dllName); if (ta null) { Debug.LogError($[Hotfix] 缺少 AOT 元數(shù)據(jù): {dllName}); continue; } // 補(bǔ)充元數(shù)據(jù)必須發(fā)生在熱更代碼調(diào)用相關(guān) AOT 泛型之前 RuntimeApi.LoadMetadataForAOTAssembly(ta.bytes, HomologousImageMode.SuperSet); } ab.Unload(false); } private static void LoadHotUpdateAssembly() { AssetBundle ab AssetBundle.LoadFromFile(GetBundlePath()); TextAsset dll ab.LoadAssetTextAsset(HotUpdateDllName); Assembly hotUpdateAssembly Assembly.Load(dll.bytes); Type entry hotUpdateAssembly.GetType(HotUpdate.GameMain); if (entry null) { Debug.LogError([Hotfix] 熱更入口類型不存在); return; } MethodInfo start entry.GetMethod(StartEntry); start?.Invoke(null, null); ab.Unload(false); } private static string GetBundlePath() { // 首包資源在 StreamingAssets后續(xù)更新資源在 persistentDataPath // 這里根據(jù)項(xiàng)目策略自行切換 return Application.streamingAssetsPath /hotupdate; } private static void FallbackToAOT() { // 你原有的啟動(dòng)邏輯 AOTMain.Start(); } }有幾個(gè)細(xì)節(jié)需要說明。HomologousImageMode.SuperSet是官方示例里很常用的模式意思是用包含超集信息的方式加載元數(shù)據(jù)對(duì)裁剪后的 dll 兼容性更好。如果你的 dll 完全沒裁剪可以用 Consistent 模式但項(xiàng)目一旦開了 Strip Engine Code經(jīng)常會(huì)出現(xiàn)某些類型被裁掉的情況所以用 SuperSet 在實(shí)際項(xiàng)目里更省心。補(bǔ)充元數(shù)據(jù)的順序一定要在加載熱更 dll 之前。你在熱更 dll 里寫的代碼可能用到了主工程的泛型方法解釋器在執(zhí)行時(shí)如果 AOT 側(cè)沒有現(xiàn)成函數(shù)實(shí)現(xiàn)就需要通過補(bǔ)充元數(shù)據(jù)去解析對(duì)應(yīng) IL。這個(gè)動(dòng)作發(fā)生得越晚越容易在詭異的位置拋出異常。不要直接在主工程里靜態(tài)調(diào)用熱更程序集里的類。上面代碼用反射拿HotUpdate.GameMain再調(diào)方法是我推薦的最小實(shí)現(xiàn)。真實(shí)項(xiàng)目里可以把這個(gè)入口抽象成一個(gè)接口放到 AOT 公共層熱更代碼提供一個(gè)實(shí)現(xiàn)這樣主工程只需要按需求反射加載熱更程序集再轉(zhuǎn)換成約定接口去調(diào)用比純反射更舒服。3.4 從 Generate/All 到 Android 打包代碼寫好后HybridCLR 的構(gòu)建流程不是直接點(diǎn) Unity 的 Build Player而是先執(zhí)行HybridCLR - Generate/All。這一步會(huì)完成幾件事把熱更程序集編譯成 dll、掃描代碼生成必要的橋接代碼、生成 AOT 泛型補(bǔ)充列表。也就是說橋接代碼和泛型列表不是純手工維護(hù)的而是在 Generate 階段自動(dòng)生成的。每次修改熱更代碼后如果你直接打包而忘了重新執(zhí)行 Generate/All很可能打出來的包運(yùn)行后行為異常因?yàn)闃蚪有畔]有同步過來。命令行構(gòu)建時(shí)也需要在打包前調(diào)用對(duì)應(yīng)接口常見寫法是using HybridCLR.Editor.Commands; using UnityEditor; using UnityEditor.Build; public static class BuildEntry { public static void BuildAndroid() { PrebuildCommand.GenerateAll(); BuildPlayerOptions options new BuildPlayerOptions(); options.scenes new[] { Assets/Scenes/Main.unity }; options.locationPathName Build/Android/demo.apk; options.target BuildTarget.Android; options.options BuildOptions.None; BuildPipeline.BuildPlayer(options); } }真機(jī)驗(yàn)證時(shí)Player Settings 里注意三點(diǎn)Scripting Backend 必須選 IL2CPPTarget Architecture 要勾選 ARM64很多中低端新機(jī)也已經(jīng)只有 64 位庫了至少你要保證包含 ARM64Strip Engine Code 可以暫時(shí)開著但首輪驗(yàn)證如果出現(xiàn)異常建議先關(guān)掉一次對(duì)比排查確認(rèn)是熱更鏈路問題還是裁剪問題。3.5 驗(yàn)證一次真正的不重裝更新首包裝完后寫一個(gè)最簡單的熱更驗(yàn)證入口在熱更程序集里做這樣一件事在屏幕中央顯示HotUpdate Version 1。裝到手機(jī)上確認(rèn)顯示正確。然后把代碼里的版本號(hào)改成HotUpdate Version 2重新 Generate/All重新打 AssetBundle但不要重新打 APK。把新的 AB 放到下載源手機(jī) App 啟動(dòng)后下載新 AB再次加載時(shí)如果屏幕顯示Version 2說明熱更已經(jīng)跑通。這一步是整個(gè)接入的“成人禮”。只要這個(gè)鏈路通了后面要做的就是把下載、校驗(yàn)、解壓、加載打磨成正式框架。我見過不少項(xiàng)目卡在“編輯器里改了代碼直接運(yùn)行是新的但熱更鏈路沒通”核心原因就是忘了驗(yàn)證從 AB 里加載的還是不是最新那版 dll。打包 AB 之前建議在 AB 文件名或 dll 里寫入版本號(hào)標(biāo)識(shí)啟動(dòng)時(shí)打印出來避免新舊資源混淆。4. 首包之后躲不開的坑元數(shù)據(jù)缺失、AOT 泛型與裁剪4.1 真機(jī) MissingMethodException 的排查路徑能把 Demo 跑通只代表最小鏈路沒問題。真實(shí)項(xiàng)目的第一個(gè)坎往往出現(xiàn)在把一部分業(yè)務(wù)代碼挪進(jìn)熱更程序集之后。我印象最深的一次報(bào)錯(cuò)是 Android 真機(jī)進(jìn)入某個(gè)界面直接拋ExecutionEngineException: Attempting to call method xxx for which no ahead of time (AOT) code was generated。在編輯器里怎么跑都沒事一上 IL2CPP 就崩。遇到這類錯(cuò)誤第一反應(yīng)不要只盯著報(bào)錯(cuò)的那一行函數(shù)而是按照這個(gè)順序排查初始化代碼是否真的執(zhí)行了。真機(jī)上熱更初始化可能被 SDK 或啟動(dòng)順序問題跳過先打日志確認(rèn)LoadMetadataForAOTAssembly每個(gè) dll 都成功了。元數(shù)據(jù)列表是否完整。報(bào)錯(cuò)類型如果是System.Collections.Generic.Dictionaryint, MyStruct之類的 AOT 泛型先查 System.dll、mscorlib.dll 的元數(shù)據(jù)是否被加載。報(bào)錯(cuò)方法是不是定義在熱更 dll 里但實(shí)現(xiàn)需要調(diào)用 AOT 側(cè)的泛型特化。這是最常見的情況。是否開啟了代碼裁剪裁剪把需要用到的元數(shù)據(jù)當(dāng)成“無用數(shù)據(jù)”干掉了。不要一上來就想著用“AOT 泛型引用列表”硬補(bǔ)。先搞清楚報(bào)錯(cuò)方法屬于哪個(gè)程序集、是不是泛型、泛型參數(shù)是不是值類型排查方向會(huì)清晰很多。4.2 AOT 泛型為什么不能靠事前祈禱規(guī)避AOT 泛型問題的本質(zhì)是編譯期和運(yùn)行期的信息不對(duì)等。IL2CPP 打包時(shí)只會(huì)把主工程代碼里實(shí)際引用過的泛型特化編譯出來。假如你有一個(gè)MyStruct只在熱更 dll 里出現(xiàn)了ListMyStruct而主工程從來沒有實(shí)例化過這個(gè)組合那么在 AOT 的機(jī)器碼里就真的沒有ListMyStruct的實(shí)現(xiàn)。程序運(yùn)行時(shí)發(fā)現(xiàn)需要它無論怎么找都找不到現(xiàn)成代碼。HybridCLR 給出的路徑是你想不到那我們就在運(yùn)行時(shí)讓解釋器去現(xiàn)讀 IL、現(xiàn)解釋執(zhí)行。所以補(bǔ)充元數(shù)據(jù)不只是湊個(gè)數(shù)它是給解釋器提供了“原料”。只要元數(shù)據(jù)里包含那個(gè)泛型方法的 IL解釋器就能自己把它跑起來不依賴 IL2CPP 現(xiàn)成機(jī)器碼。但在實(shí)際項(xiàng)目里我遇到過需要補(bǔ)充的元數(shù)據(jù)太多導(dǎo)致啟動(dòng)階段加載耗時(shí)上升的情況。后來我們做了個(gè)折中對(duì)性能敏感、且只在固定幾個(gè)類型之間使用的泛型盡量在主工程的 AOT 側(cè)提前打一次“引用錨點(diǎn)”讓它被 IL2CPP 編譯出來對(duì)業(yè)務(wù)里零散的泛型用法交給補(bǔ)充元數(shù)據(jù)解釋執(zhí)行。這樣既不出錯(cuò)性能也可控。4.3 link.xml 裁剪與混淆帶來的一連串問題元數(shù)據(jù)有了但如果構(gòu)建時(shí)裁剪器把 dll 里的元數(shù)據(jù)當(dāng)成“沒被引用”的垃圾裁掉加載元數(shù)據(jù)時(shí)一樣會(huì)失敗。HybridCLR 官方工程里通常會(huì)帶一份 link.xml 或者在 Installer 時(shí)配置好 keep 規(guī)則如果你是自己創(chuàng)建的新工程注意保留 AOT 程序集的相關(guān)節(jié)點(diǎn)。我們的教訓(xùn)是某次為了減包重打開 Strip Engine Code結(jié)果線上部分低端機(jī)開始隨機(jī)出現(xiàn)加載失敗。后來檢查發(fā)現(xiàn)裁剪配置沒有把第三方 SDK 里被熱更代碼反射調(diào)用的類型排除出去反射調(diào)用在 IL2CPP 裁剪后找不到類型。排查時(shí)可以先試著把Managed Stripping Level調(diào)到最低確認(rèn)問題消失再逐步調(diào)高裁減等級(jí)定位是哪個(gè)規(guī)則誤傷了類型。如果項(xiàng)目用了混淆或加固尤其是對(duì) dll 做二次處理的方案要和熱更鏈路分開對(duì)待。熱更 dll 自己可以加密混淆運(yùn)行時(shí)解密再Assembly.Load沒問題但 AOT 元數(shù)據(jù)那批 dll 盡量不要做會(huì)影響元數(shù)據(jù)結(jié)構(gòu)的混淆否則LoadMetadataForAOTAssembly時(shí)的模式校驗(yàn)可能直接不通過。排查這類問題有個(gè)技巧關(guān)閉混淆打一個(gè)包如果不再報(bào)錯(cuò)基本就是混淆規(guī)則或順序的問題。4.4 一次真實(shí)排查字典泛型在熱更里爆炸當(dāng)初我們把任務(wù)系統(tǒng)挪進(jìn)熱更程序集時(shí)熱更代碼里有這么一段Dictionaryint, TaskReward rewardMap new Dictionaryint, TaskReward();TaskReward是熱更程序集里的一個(gè)普通類int是值類型。這個(gè)寫法在 C# 里再普通不過但在 IL2CPP 熱更環(huán)境下它是一個(gè)典型的泛型特化組合主工程 AOT 側(cè)從來沒寫過Dictionaryint, TaskReward所以沒有現(xiàn)成 AOT 代碼。最終是靠補(bǔ)充元數(shù)據(jù)解決的。我們?cè)?AOT 元數(shù)據(jù)列表里帶上 System.dll字典泛型的實(shí)現(xiàn)定義在這里并在加載熱更 dll 之前調(diào)用LoadMetadataForAOTAssembly加載它解釋器拿到元數(shù)據(jù)后就能自己解釋執(zhí)行這個(gè)泛型方法。如果你也想臨時(shí)驗(yàn)證某個(gè)泛型問題是不是補(bǔ)充元數(shù)據(jù)能解決可以寫一段只包含該泛型操作的測(cè)試熱更代碼真機(jī)跑一次比在論壇上猜快得多。5. 與項(xiàng)目框架配套AB 打包、啟動(dòng)更新和版本保護(hù)5.1 熱更 dll 放 AssetBundle元數(shù)據(jù)放哪里熱更 dll 本質(zhì)上是一個(gè)二進(jìn)制文件你可以直接放服務(wù)器讓客戶端下載后寫到 persistentDataPath也可以塞進(jìn) AssetBundle。實(shí)戰(zhàn)上我更推薦塞 AssetBundle原因不是放不下一個(gè) dll而是項(xiàng)目本來就有資源更新鏈路復(fù)用同一套下載、校驗(yàn)、加載邏輯比另起一套文件下載穩(wěn)定得多。有一點(diǎn)經(jīng)驗(yàn)很重要不要把熱更 dll 用 Unity 的 TextAsset 直接打進(jìn) ResourcesResources 里的東西在包發(fā)布后是不能動(dòng)態(tài)替換的只適合放“永遠(yuǎn)不會(huì)變的 AOT 兜底版本”或某個(gè)基礎(chǔ)元數(shù)據(jù)。真正要更新的是放在 AssetBundle 里的那份 dll首包時(shí)可以把這個(gè) AB 同時(shí)放到 StreamingAssets