Unity游戏插件开发入门：基于BepInEx框架的运行时补丁与Harmony应用

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

如果你是一个Unity游戏的深度玩家，或者是一个对游戏机制有自己想法的开发者，你肯定不止一次想过：“要是这个游戏能加上XX功能就好了”。也许是给《星露谷物语》加个自动化农场，给《雨中冒险2》做个新角色，或者给《英灵神殿》整点更酷的建筑。但面对一个编译好的游戏客户端，传统上你只能望洋兴叹，觉得这是只有游戏公司内部开发者才能触及的领域。几年前，我也是这么想的，直到我遇到了BepInEx。

BepInEx不是一个普通的Unity插件框架，它更像是一把“万能钥匙”。它绕过了Unity游戏发布后的封闭性，让你能够安全、稳定地向游戏中注入自己编写的代码。与那些需要你反编译、重打包的“硬核”修改方式不同，BepInEx采用了一种非侵入式的运行时补丁（Runtime Patching）方案。简单来说，它就像是在游戏启动时，把自己“夹”在游戏引擎和游戏代码之间，让你有机会在游戏运行的关键节点插入自己的逻辑，而无需动游戏原始文件的一行代码。这种设计理念，使得插件开发的门槛大大降低，稳定性却显著提高。

为什么我强烈推荐从BepInEx入门Unity插件开发？首先，它的社区生态极其繁荣。从《我的世界》的Forge到《饥荒》的Mod，很多成功的模组社区背后都有一个强大的底层框架。BepInEx在Unity游戏圈就扮演了这个角色，大量的热门游戏模组都基于它开发，这意味着你有海量的学习资料、现成的插件范例和活跃的社区可以求助。其次，它对开发者非常友好。它提供了完整的日志系统、配置管理、插件生命周期管理，让你可以专注于功能实现，而不是重复造轮子去处理如何加载DLL、如何读取配置文件这些底层问题。最后，也是最重要的一点，它支持Unity的Mono和IL2CPP两种后端运行时。IL2CPP是Unity为了提升性能和安全性而推出的AOT（提前编译）方案，很多新游戏都采用了它，这让很多传统的基于Mono的注入工具失效。而BepInEx完美地解决了这个问题，让你的插件能面向更广泛的游戏。

所以，无论你是想为自己喜欢的游戏增添乐趣的玩家，还是想学习游戏逆向与修改技术的开发者，这篇指南都将带你从零开始，彻底掌握BepInEx，把你的创意变成游戏里实实在在的功能。

2. 环境搭建：从零部署你的第一个BepInEx工作环境

动手之前，我们先得把“厨房”准备好。BepInEx的环境搭建并不复杂，但有几个关键步骤和选择点，一旦弄错，可能会导致游戏无法启动或者插件不生效。我会带你走一遍最稳妥的流程，并解释每一步背后的原因。

2.1 核心工具获取与版本选择

首先，你需要获取BepInEx。最官方的来源是GitHub上的发布页。这里有个关键选择：BepInEx 5还是BepInEx 6？对于绝大多数Unity游戏，BepInEx 5 (BepInEx 5.4.x) 是目前最稳定、兼容性最广的版本，社区插件也主要基于此版本开发。BepInEx 6 是正在开发中的下一代版本，带来了性能改进和新特性，但可能对部分老游戏支持不佳。作为初学者，我强烈建议从BepInEx 5.4.21这个LTS（长期支持）版本开始。你可以在GitHub的Release页面找到以BepInEx_x64_5.4.21.0.zip命名的文件，下载这个通用版本。

注意：一定要根据你的游戏是32位（x86）还是64位（x64）来选择对应的版本。现在绝大多数游戏都是64位的，下载x64版本即可。如果不确定，可以查看游戏主程序（.exe）的属性。

除了框架本身，你还需要一个开发环境。由于BepInEx插件本质上是.NET类库（DLL），你需要：

