1. 项目概述：为什么选择BepInEx作为你的模组开发起点？

如果你是一个Unity游戏的狂热玩家，看着社区里层出不穷的模组（Mod）心痒难耐，或者你本身就是一名开发者，想为自己喜欢的游戏注入新的灵魂，那么“如何开始”这个问题一定困扰过你。市面上有各种模组框架，比如MelonLoader、Unity Mod Manager等，但为什么我们今天要聚焦于BepInEx？答案很简单：它几乎是当前Unity游戏模组开发领域，尤其是对热门独立游戏和部分商业游戏进行深度修改时，最强大、最稳定、社区支持最广泛的框架之一。从《雨中冒险2》（Risk of Rain 2）到《英灵神殿》（Valheim），再到《太吾绘卷》，无数成功的模组都构建在BepInEx之上。

BepInEx的核心魅力在于其“非侵入性”和“高兼容性”。它不需要你修改游戏的原生程序集，而是通过一个精巧的启动器（Bootstrap）在游戏启动时注入，并加载你编写的插件（Plugin）。这就像给游戏装了一个“外挂大脑”，既能指挥游戏执行新逻辑，又不会破坏其原有的“身体结构”。对于开发者而言，这意味着更低的入门门槛和更安全的调试环境——你的代码错误通常只会导致插件加载失败，而不会直接让游戏崩溃。本指南的目标，就是带你从零开始，穿越从环境配置、代码编写、调试到发布的完整流程，让你不仅能做出一个“Hello World”式的简单模组，更能理解其背后的运行机制，从而有能力去实现那些天马行空的创意。

2. 核心环境搭建与工具链配置

工欲善其事，必先利其器。开发BepInEx插件，你需要的不仅仅是一个代码编辑器。

2.1 基础环境准备：.NET与Unity版本的对齐

BepInEx插件本质上是使用C#编写的.NET程序集。因此，第一步是确保你的开发环境与目标游戏所使用的.NET框架及Unity版本匹配。这是一个极易被忽略但至关重要的步骤。

1. 确定目标游戏的运行环境：大多数使用BepInEx的Unity游戏是基于.NET Framework 4.x（如4.7.2）或.NET Standard 2.0构建的。你可以通过查看游戏目录下的<GameName>_Data/Managed/文件夹中的核心程序集（如Assembly-CSharp.dll）的属性来确认。更简单的方法是查阅该游戏的模组社区Wiki或BepInEx的发布页，通常会明确写明所需的.NET版本。

2. 安装对应版本的.NET开发包（SDK）：如果你开发的是面向较新游戏（使用Unity 2020+）的插件，可能需要安装.NET 6/8 SDK。但对于绝大多数存量游戏，你需要的是**.NET Framework 4.7.2或4.8的开发者工具包**。这并非SDK，而是确保你的Visual Studio等IDE能正确编译针对该框架的项目。通常，安装最新版Visual Studio时勾选“.NET桌面开发”工作负载即可。

3. Unity版本关联：你不需要安装完整的Unity编辑器来开发插件，但你需要对应游戏版本的UnityEngine.dll和UnityEngine.CoreModule.dll等核心库。这些库文件可以直接从目标游戏的Managed文件夹中获取。在Visual Studio中创建项目后，将这些DLL作为引用添加进去，而不是引用你自己安装的Unity编辑器中的DLL，这是保证兼容性的关键。

注意：绝对不要从Unity Hub安装一个版本号接近的Unity来获取库文件。游戏发布时使用的Unity版本可能包含特定的补丁或模块，直接使用游戏本体的DLL是唯一可靠的方法。

2.2 开发IDE与关键插件选择

Visual Studio 2022 Community（首选）：免费、功能强大，对C#和.NET开发支持最好。确保安装时包含“.NET桌面开发”和“使用C++的桌面开发”（部分游戏依赖本地库）工作负载。

关键插件安装：

