Unity引擎Mod架構解析：BepInEx在Mono與IL2CPP下的運行差異、Harmony動態鉤子與程式集注入

引言：Unity引擎Mod開發的底層運行邏輯

Unity引擎構成了當今獨立遊戲與中量級PC商業作品的半壁江山，從多人連線生存爆款《幻獸帕魯》、《致命公司》（Lethal Company）、《瓦爾海姆》（Valheim），到複雜的模擬經營大作《天際線2》與《戴森球計劃》，均基於Unity開發。與傳統依靠解包重寫專屬資源包（如虛幻引擎的pak檔案）或註冊聲明式外掛記錄（如B社Creation引擎的esp/esm）的Mod開發模式截然不同，Unity作品的Mod開發深深植根於.NET與C#生態體系。

在Unity遊戲中實現功能擴展或玩法修改，通常無需替換磁碟上的原始資源，而是依託運行時的記憶體程式集動態修補與方法攔截（In-Memory Method Hooking）。在這一Mod生態的核心，坐落著兩大基石工具：作為開源引導啟動框架的BepInEx（Bepis Injector Extensible），以及由Andreas Pardeike開發的著名動態補丁庫Harmony。

然而，許多Mod創作者與玩家在跨遊戲移植或安裝Mod時，經常遭遇遊戲瞬間閃退、鉤子完全失效或控制台報錯的頑疾。這背後的根源在於Unity底層編譯管線的重大分野：經典的Mono託管後端與預先編譯的IL2CPP（Intermediate Language to C++）原生後端之間存在著不可逾越的底層架構鴻溝。

腳本後端分野：Mono與IL2CPP架構剖析

遊戲開發商在將Unity專案打包導出為PC可執行程序時，必須在兩大本質不同的腳本後端編譯模式中二選一：

【C#原始碼腳本：遊戲核心邏輯】
             │
             ▼
【Roslyn / Unity C#編譯器】 ---> 公共中間語言 (CIL 位元組碼)
             │
             ├─────────────────────────────────────────┐
             ▼                                         ▼
    【Mono 腳本後端路徑】                     【IL2CPP 腳本後端路徑】
- 將CIL打包至託管程式集 (DLL)             - IL2CPP轉譯器將CIL程式碼批量翻譯為C++
- 輸出 Assembly-CSharp.dll 等標準庫       - 平台原生編譯器輸出 GameAssembly.dll
- 遊戲運行時由 Mono JIT 虛擬機執行         - 元數據剝離至獨立的 global-metadata.dat
- 完整保留反射元數據，極易反編譯閱讀       - 純機器原生碼，徹底移除運行時CLR虛擬機

Mono腳本後端

在採用Mono模式編譯的遊戲中，所有的核心玩法系統、怪物AI、角色屬性等邏輯，均被編譯為標準的.NET中間語言（CIL）並封裝在Managed/Assembly-CSharp.dll等動態連結庫中。

• 運行時虛擬機：遊戲啟動時，內嵌的Mono JIT（即時編譯）虛擬機會加載並執行這些CIL位元組碼。
• 元數據高度完整：所有的類別名、方法簽名、私有欄位以及資料類型定義均完好無損地保存在程式集元數據中。
• Mod可逆性極高：開發者可以使用dnSpy或ILSpy等逆向工具，以接近100%的還原度直接查看並修改遊戲原始C#源碼，透過反射機制在運行時無縫掛鉤任何方法。

IL2CPP腳本後端

而採用IL2CPP編譯的遊戲，其構建流程經歷了徹底的範式轉變：

• C++程式碼轉譯：CIL位元組碼會被Unity的IL2CPP工具鏈強行轉譯為數以萬計的原生C++原始檔案。
• 機器碼硬編譯：這些C++程式碼隨後被Clang或MSVC等系統級編譯器直接硬編譯為平台原生的動態連結庫——GameAssembly.dll。
• 元數據剝離與混淆：整個.NET公共語言運行庫（CLR）在運行時被完全剔除。類型定義和字串常數被打包抽離到高度混淆的二進位檔案global-metadata.dat中。
• Modding壁壘：遊戲在記憶體中運行的是純粹的組合語言機器指令，不存在任何可直接執行的託管程式集。傳統的C# Mod如果直接丟進遊戲目錄，會因缺乏.NET運行環境而直接失效。

BepInEx注入引導架構與動態代理

BepInEx之所以能夠在一個封閉的原生Unity行程中強行執行第三方Mod邏輯，其核心依賴於Windows動態連結庫的**代理劫持（DLL Proxy Hijacking）**機制。

Doorstop代理劫持鏈路

Windows作業系統在加載可執行程序依賴的動態連結庫時，預設優先檢索程式根目錄，其次才會檢索系統核心目錄（C:\Windows\System32）。BepInEx充分利用了這一系統特性：