1. .NET开发环境：安装.NET SDK（建议6.0或8.0 LTS版本）。BepInEx 5基于.NET Framework 4.7.2，但使用更新的.NET SDK进行开发完全兼容，且能获得更好的开发体验。
2. 代码编辑器：Visual Studio 2022是首选，社区版免费且功能强大。务必在安装时勾选“.NET桌面开发”和“使用Unity的游戏开发”工作负载。如果你偏爱轻量级，Visual Studio Code配合C#扩展也是不错的选择。
3. 目标游戏：准备一个你想为其开发插件的Unity游戏。建议先从一些Mod社区活跃、结构相对简单的游戏开始，比如《Hollow Knight》（空洞骑士）、《Risk of Rain 2》（雨中冒险2）的单机版本。

2.2 安装与配置的魔鬼细节

安装BepInEx不是简单解压。你需要将下载的ZIP包里的所有内容，解压到游戏的根目录。什么是根目录？就是包含游戏主程序（.exe文件）和GameName_Data文件夹的那个目录。

解压后，你会看到一堆文件和文件夹，其中最关键的是：

• winhttp.dll/doorstop_config.ini：这是注入器核心，负责在游戏启动时加载BepInEx。
• BepInEx文件夹：框架本体。

接下来是第一个容易踩坑的点：运行时配置。BepInEx需要知道游戏使用的是Mono还是IL2CPP。你可以在游戏根目录寻找线索：如果存在GameName_Data/Managed文件夹，里面有很多.dll文件，那通常是Mono。如果存在GameName_Data/il2cpp_data等文件夹，则是IL2CPP。更简单的方法是，直接打开doorstop_config.ini文件。

找到[Doorstop]部分，关键参数是：

enabled=true targetAssembly=BepInEx\core\BepInEx.Preloader.dll

对于绝大多数情况，保持默认即可。BepInEx会自动检测。但如果游戏启动失败，你可能需要根据游戏运行时调整targetAssembly：

• Mono：通常就是BepInEx\core\BepInEx.Preloader.dll。
• IL2CPP：有时需要指定为BepInEx\core\BepInEx.Unity.IL2CPP.dll（但BepInEx 5.4.x的通用包已能自动处理）。

配置完成后，启动游戏。如果安装成功，你会看到：

1. 游戏根目录下会生成完整的BepInEx文件夹结构（如果之前没有）。
2. 控制台窗口可能会弹出（如果BepInEx/config/BepInEx.cfg中的Logging.Console.Enabled为true）。
3. 在BepInEx/LogOutput.log文件中，会看到详细的启动日志，包含“Chainloader started”和“Chainloader finished”这样的成功信息。

实操心得：第一次安装后，务必先启动一次游戏并正常关闭，让BepInEx生成完整的目录和默认配置文件。这能避免很多因路径缺失导致的插件加载问题。如果游戏闪退，首先检查LogOutput.log文件的最后几行错误信息，这是排查问题的黄金标准。

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

环境搭好了，让我们立刻开始写代码。第一个插件我们不搞复杂的，就做一个在游戏加载时，在控制台和日志文件里打印“Hello BepInEx!”的插件。这个简单的过程会贯穿插件开发的所有核心概念。

3.1 创建插件项目与基础结构

打开Visual Studio，新建一个“类库(.NET Framework)”项目，命名为MyFirstPlugin。将目标框架设置为.NET Framework 4.7.2（为了与BepInEx 5运行时最佳兼容）。然后，通过NuGet包管理器，为项目添加对BepInEx.Core的引用。你需要添加NuGet源https://nuget.bepinex.dev/v3/index.json，然后搜索安装BepInEx.Core（版本号选择5.4.x）。

现在，创建一个主插件类，例如HelloWorldPlugin.cs：