• HarmonyX：这是BepInEx用于“打补丁”（Patch）的核心库的现代分支。你需要在NuGet包管理器中搜索并安装Lib.Harmony。它将允许你拦截、修改游戏原有的方法。
• BepInEx.Core库引用：你不是直接安装BepInEx的NuGet包（通常没有官方包）。正确做法是：从BepInEx的GitHub发布页下载对应版本的BepInEx.dll（通常位于BepInEx/core/目录下），然后在你的项目中直接添加对这个DLL文件的引用。

项目结构初始化：

1. 在VS中新建一个“类库(.NET Framework)”项目，目标框架选择与你之前确定的游戏环境一致的版本（如.NET Framework 4.7.2）。
2. 将游戏Managed文件夹下的UnityEngine.dll、UnityEngine.CoreModule.dll以及下载的BepInEx.dll添加到项目引用。
3. 通过NuGet安装Lib.Harmony。
4. 删除默认的Class1.cs，新建一个类，例如MyAwesomePlugin.cs。

2.3 BepInEx运行环境部署

开发插件前，你需要在游戏本体上搭建BepInEx的运行环境，用于测试。

1. 从BepInEx的GitHub Releases页面下载与游戏架构（x86或x64）匹配的预编译包。
2. 将压缩包内的所有文件解压到游戏的根目录（即Game.exe所在的文件夹）。
3. 首次运行游戏，BepInEx会自动生成所需的文件夹结构（BepInEx/plugins,BepInEx/config,BepInEx/patchers等）。
4. 运行后关闭游戏，检查BepInEx/LogOutput.log文件，确认没有红色错误信息，即表示环境部署成功。

3. 第一个BepInEx插件：从“Hello World”到理解生命周期

让我们从一个最简单的插件开始，它将在游戏启动时向日志文件和控制台输出一条信息。

3.1 插件类的基本结构

在你的MyAwesomePlugin.cs中，写入以下代码：