1. 偽裝代理DLL：BepInEx在遊戲根目錄下放置一個同名的系統庫偽裝檔案，最常見的包括winhttp.dll、version.dll或doorstop.dll。
2. 攔截主執行緒控制權：當作業系統的PE加載器啟動遊戲主程序時，它會優先將遊戲根目錄下的偽裝winhttp.dll載入記憶體空間。
3. 拉起.NET引導環境：該代理DLL會迅速初始化Doorstop引導器，在Unity引擎的主初始化程式碼奪取控制權之前，強行在當前行程中掛載BepInEx.Preloader.dll與BepInEx.Core.dll。
4. 外掛掃描與分發：基礎運行環境就緒後，BepInEx會喚起獨立除錯主控台（若開啟），綁定日誌輸出管線，並掃描BepInEx/plugins/目錄下的所有已編譯Mod程式集。

BepInEx 5 與 BepInEx 6：跨越IL2CPP的Interop橋樑

• BepInEx 5：專為Mono架構打造的黃金版本。所有外掛繼承自BaseUnityPlugin基類，直接借助宿主行程自帶的Mono虛擬機進行高效加載與執行。
• BepInEx 6：採用模組化重構的大版本，核心使命是攻克IL2CPP架構的Mod難題。針對IL2CPP遊戲，BepInEx 6深度集成了Il2CppInterop（前身為Unhollower）技術。在遊戲首次啟動時，它會自動逆向掃描GameAssembly.dll與global-metadata.dat，並在BepInEx/interop/目錄下即時反向生成數千個由C#編寫的虛擬代理包裝程式集。Mod開發者只需像平常一樣編寫物件導向的C#程式碼，底層便會自動將調用封送（Marshal）映射到原生的C++物理記憶體位址上。

Harmony動態掛鉤：無損記憶體方法修補藝術

在BepInEx成功將程式碼載入記憶體後，具體的玩法修改則主要依賴Harmony框架來完成。Harmony徹底摒棄了修改磁碟檔案的落後方式，透過在JIT編譯器準備執行方法時，在記憶體中直接重寫方法序言（Method Prologue），插入跳轉指令來實現無損攔截。

四大核心補丁類型

【宿主遊戲方法調用：如 PlayerController.TakeDamage(float amount)】
           │
           ▼
【Harmony Prefix 前置補丁】 ---> 返回 true (繼續原邏輯) 或 返回 false (阻斷原方法)
           │
           ▼
【遊戲原始方法執行：計算血量扣除】
           │
           ▼
【Harmony Postfix 後置補丁】 ---> 讀取/覆寫返回值 (__result) 或修改遊戲全域狀態
           │
           ▼
【Harmony Finalizer 終結者】 ---> 捕獲未處理的運行時例外，防止遊戲閃退

1. 前置補丁（[HarmonyPrefix]）：
   • 在原始方法執行之前的一瞬間搶先運行。
   • 具備修改入參的能力（例如在扣血邏輯執行前，直接將amount乘以0.5實現減傷）。
   • 執行阻斷權：若Prefix方法返回false，遊戲將徹底跳過原方法的後續執行，直接轉入返回階段。
2. 後置補丁（[HarmonyPostfix]）：
   • 在原始方法完全執行完畢後立即被調用。
   • 能夠使用特殊的ref __result參數，讀取甚至強行篡改原始方法的返回值（例如將商店道具的售價強制改寫為0）。
   • 適合用於觸發伴隨事件（如製作物品成功後順便發放成就）。
3. 轉譯器補丁（[HarmonyTranspiler]）：
   • 難度最高也是功能最強的底層補丁。它將方法的原始CIL位元組碼以指令序列（IEnumerable of CodeInstruction）的形式暴露給開發者。
   • 開發者可以直接在位元組碼層面精準增刪改操作碼（OpCode），例如將常數載入指令ldc.i4.0精準替換為ldc.i4.1，實現手術刀級別的微觀邏輯篡改。
4. 終結器補丁（[HarmonyFinalizer]）：
   • 充當包圍在被修補方法外圍的動態try/finally保護層。它能夠捕獲並吞沒拋出的嚴重未處理例外，防止因Mod內部邏輯偶發報錯而導致整個遊戲閃退崩潰。

故障診斷矩陣：Unity Mod常見失效與排查指南

當Unity Mod無法生效或引發遊戲崩潰時，請對照以下底層架構矩陣排查原因：

在配置大型Mod整合包、除錯程式集加載衝突或編寫專屬C#擴充外掛時，參考365Finds上的深度技術評測與運行時架構指南，能幫助創作者從底層虛擬機的視角精準解決相容問題。透徹理解Mono與IL2CPP在記憶體模型與動態掛鉤機制上的本質差異，是確保Unity Mod體系長期穩定運行的核心保證。

參考資料

• Scripting backends - Unity Manual
• BepInEx Documentation
• Harmony 2 - Harmony Documentation
• Reflection in .NET - .NET | Microsoft Learn