using BepInEx; using BepInEx.Logging; using UnityEngine; namespace MyFirstPlugin { // 这是插件的元数据，必不可少 [BepInPlugin(PluginInfo.PLUGIN_GUID, PluginInfo.PLUGIN_NAME, PluginInfo.PLUGIN_VERSION)] public class HelloWorldPlugin : BaseUnityPlugin // 必须继承BaseUnityPlugin { // 内部日志记录器实例 internal static ManualLogSource Log; // Awake方法：插件加载时立即执行一次 private void Awake() { // 将类的日志源赋值给静态变量，方便其他类访问 Log = Logger; // 使用BepInEx提供的Logger记录日志 Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 正在加载！"); // 尝试在游戏内输出信息（需要游戏有UI控制台） // Debug.Log($"[{PluginInfo.PLUGIN_NAME}] Hello from Awake!"); // 插件加载成功的标志 Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 加载完成！"); } // Update方法：每一帧都执行（慎用，性能敏感） // private void Update() // { // // 这里不要写频繁执行的代码 // } } }

同时，创建一个PluginInfo.cs文件来集中管理元数据：

namespace MyFirstPlugin { public static class PluginInfo { public const string PLUGIN_GUID = "com.yourname.myfirstplugin"; public const string PLUGIN_NAME = "我的第一个BepInEx插件"; public const string PLUGIN_VERSION = "1.0.0"; } }

关键点解析：

• [BepInPlugin]属性：这是插件的“身份证”。PLUGIN_GUID必须是全局唯一的，通常使用“作者.插件名”的逆域名格式。BepInEx靠这个来识别和管理插件。
• BaseUnityPlugin基类：它提供了Logger属性（用于日志）、Config属性（用于配置）以及Unity MonoBehaviour的生命周期方法（如Awake,Start,Update,OnDestroy）。
• Awake()方法：这是插件入口点。当BepInEx加载你的插件DLL时，会实例化这个类并调用Awake。在这里进行一次性初始化操作，千万不要在这里启动长时间循环或加载大量资源。

3.2 编译、部署与调试

在Visual Studio中编译项目（生成 -> 生成解决方案），你会在项目的bin/Debug或bin/Release目录下找到MyFirstPlugin.dll。

将这个DLL文件复制到目标游戏的BepInEx/plugins目录下。如果plugins文件夹不存在，就手动创建一个。

启动游戏。如果一切正常，你应该能在BepInEx/LogOutput.log文件中看到类似这样的输出：

[Info : MyFirstPlugin] 插件 我的第一个BepInEx插件 正在加载！ [Info : MyFirstPlugin] 插件 我的第一个BepInEx插件 加载完成！

同时，如果游戏内置控制台（例如通过其他插件开启）或者你配置了BepInEx弹出控制台窗口，也能看到这些信息。

注意事项：插件DLL的文件名可以任意，但强烈建议保持与项目名或插件名一致，并且一个DLL只包含一个[BepInPlugin]主类。多个主类在一个DLL里可能会导致不可预知的行为。调试时，最可靠的方式就是查看LogOutput.log文件。

4. 深入核心：掌握Harmony进行游戏代码修补

打印日志只是第一步，真正的力量在于修改游戏原有的行为。BepInEx自身并不直接提供修改游戏代码的能力，它整合了一个强大的库——Harmony。Harmony允许你为游戏原有的方法打上“补丁”（Patch），可以在目标方法执行前、执行后甚至完全替换它。这是BepInEx插件实现功能的基石。

4.1 Harmony补丁原理与类型

想象一下游戏里有一个计算玩家伤害的方法CalculateDamage。你想实现一个“双倍伤害”的插件。不用找到源码去修改，Harmony让你可以：

1. 前缀补丁（Prefix）：在CalculateDamage执行之前运行你的代码。你可以修改传入的参数，或者直接返回结果来跳过原方法。
2. 后缀补丁（Postfix）：在CalculateDamage执行之后运行你的代码。你可以读取原方法的返回值并进行修改，或者执行一些后续操作。
3. 中转补丁（Transpiler）：这是高级功能，它允许你直接修改方法的IL代码（中间语言），实现更底层的操控。

我们需要通过NuGet为项目添加HarmonyX库（BepInEx 5 通常使用Lib.Harmony包，但HarmonyX是更新更活跃的分支，推荐使用）。

4.2 实战：修改玩家生命值

假设我们想实现一个“锁血”功能，让玩家的生命值永远不会低于1。我们首先需要知道游戏里管理玩家生命值的类和方法。这通常需要借助逆向工具（如dnSpy, ILSpy）去分析游戏的Assembly-CSharp.dll文件。假设我们找到了一个PlayerController类，里面有一个TakeDamage(int damage)方法。

首先，创建一个补丁类PlayerPatch.cs：

using HarmonyLib; using BepInEx.Logging; namespace MyFirstPlugin { [HarmonyPatch(typeof(PlayerController))] // 指定要修补的类 [HarmonyPatch(nameof(PlayerController.TakeDamage))] // 指定要修补的方法 internal static class PlayerPatch_TakeDamage { // 这是一个前缀补丁，在原方法执行前运行 static bool Prefix(PlayerController __instance, ref int damage) { // __instance 是对原方法所属对象（PlayerController实例）的引用 // damage 是传入的参数，通过ref关键字我们可以修改它 // 假设PlayerController有个Health属性 if (__instance.Health <= 1) { HelloWorldPlugin.Log.LogInfo($"玩家生命值已为1，阻止此次伤害！"); return false; // 返回false表示跳过原始方法的执行 } // 如果生命值大于1，允许原方法执行，但我们可以修改伤害值 // 例如，实现一个简单的减伤50%： // damage = Mathf.Max(1, damage / 2); HelloWorldPlugin.Log.LogInfo($"玩家将受到 {damage} 点伤害"); return true; // 返回true表示继续执行原方法 } // 这是一个后缀补丁，在原方法执行后运行 // static void Postfix(PlayerController __instance, int damage) // { // // 可以在这里检查执行后的状态，比如播放一个受击特效 // HelloWorldPlugin.Log.LogInfo($"玩家受到伤害后，当前生命值：{__instance.Health}"); // } } }

然后，我们需要在主插件类的Awake方法中应用这个补丁：

private void Awake() { Log = Logger; Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 正在加载！"); // 应用所有Harmony补丁 Harmony.CreateAndPatchAll(typeof(HelloWorldPlugin).Assembly, PluginInfo.PLUGIN_GUID); Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 加载完成！"); }

Harmony.CreateAndPatchAll会扫描当前程序集（你的插件DLL）中所有带有[HarmonyPatch]属性的类，并自动为它们创建补丁。

实操心得：使用Harmony时，最大的挑战是找到正确的类和方法签名。逆向工具是必备的。此外，前缀补丁如果返回false，必须确保你的逻辑能提供原方法应有的所有副作用和返回值，否则游戏可能崩溃或出现奇怪bug。对于像TakeDamage这样返回void的方法，跳过执行是相对安全的。对于有返回值的方法，你需要在前缀补丁中设置__result并返回false。

5. 插件配置：让用户自定义你的插件行为

一个好的插件应该是可配置的。你不可能为每个用户的需求都重写代码。BepInEx内置了一套完整的配置系统，让你可以轻松地创建和管理插件的设置文件。

5.1 创建与绑定配置项

BepInEx的配置基于BepInEx.Configuration命名空间。我们继续上面的例子，让“锁血”功能变成可选项，并且让用户能自定义最低生命值。

在主插件类HelloWorldPlugin中，添加配置字段和初始化代码：

using BepInEx.Configuration; namespace MyFirstPlugin { [BepInPlugin(PluginInfo.PLUGIN_GUID, PluginInfo.PLUGIN_NAME, PluginInfo.PLUGIN_VERSION)] public class HelloWorldPlugin : BaseUnityPlugin { internal static ManualLogSource Log; // 声明配置项 internal static ConfigEntry<bool> ConfigGodMode; internal static ConfigEntry<int> ConfigMinHealth; private void Awake() { Log = Logger; // 1. 绑定配置项 // 参数：配置分组（section），配置项键（key），默认值，配置描述 ConfigGodMode = Config.Bind("通用设置", // 分组名 "GodMode", // 键名 false, // 默认值：关闭 "是否开启无敌模式（锁血）"); // 描述 ConfigMinHealth = Config.Bind("通用设置", "MinHealth", 1, "无敌模式下的最低生命值（仅GodMode开启时生效）"); // 2. 应用补丁 Harmony.CreateAndPatchAll(typeof(HelloWorldPlugin).Assembly, PluginInfo.PLUGIN_GUID); Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 加载完成！"); Log.LogInfo($"当前配置 - 无敌模式: {ConfigGodMode.Value}, 最低生命: {ConfigMinHealth.Value}"); } } }

这样，插件加载时会在BepInEx/config目录下生成一个以插件GUID命名的配置文件，例如com.yourname.myfirstplugin.cfg。用户可以用文本编辑器打开它进行修改：

[通用设置] ## 是否开启无敌模式（锁血） # Setting type: Boolean GodMode = false ## 无敌模式下的最低生命值（仅GodMode开启时生效） # Setting type: Int32 MinHealth = 1

5.2 在代码中使用动态配置

现在，我们需要修改之前的Harmony补丁，让它响应配置：

static bool Prefix(PlayerController __instance, ref int damage) { // 检查配置：如果无敌模式关闭，则不做任何干预 if (!HelloWorldPlugin.ConfigGodMode.Value) { return true; } int minHealth = HelloWorldPlugin.ConfigMinHealth.Value; if (__instance.Health <= minHealth) { HelloWorldPlugin.Log.LogInfo($"玩家生命值已为{__instance.Health}（低于或等于设置的最低值{minHealth}），阻止此次伤害！"); return false; } // 如果当前生命值高于最低值，允许受伤，但可以确保不会低于最低值 // 这里我们可以在后缀补丁中处理，或者直接在这里计算 // 为了简单，我们只是记录日志，原方法会正常执行 HelloWorldPlugin.Log.LogInfo($"无敌模式开启，最低生命值设置为{minHealth}。玩家将受到 {damage} 点伤害"); return true; }

关键点：Config.Bind返回的ConfigEntry<T>对象，其Value属性会实时反映配置文件中的值。这意味着用户可以在游戏运行时修改配置文件，而插件在下一次读取配置时（通常是相关逻辑触发时）就能生效，无需重启游戏。这是一种“热重载”配置的简易实现。

注意事项：配置文件的读写是线程安全的，但频繁读写磁盘会影响性能。对于需要实时响应的配置（如快捷键），建议在插件启动时读取一次并缓存，同时监听配置文件变化事件Config.SettingChanged。对于不常变的设置，直接读取Value即可。

6. 资源管理与游戏交互：超越代码修改

插件不仅能修改逻辑，还能添加新的内容，比如加载自定义的贴图、模型、音效，或者在游戏界面上添加新的按钮。这涉及到Unity的资源管理和UI系统。

6.1 加载外部资源（AssetBundle）

游戏本身的资源都打包在AssetBundle里。我们也可以制作自己的AssetBundle，让插件加载。假设我们想为玩家添加一个自定义的宠物模型。

1. 准备资源：在Unity编辑器中创建一个新项目，制作你的宠物Prefab，然后通过AssetBundle Browser工具将它打包成.assets文件（例如mypet.assets）。
2. 将资源文件放入插件目录：在你的Visual Studio项目中，创建一个文件夹（如Assets），将mypet.assets文件放入，并设置其“生成操作”为“内容”，“复制到输出目录”为“始终复制”。这样编译时它会出现在DLL同级目录。
3. 在插件中加载：

using UnityEngine; private void Awake() { // ... 其他初始化代码 ... // 在游戏场景加载后初始化资源（例如在Start或一个延迟调用的协程中） // 这里为了示例，在Awake中简单演示路径获取 string pluginPath = Paths.PluginPath; // BepInEx提供的插件根目录路径 string assetBundlePath = Path.Combine(pluginPath, PluginInfo.PLUGIN_GUID, "mypet.assets"); Log.LogInfo($"资源包路径: {assetBundlePath}"); } // 在一个合适的时机（如玩家生成后）加载宠物 private void SpawnPet() { string assetBundlePath = Path.Combine(Paths.PluginPath, PluginInfo.PLUGIN_GUID, "mypet.assets"); if (File.Exists(assetBundlePath)) { AssetBundle petBundle = AssetBundle.LoadFromFile(assetBundlePath); GameObject petPrefab = petBundle.LoadAsset<GameObject>("MyPetPrefab"); if (petPrefab != null) { GameObject myPet = Instantiate(petPrefab, Player.instance.transform.position, Quaternion.identity); Log.LogInfo("自定义宠物加载成功！"); } else { Log.LogError("在资源包中未找到名为'MyPetPrefab'的资源！"); } petBundle.Unload(false); // 卸载AssetBundle，但保留已加载的资源 } else { Log.LogError($"资源包文件不存在: {assetBundlePath}"); } }

Paths.PluginPath是BepInEx提供的一个非常实用的属性，它指向BepInEx/plugins目录。将你的插件资源放在BepInEx/plugins/作者.插件名/的子目录下，是一个良好的组织习惯。

6.2 与游戏UI交互（以Unity GUI为例）

许多游戏使用Unity的即时模式GUI（IMGUI）或uGUI来绘制界面。我们可以利用Harmony补丁，在游戏的UI渲染循环中插入我们自己的绘制代码。

例如，我们想在游戏屏幕左上角显示一个自定义的HUD，展示插件状态。

using HarmonyLib; using UnityEngine; [HarmonyPatch(typeof(SomeGameUIClass))] // 需要找到游戏实际绘制UI的类 [HarmonyPatch("OnGUI")] // 修补OnGUI方法 internal static class Patch_GameUI_OnGUI { static void Postfix() { // 在游戏UI绘制之后，绘制我们自己的UI DrawPluginHUD(); } static void DrawPluginHUD() { // 定义一个简单的矩形区域 Rect hudRect = new Rect(10, 10, 200, 100); // 开始一个GUI窗口（或使用GUI.Box/Label） GUI.Box(hudRect, "我的插件HUD"); // 在框内显示信息 GUI.Label(new Rect(20, 40, 180, 20), $"无敌模式: {HelloWorldPlugin.ConfigGodMode.Value}"); GUI.Label(new Rect(20, 60, 180, 20), $"最低生命: {HelloWorldPlugin.ConfigMinHealth.Value}"); // 甚至可以添加一个按钮来开关功能 if (GUI.Button(new Rect(20, 80, 160, 20), "切换无敌模式")) { HelloWorldPlugin.ConfigGodMode.Value = !HelloWorldPlugin.ConfigGodMode.Value; HelloWorldPlugin.Log.LogInfo($"无敌模式切换为: {HelloWorldPlugin.ConfigGodMode.Value}"); } } }

关键挑战：找到正确的UI类和方法进行修补，需要逆向分析游戏代码。通常可以搜索OnGUI,Update,BeginGUI等方法名。使用HarmonyPatch时，如果方法有重载，需要指定参数类型来精确匹配。

实操心得：UI交互要特别注意性能。OnGUI每帧调用多次，里面的逻辑要尽可能轻量。避免在OnGUI中做复杂的计算或频繁查找游戏对象。对于复杂的UI，可以考虑使用游戏原有的UI系统（如果它暴露给插件）或者更高效的渲染方式。

7. 进阶技巧与最佳实践

当你掌握了基础，下面这些技巧能让你的插件更专业、更健壮。

7.1 依赖管理与插件间通信

你的插件可能需要依赖其他插件。BepInEx通过[BepInDependency]属性来处理。

[BepInPlugin(...)] [BepInDependency("com.other.author.theirplugin", BepInDependency.DependencyFlags.SoftDependency)] // 软依赖 public class MyPlugin : BaseUnityPlugin { private void Awake() { // 检查依赖插件是否加载 if (Chainloader.PluginInfos.ContainsKey("com.other.author.theirplugin")) { // 依赖存在，可以安全调用其功能 Log.LogInfo("找到依赖插件，启用高级功能。"); } else { // 依赖不存在，降级处理或提示用户 Log.LogWarning("未找到依赖插件XXX，部分功能不可用。"); } } }

DependencyFlags.SoftDependency表示软依赖，即使对方不存在你的插件也能加载。HardDependency则表示硬依赖，对方不存在你的插件将无法加载。

7.2 性能优化与内存管理

• 避免在Update中做繁重操作：Update每帧调用。如果需要定时检查，使用InvokeRepeating或协程StartCoroutine配合WaitForSeconds。
• 缓存引用：通过Harmony或GameObject.Find获取的游戏对象、组件引用，尽量在Awake或Start中获取并缓存，避免每帧查找。
• 及时销毁和卸载：自己实例化的GameObject，在插件卸载时（OnDestroy）要记得Destroy。加载的AssetBundle也要Unload。
• 使用对象池：对于需要频繁创建和销毁的对象（如子弹、特效），实现一个简单的对象池能极大提升性能。

7.3 调试与日志的艺术

BepInEx的日志系统是你的最佳伙伴。

• 分级日志：使用Log.LogDebug,Log.LogInfo,Log.LogWarning,Log.LogError来区分信息重要性。在开发时开启Debug级别，发布时改为Info或更高。
• 结构化日志：在日志中输出关键对象的状态、变量值，便于追踪问题。
• 使用Debug.Log与游戏内控制台结合：如果游戏有内嵌控制台（如通过Console Mod），Debug.Log的信息也会输出到那里，方便实时查看。
• 配置日志回滚：在BepInEx/config/BepInEx.cfg中配置Logging.Loggers.File.MaxLogFiles和Logging.Loggers.File.MaxLogSize，防止日志文件无限膨胀。

8. 发布、分享与问题排查

8.1 插件打包与发布

一个完整的插件发布包通常包括：

1. 核心DLL：你的插件编译文件。
2. 依赖DLL（如果有）：如你引用的第三方库（非BepInEx/Harmony核心库）。这些通常放在插件目录下即可。
3. 资源文件：如图像、声音、配置文件模板等，放在一个以你插件命名的子文件夹内。
4. README.md：说明文件，包含功能描述、安装方法、配置说明、常见问题。
5. manifest.json（如果发布到Thunderstore等Mod平台）：描述插件元数据、依赖、版本等。

标准的目录结构建议如下：

BepInEx/ └── plugins/ └── YourPluginGUID/ ├── YourPlugin.dll ├── YourPlugin.deps.json (如果有) ├── icon.png (可选) ├── config.cfg (默认配置，可选) └── assets/ (资源文件夹) └── ...

8.2 常见问题排查清单

当你或用户遇到问题时，按以下步骤排查：

问题现象	可能原因	解决方案
游戏启动崩溃，无日志	BepInEx版本与游戏不兼容；注入器配置错误。	1. 确认游戏是Mono还是IL2CPP，使用对应BepInEx版本或通用版。 2. 检查doorstop_config.ini，enabled=true，targetAssembly路径正确。 3. 尝试删除BepInEx文件夹（备份配置），让BepInEx重新生成。
游戏能启动，但插件没加载	插件DLL未放在正确位置；插件依赖缺失；插件代码有异常。	1. 确认DLL在BepInEx/plugins或其子目录。 2. 查看BepInEx/LogOutput.log，搜索你的插件GUID，看是否有加载错误。 3. 检查插件是否依赖其他未安装的库。
插件加载了，但功能不生效	Harmony补丁未正确应用；补丁目标方法签名错误；配置未读取。	1. 在日志中搜索Harmony关键字，看补丁是否成功创建。 2. 使用Harmony.DEBUG = true;在插件Awake中启用Harmony调试，查看更详细的补丁信息。 3. 确认配置项键名与代码中Config.Bind使用的完全一致。
游戏运行一段时间后崩溃	内存泄漏；补丁逻辑错误导致无限循环或状态异常。	1. 检查插件中是否有未销毁的GameObject或未卸载的AssetBundle。 2. 检查补丁逻辑，尤其是前缀补丁返回false时，是否妥善处理了所有情况。 3. 尝试逐个禁用插件，定位问题插件。
与其他插件冲突	多个插件修补了同一个方法，且逻辑冲突。	1. 查看日志，看是否有其他插件的补丁信息。 2. 调整补丁优先级（Harmony的[HarmonyPriority]属性）。 3. 联系另一个插件作者，协商兼容方案。

8.3 最后的建议

从“Hello World”到能够修改游戏逻辑、加载资源、创建交互，你已经走完了BepInEx插件开发的核心路径。记住，最强大的学习工具是游戏的Assembly-CSharp.dll和你的LogOutput.log文件。多拆解，多试验，多记录。从模仿优秀的开源插件开始，理解他们的架构和代码。Unity插件开发社区非常友好，遇到解决不了的问题，去相关的游戏Mod社区或GitHub Issues里搜索，你很可能找到答案。

开发插件最大的乐趣，在于将想法变为现实，并与社区分享。现在，你已经拥有了这把钥匙，去打开那扇门，创造属于你自己的游戏体验吧。