using BepInEx; using BepInEx.Logging; using UnityEngine; namespace MyFirstPlugin { // 关键特性：告诉BepInEx这是一个插件 [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class MyAwesomePlugin : BaseUnityPlugin { // 定义插件的元数据 public const string PluginGUID = "com.yourname.game.mods.myfirstplugin"; public const string PluginName = "我的第一个插件"; public const string PluginVersion = "1.0.0.0"; // 内部日志记录器 internal static ManualLogSource Log; // Awake方法：插件加载时最先执行，适合进行初始化 private void Awake() { // 将基类的Logger赋值给我们的静态Log变量，方便其他类调用 Log = Logger; // 记录一条日志信息 Log.LogInfo($"插件 {PluginName} v{PluginVersion} 已加载！"); // 尝试在游戏UI中创建调试文本（需要游戏有UI环境） // GameObject debugText = new GameObject("MyDebugText"); // debugText.AddComponent<GUIText>().text = "插件已加载！"; // DontDestroyOnLoad(debugText); } // Update方法：每帧调用，可用于实现持续性的逻辑（谨慎使用，性能敏感） // private void Update() // { // // 例如：每5秒打印一次时间 // if (Time.time % 5f < Time.deltaTime) // { // Log.LogInfo($"游戏运行时间：{Time.time}秒"); // } // } } }

代码解析与核心概念：

1. [BepInPlugin]特性：这是插件的“身份证”。PluginGUID必须是全局唯一的，通常使用逆域名格式。PluginName和PluginVersion会显示在BepInEx的插件管理界面中。
2. 继承BaseUnityPlugin：这是BepInEx插件类的基类。它提供了Logger属性（用于记录日志）和Unity MonoBehaviour的生命周期方法（如Awake,Start,Update,OnDestroy）。
3. Awake()vsStart()：在Unity中，Awake在脚本实例被创建时立即调用，Start则在第一帧更新之前调用。在BepInEx插件中，Awake是进行插件初始化（如读取配置、注册Harmony补丁）的标准位置。Start可能在某些游戏对象尚未完全初始化时被调用，因此更推荐使用Awake。
4. 日志记录：Log.LogInfo()是输出信息性日志的标准方式。还有LogDebug,LogWarning,LogError等方法。所有日志都会写入BepInEx/LogOutput.log，部分游戏也可能在屏幕上显示。

3.2 编译、部署与调试

1. 编译：在Visual Studio中，选择“Release”配置（调试完成后），右键项目点击“生成”。生成的DLL文件位于项目目录的bin/Release/下。
2. 部署：将生成的MyFirstPlugin.dll（名称取决于你的程序集名称）复制到游戏的BepInEx/plugins/文件夹下。你可以直接放在这里，也可以创建一个子文件夹（如BepInEx/plugins/MyFirstPlugin/）来保持整洁。
3. 运行与验证：启动游戏。如果一切正常，你将在游戏启动后，在BepInEx/LogOutput.log文件中看到一行类似[Info :MyAwesomePlugin] 插件 我的第一个插件 v1.0.0.0 已加载！的信息。
4. 调试（高级）：若要使用Visual Studio进行断点调试，需要将项目配置改为“Debug”，并在项目属性->调试中，设置“启动外部程序”为游戏的exe文件。同时，你需要确保游戏启动时加载的是Debug版本的DLL。这通常需要配合BepInEx的Doorstop配置或使用dnSpy等.NET调试器，过程较为复杂，初期建议通过大量使用Log.LogInfo进行“打印调试”。

4. 深入核心：使用HarmonyX进行代码劫持与修改

仅仅输出日志远远不够。模组的强大之处在于能改变游戏原有的行为。这就是Harmony库的用武之地——它允许你在运行时修改（Patch）其他类的方法。

4.1 Harmony补丁原理与类型

Harmony通过IL（中间语言）注入来实现补丁。你可以把它想象成在游戏原有的方法代码中插入几个“钩子点”。主要有三种补丁类型：

• 前缀补丁（Prefix）：在原方法执行之前运行。你可以访问方法的参数，甚至可以修改它们，或者通过返回false来完全阻止原方法的执行。
• 后缀补丁（Postfix）：在原方法执行之后运行。你可以访问方法的参数、返回值（__result）以及实例（__instance）。
• 变址补丁（Transpiler）：这是最强大也是最复杂的补丁。它直接操作方法的IL代码指令流，可以插入、删除或修改具体的指令。通常用于实现前缀和后缀无法完成的复杂修改。

4.2 实战：修改玩家金币数量

假设一个游戏，玩家获得金币的方法叫做Player.AddGold(int amount)。我们想实现一个功能：所有获得的金币数量翻倍。

首先，你需要使用类似dnSpy或ILSpy这样的反编译工具，打开游戏的Assembly-CSharp.dll，找到Player类和AddGold方法，确认其完整的签名（包括命名空间、参数类型等）。

然后，在你的插件项目中创建补丁类：

using HarmonyLib; using BepInEx; namespace MyFirstPlugin { // 使用HarmonyPatch特性声明要修补的类和方法 [HarmonyPatch(typeof(Player), nameof(Player.AddGold))] public class Patch_DoubleGold { // 这是一个前缀补丁，静态方法，返回类型为bool（表示是否继续执行原方法） [HarmonyPrefix] static bool Prefix(ref int amount) { // 修改传入的amount参数，使其翻倍 amount *= 2; // 记录日志以便调试 MyAwesomePlugin.Log?.LogInfo($"金币获取翻倍生效！原始值已被修改为：{amount}"); // 返回true，表示继续执行原方法（此时amount已经是翻倍后的值） return true; } } }

接下来，你需要在主插件类的Awake方法中创建Harmony实例并应用所有补丁：

private void Awake() { Log = Logger; Log.LogInfo($"插件 {PluginName} v{PluginVersion} 已加载！"); // 创建Harmony实例，参数是你的PluginGUID var harmony = new Harmony(PluginGUID); try { // 应用所有标记了[HarmonyPatch]的补丁 harmony.PatchAll(); Log.LogInfo("Harmony补丁应用成功！"); } catch (System.Exception ex) { Log.LogError($"应用Harmony补丁时出错：{ex}"); } }

实操要点与避坑指南：

1. 方法签名必须精确匹配：[HarmonyPatch]中的类型名和方法名必须与游戏程序集中的完全一致，包括命名空间。nameof操作符可以避免拼写错误。
2. 参数传递：前缀补丁的参数需要使用ref关键字才能修改传入值。后缀补丁中，使用ref int __result来访问和修改返回值。
3. 访问实例成员：如果原方法不是静态方法，你可以在补丁方法中使用Player __instance参数来访问调用该方法的对象实例。
4. 补丁顺序：如果有多个补丁作用于同一个方法，它们的执行顺序可能不确定。Harmony提供了[HarmonyPriority]特性来设定优先级。
5. 异常处理：务必用try-catch包裹harmony.PatchAll()，因为补丁应用失败会导致插件加载失败，但详细的错误信息能帮你快速定位问题。

5. 配置管理、UI交互与数据持久化

一个成熟的模组应该允许用户自定义配置，并能与游戏UI进行适当的交互。

5.1 使用BepInEx.Configuration进行配置管理

BepInEx内置了一个简单易用的配置系统。我们为上面的“金币翻倍”功能添加一个开关。

在主插件类中修改：

using BepInEx.Configuration; namespace MyFirstPlugin { [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class MyAwesomePlugin : BaseUnityPlugin { public const string PluginGUID = "com.yourname.game.mods.myfirstplugin"; public const string PluginName = "我的第一个插件"; public const string PluginVersion = "1.0.0.0"; internal static ManualLogSource Log; // 声明一个静态的配置项引用 internal static ConfigEntry<bool> ConfigDoubleGoldEnabled; private void Awake() { Log = Logger; Log.LogInfo($"插件 {PluginName} v{PluginVersion} 已加载！"); // 1. 创建配置项 // 参数：配置小节、配置项键名、默认值、配置描述 ConfigDoubleGoldEnabled = Config.Bind( "功能开关", // 小节名 "启用金币翻倍", // 键名 true, // 默认值 "是否启用获得金币时数量翻倍的功能。" // 描述 ); Log.LogInfo($"金币翻倍功能初始状态：{ConfigDoubleGoldEnabled.Value}"); var harmony = new Harmony(PluginGUID); harmony.PatchAll(); } } }

然后修改我们的补丁类，使其读取配置：

[HarmonyPatch(typeof(Player), nameof(Player.AddGold))] public class Patch_DoubleGold { [HarmonyPrefix] static bool Prefix(ref int amount) { // 检查配置，如果未启用则直接执行原方法 if (!MyAwesomePlugin.ConfigDoubleGoldEnabled.Value) return true; amount *= 2; MyAwesomePlugin.Log?.LogInfo($"金币获取翻倍生效！修改后值：{amount}"); return true; } }

用户运行游戏后，会在BepInEx/config/目录下生成一个以你PluginGUID命名的.cfg文件（如com.yourname.game.mods.myfirstplugin.cfg），用户可以用文本编辑器直接修改。下次启动插件时，就会读取新的配置值。

5.2 与游戏UI的简单交互（以Unity GUI为例）

在游戏内显示一个简单的调试窗口是常见的需求。我们可以利用Unity的即时模式GUI（IMGUI）。

在主插件类中添加：

using UnityEngine; public class MyAwesomePlugin : BaseUnityPlugin { // ... 其他代码 ... private bool _showDebugWindow = false; private Rect _debugWindowRect = new Rect(20, 20, 300, 200); private void Update() { // 例如，按F1键切换调试窗口显示 if (Input.GetKeyDown(KeyCode.F1)) { _showDebugWindow = !_showDebugWindow; } } private void OnGUI() { if (!_showDebugWindow) return; // 创建一个可拖拽的窗口 _debugWindowRect = GUI.Window( 0, // 窗口ID _debugWindowRect, // 位置和大小 DrawDebugWindow, // 绘制窗口内容的委托 "我的插件调试窗口" // 窗口标题 ); } private void DrawDebugWindow(int windowId) { GUILayout.Label($"插件状态：已加载"); GUILayout.Label($"金币翻倍功能：{ConfigDoubleGoldEnabled.Value}"); // 提供一个按钮来实时切换功能 if (GUILayout.Button("切换金币翻倍")) { ConfigDoubleGoldEnabled.Value = !ConfigDoubleGoldEnabled.Value; Log.LogInfo($"金币翻倍已{(ConfigDoubleGoldEnabled.Value ? "启用" : "禁用")}"); } // 使窗口可拖拽 GUI.DragWindow(new Rect(0, 0, _debugWindowRect.width, 20)); } }

注意：OnGUI方法每帧会调用多次，性能开销较大。仅用于调试或简单的信息展示。对于复杂的UI，社区有更成熟的方案，如BepInEx.ConfigurationManager（提供一个统一的图形化配置界面）或Unity UI（uGUI）方案，但后者实现起来复杂得多。

6. 高级主题与性能优化

当你的插件功能越来越复杂时，就需要考虑代码结构、性能和兼容性。

6.1 插件架构与模块化设计

不要把所有代码都塞进一个巨大的MyAwesomePlugin.cs文件里。合理的组织方式如下：

MyAwesomeMod/ ├── MyAwesomeMod.csproj ├── Properties/ ├── PluginCore/ │ ├── MyAwesomePlugin.cs (主入口，负责初始化、配置、Harmony加载) │ └── ConfigManager.cs (集中管理所有配置项) ├── Patches/ │ ├── PlayerPatches.cs (所有与Player相关的Harmony补丁) │ ├── UIPatches.cs │ └── EnemyPatches.cs ├── Systems/ │ ├── EconomySystem.cs (处理金币、经济相关的逻辑) │ └── UISystem.cs (管理自定义UI) ├── Utilities/ │ └── ExtensionMethods.cs (扩展方法、工具函数) └── lib/ (存放引用的外部DLL，如BepInEx.dll，HarmonyX.dll)

使用internal访问修饰符来控制类之间的可见性，并通过主插件类的静态实例或服务定位器模式来传递必要的引用（如Logger、Config）。

6.2 性能考量与优化技巧

1. 慎用Update和OnGUI：这是性能杀手。如果需要在每帧检查条件，考虑使用协程（IEnumerator）配合WaitForSeconds或WaitUntil来降低检查频率。

   private IEnumerator CheckConditionCoroutine() { while (true) { // 你的检查逻辑 if (SomeCondition) { DoSomething(); } // 每0.5秒检查一次，而不是每帧 yield return new WaitForSeconds(0.5f); } } // 在Awake或Start中启动协程：StartCoroutine(CheckConditionCoroutine());

2. 缓存引用：避免在频繁调用的方法（如补丁方法、Update）中使用GameObject.Find、GetComponent等开销较大的操作。在Awake或Start中获取并缓存引用。
3. Harmony补丁的粒度：尽量让补丁方法轻量。复杂的逻辑应该调用外部方法。避免在补丁方法中进行复杂的计算或对象分配。
4. 日志级别控制：在开发阶段使用Log.LogDebug输出大量信息，发布时可以通过BepInEx的日志等级配置（BepInEx.cfg）来关闭Debug日志，减少IO开销。

6.3 处理游戏更新与兼容性

游戏更新是模组开发者的噩梦。为了最大程度减少影响：

1. 使用模糊匹配和特性补丁：Harmony支持通过方法名、参数类型等特征进行补丁，即使方法签名稍有变化也可能匹配上。但这有风险，可能导致错误的补丁。
2. 版本检测与条件加载：在插件的Awake方法开始时，读取游戏程序集的版本号，并与插件支持的版本进行比对。如果不匹配，可以禁用部分功能或直接提示用户。

   private void Awake() { string gameVersion = Application.version; // 或从Assembly-CSharp.dll读取 Log.LogInfo($"检测到游戏版本：{gameVersion}"); if (gameVersion != "1.0.0") { Log.LogWarning($"此插件针对游戏版本1.0.0开发，当前版本{gameVersion}可能不兼容。"); // 可以选择不应用Harmony补丁，或只启用安全的功能 } else { // 正常初始化 } }

3. 社区协作：关注游戏的模组社区（如Discord、GitHub）。其他开发者可能已经找到了应对更新的方法，或者可以共同维护一个补丁库。

7. 测试、发布与社区维护

7.1 系统化测试流程

1. 单元测试（可选但推荐）：为你的核心逻辑（非Unity依赖部分）创建独立的测试项目。使用NUnit或MSTest框架。
2. 集成测试：在目标游戏环境中进行手动测试。制定检查清单：
   • [ ] 插件是否能正常加载和初始化？
   • [ ] 所有配置项是否能正确生成和读取？
   • [ ] 每个Harmony补丁是否按预期工作？（测试开启/关闭状态）
   • [ ] 与其他流行模组同时加载是否有冲突？
   • [ ] 游戏存档/读档后，插件状态是否保持正确？
   • [ ] 长时间运行游戏，是否有内存泄漏或性能下降？
3. 崩溃报告收集：鼓励用户在出现问题时提供BepInEx/LogOutput.log文件。你可以在插件初始化时捕获未处理异常，并记录更详细的信息到单独的文件。

7.2 打包与发布规范

一个专业的模组发布包应该清晰、易用。

推荐的文件结构：

MyAwesomeMod-v1.0.0.zip ├── README.md (说明文档，包含功能、安装、配置、常见问题) ├── CHANGELOG.md (版本更新日志) ├── icon.png (插件的图标，可选) └── BepInEx/ └── plugins/ └── MyAwesomeMod/ ├── MyAwesomeMod.dll (主插件文件) ├── MyAwesomeMod.cfg (默认配置文件，可选) └── manifest.json (如果发布到Thunderstore等模组平台需要)

manifest.json示例（用于Thunderstore）：

{ "name": "MyAwesomeMod", "version_number": "1.0.0", "website_url": "https://github.com/yourname/MyAwesomeMod", "description": "一个让游戏变得更有趣的模组！", "dependencies": [ "BepInEx-BepInExPack-5.4.2100" ] }

7.3 社区维护与版本迭代

1. 选择托管平台：GitHub或GitLab用于代码托管和版本控制。Thunderstore、Nexus Mods或游戏特定的模组网站用于发布。
2. 清晰的文档：README.md应包含详细的安装教程、配置说明、功能列表和故障排除指南。使用截图和GIF动图能极大提升用户体验。
3. 建立反馈渠道：在GitHub上开启Issues，或建立Discord频道，积极回应用户的问题和功能请求。
4. 版本管理：遵循语义化版本控制（SemVer）。主版本号.次版本号.修订号。重大不兼容更新升主版本，向下兼容的功能更新升次版本，问题修复升修订号。在CHANGELOG中详细记录每次更新的内容。

开发BepInEx插件是一场深入游戏内部的探险，从最初看到日志输出的兴奋，到成功修改游戏规则的成就感，再到处理复杂兼容性问题的挑战，每一步都充满了学习的乐趣。最关键的技巧永远是：从小功能开始，频繁测试，仔细阅读日志，并善用反编译工具和社区资源。当你成功发布第一个被其他玩家使用的模组时，你会发现这一切的努力都是值得的。