1. 项目概述为什么你需要BepInEx如果你是一个Unity游戏的玩家尤其是那些支持创意工坊的PC单机游戏你肯定见过“Mod”这个词。Mod即游戏模组它能让《上古卷轴5》的风景变得如诗如画能让《星露谷物语》的农场生活增添无数便利甚至能彻底改变一个游戏的玩法。但你是否好奇过这些Mod是如何被“安装”到游戏里并让游戏乖乖听话执行新代码的这背后就需要一个桥梁一个框架。对于基于Unity引擎开发的游戏来说BepInEx就是这个领域里最流行、最强大的“桥梁”之一。简单来说BepInEx是一个Unity游戏的插件/Mod加载框架。它的核心工作是在游戏启动时将自己“注入”到游戏进程中为后续所有Mod提供一个稳定、统一的运行环境。你可以把它想象成游戏的一个“扩展坞”所有第三方插件Mod都通过这个扩展坞与游戏本体安全、有序地进行通信和交互。没有它大多数复杂的Mod将无法运行或者会引发各种难以预料的崩溃。那么为什么是“5分钟快速上手”因为BepInEx的设计哲学之一就是开箱即用和对Mod开发者友好。对于玩家而言安装BepInEx通常只是把几个文件复制到游戏目录对于有志于尝试Mod开发的初学者它提供了一套清晰的模板和API大大降低了为Unity游戏制作Mod的门槛。无论你是想为自己喜欢的游戏安装Mod还是想亲手创造一些有趣的功能从理解BepInEx开始都是最直接、最有效的路径。接下来我将带你绕过复杂的底层原理直击核心使用和入门开发让你在短时间内掌握这个强大工具的基本用法。2. BepInEx核心机制与工作流程拆解要用好一个工具最好先明白它是怎么工作的。BepInEx虽然对使用者隐藏了大部分复杂性但了解其基本流程能帮助你在遇到问题时更快地定位原因。2.1 核心组件与启动流程BepInEx不是一个单一的程序而是一个由多个组件协同工作的套件。当你把BepInEx的文件放入游戏根目录后下一次启动游戏时一个精妙的“劫持”过程就开始了。引导程序Bootstrap这是最先执行的部分。通常是一个名为winhttp.dllWindows或lib开头的文件Linux/macOS。游戏启动时操作系统会加载这个库它将控制权转交给BepInEx的核心。核心加载器Core CLRBepInEx的核心是用.NET编写的。引导程序会准备一个.NET运行时环境并加载BepInEx的核心库如BepInEx.Core.dll。这一步是关键它使得BepInEx能够在一个受控的、独立于游戏原始代码的环境里运行。插件扫描与加载核心启动后它会扫描游戏目录下的BepInEx/plugins文件夹。每一个子文件夹或.dll文件都可能是一个插件Mod。BepInEx会加载这些DLL查找其中继承了特定基类如BaseUnityPlugin的类并实例化它们。Harmony补丁集成绝大多数BepInEx插件依赖一个名为Harmony的库来实现对游戏代码的修改。Harmony允许开发者在游戏原有的方法执行前、后或完全替换其逻辑而无需拥有游戏的源代码。BepInEx在启动时会初始化Harmony为所有插件的代码注入做好准备。插件初始化每个被发现的插件类都会调用其Awake()、Start()等方法类似于Unity MonoBehaviour的生命周期在这里插件开发者可以执行自己的初始化逻辑例如注册Harmony补丁、加载配置、创建游戏内UI等。这个过程结束后游戏才真正开始它的主循环。而此时所有插件都已经就位在幕后开始工作了。整个流程对玩家是无感的你只会发现游戏启动时命令行窗口可能一闪而过如果保留了控制台窗口然后游戏照常运行但Mod功能已经生效。2.2 插件Mod的基本结构一个最简单的BepInEx插件本质上就是一个.NET类库.dll。它通常包含以下要素GUID插件的全球唯一标识符格式通常类似com.author名.plugin名。这是区分不同插件的关键绝对不允许重复。插件元数据通过[BepInPlugin]特性Attribute标注在插件主类上包含GUID、插件名称和版本号。插件主类继承自BaseUnityPlugin的类。这是插件的入口点。Harmony补丁类包含用[HarmonyPatch]特性标注的静态方法用于定义要修改的游戏代码位置和修改逻辑。配置文件通过Config.Bind生成的配置项会自动在BepInEx/config目录下生成.cfg文件允许玩家自定义设置。理解这个结构你就明白了为什么把Mod的DLL文件扔进plugins文件夹就能生效——BepInEx的扫描和加载机制自动完成了所有繁重的工作。注意BepInEx 5.x版本是其目前最主流且长期维护的版本它与旧版如3.x、4.x在架构和API上有较大不同。本文所有内容均基于BepInEx 5.x。在为游戏安装BepInEx时务必确认下载的是适用于该游戏和对应Unity版本的BepInEx版本否则可能导致无法启动。3. 玩家视角5分钟安装与使用指南对于绝大多数玩家来说我们不需要开发只需要享受Mod带来的乐趣。以下是为你准备的极简安装与使用流程。3.1 第一步确认游戏与准备确认游戏支持首先你的游戏必须是基于Unity引擎开发的单机游戏并且其Mod社区普遍使用BepInEx。常见的例子有《雨中冒险2》、《英灵神殿》、《幸福工厂》、《戴森球计划》等。你可以通过游戏社区、Nexus Mods等网站确认。寻找合适的BepInEx包不要盲目去BepInEx的GitHub主页下载最新版。最稳妥的方法是去该游戏的Mod社区如Nexus Mods的对应游戏板块或中文Mod站寻找玩家们为该特定游戏打包好的BepInEx版本。这些版本通常已经配置好了必要的参数解压即用。备份游戏存档这是一个好习惯。虽然BepInEx本身非常稳定但Mod可能存在冲突。备份你的存档文件夹通常位于C:\Users\[你的用户名]\AppData\LocalLow\[游戏公司名]\[游戏名]或游戏目录下的save文件夹以防万一。3.2 第二步安装BepInEx框架假设你已经下载了一个为《游戏X》准备好的BepInEx压缩包。定位游戏根目录在Steam库中右键游戏 - “管理” - “浏览本地文件”。这就是你的游戏根目录里面应该能看到Game.exe、UnityPlayer.dll等文件。解压覆盖将下载的BepInEx压缩包里的所有文件和文件夹直接解压到游戏根目录。当系统询问是否覆盖或合并文件夹时选择“是”。首次运行关闭所有游戏启动器如Steam直接双击游戏根目录下的Game.exe或者通过Steam正常启动。游戏可能会弹出一个黑色的控制台窗口并显示BepInEx的加载日志。等待游戏完全启动到主菜单然后正常关闭游戏。验证安装再次打开游戏根目录你应该能看到一个新生成的BepInEx文件夹。其内部结构通常如下BepInEx/ ├── core/ # BepInEx核心库 ├── plugins/ # 【重要】这是放置Mod的地方 ├── patchers/ # 高级补丁较少用 ├── config/ # 【重要】Mod的配置文件会在这里生成 └── LogOutput.log # 运行日志出问题时查看它看到这个文件夹恭喜你BepInEx框架安装成功3.3 第三步安装与管理Mod安装Mod比安装框架更简单。获取Mod文件从可靠的Mod发布站下载你想要的Mod。Mod通常以压缩包形式提供。安装Mod将压缩包内的内容通常是一个或多个.dll文件有时附带manifest.json或配置文件解压到BepInEx/plugins文件夹下。注意有些Mod要求直接放DLL有些要求放在以作者名或Mod名命名的子文件夹里。请务必阅读Mod发布页面的安装说明。运行与配置启动游戏Mod应该会自动生效。许多Mod会在游戏内生成一个配置界面通常按F1或F10呼出或者它们的配置会自动保存在BepInEx/config目录下你可以用记事本编辑这些.cfg文件来调整Mod设置。故障排查如果游戏崩溃或Mod不生效首先检查BepInEx/LogOutput.log文件。这个日志文件会详细记录加载了哪些插件、哪些失败了以及错误原因。根据错误信息去Mod页面或社区寻找解决方案通常你遇到的问题别人早就遇到过了。实操心得管理大量Mod时建议在plugins文件夹内为每个Mod创建独立的子文件夹。这样结构清晰卸载时直接删除整个文件夹即可避免文件混杂。一些社区工具如r2modmanThunderstore或VortexNexus Mods提供了更图形化的Mod管理功能支持一键安装、更新和依赖解决对于Mod较多的游戏非常推荐使用。4. 开发者视角创建你的第一个BepInEx插件现在让我们换个身份从玩家变为创造者。假设你想为你最喜欢的游戏添加一个显示实时FPS的小功能。我们将通过这个简单例子走一遍插件开发的基本流程。4.1 开发环境准备安装.NET SDKBepInEx 5.x 基于.NET Framework 4.7.2 或 .NET Standard 2.0。你需要安装 .NET 6.0 SDK 或更高版本它兼容开发旧框架的项目。安装后在命令行输入dotnet --version确认安装成功。安装IDE推荐使用Visual Studio 2022社区版免费或JetBrains Rider。它们对C#和.NET开发的支持最完善。准备游戏引用要修改游戏你需要知道游戏里有哪些类和方法。这就需要游戏的Assembly-CSharp.dll文件。它通常位于游戏根目录的[游戏名]_Data/Managed文件夹下。将这个DLL文件复制到一个安全的地方我们稍后会引用它。获取BepInEx开发包从 BepInEx GitHub Releases 页面下载BepInEx_win_x64_5.x.x.zip或其他对应版本。我们需要的核心开发库在解压后的BepInEx/core文件夹里主要是BepInEx.Core.dll、BepInEx.Harmony.dll、0Harmony.dll等。4.2 创建插件项目打开Visual Studio新建一个“类库(.NET Framework)”项目命名为MyFirstFPSPlugin目标框架选择.NET Framework 4.7.2。在解决方案资源管理器中右键“引用” - “添加引用”。浏览并添加游戏目录下的Assembly-CSharp.dll。浏览并添加你从BepInEx包中复制的BepInEx.Core.dll、BepInEx.Harmony.dll和0Harmony.dll。右键项目 - “属性” - “生成”选项卡确保“输出路径”指向一个方便的位置比如bin\Debug\。4.3 编写插件代码现在我们来编写一个在屏幕左上角显示FPS的插件。首先安装必要的NuGet包在VS中右键项目 - “管理NuGet程序包”HarmonyX这是Harmony库的一个活跃分支与BepInEx兼容。搜索并安装它。然后创建你的主插件类FPSPlugin.csusing BepInEx; using BepInEx.Logging; using HarmonyLib; using UnityEngine; // 1. 定义插件元数据 [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class FPSPlugin : BaseUnityPlugin { public const string PluginGUID com.yourname.fpsdisplay; public const string PluginName FPS Display; public const string PluginVersion 1.0.0; internal static ManualLogSource Log; // 用于日志输出 private static GameObject _fpsCounterObject; private static float _deltaTime 0.0f; // 2. 插件启动时的初始化 private void Awake() { Log Logger; // 初始化日志 Log.LogInfo($插件 {PluginName} 正在加载...); // 应用Harmony补丁 Harmony.CreateAndPatchAll(typeof(FPSPlugin)); // 创建一个GameObject来承载我们的更新逻辑 _fpsCounterObject new GameObject(FPSDisplay_Object); DontDestroyOnLoad(_fpsCounterObject); // 防止场景切换时被销毁 _fpsCounterObject.AddComponentFPSDisplay(); // 添加显示组件 Log.LogInfo($插件 {PluginName} 加载完成); } // 3. 用于显示FPS的MonoBehaviour组件 public class FPSDisplay : MonoBehaviour { private GUIStyle _style new GUIStyle(); void Start() { _style.fontSize 24; _style.normal.textColor Color.green; _style.fontStyle FontStyle.Bold; } void Update() { // 计算平滑的FPS _deltaTime (Time.unscaledDeltaTime - _deltaTime) * 0.1f; } void OnGUI() { // 只在屏幕上绘制FPS float fps 1.0f / _deltaTime; GUI.Label(new Rect(10, 10, 200, 50), $FPS: {fps:0.}, _style); } } }这个插件做了以下几件事通过[BepInPlugin]特性声明了自己。在Awake()方法中创建了一个不随场景销毁的GameObject。为该GameObject添加了一个自定义的FPSDisplay组件该组件在OnGUI中绘制FPS文字。4.4 编译与测试在Visual Studio中按F6生成项目。如果一切顺利会在bin\Debug\目录下生成MyFirstFPSPlugin.dll。将这个DLL文件复制到你已经安装好BepInEx框架的游戏目录下的BepInEx/plugins文件夹里。你可以创建一个MyFirstFPSPlugin子文件夹再把DLL放进去保持整洁。启动游戏。如果代码正确你应该能在屏幕左上角看到绿色的FPS数值。恭喜你已经成功创建并运行了你的第一个BepInEx插件。虽然功能简单但它包含了插件开发的所有核心要素元数据、初始化、创建游戏对象、访问Unity引擎API。注意事项在开发过程中频繁修改代码并复制DLL测试是常态。你可以通过一些工具如BepInEx.ConfigurationManager插件实现游戏内重载插件但最直接的方法还是重启游戏。务必养成查看BepInEx/LogOutput.log的习惯它是调试的“第一现场”。5. 深入核心Harmony补丁实战与游戏交互仅仅创建UI还不够Mod的魅力在于与游戏逻辑深度交互。这就需要用到Harmony进行代码修补。让我们为上面的FPS插件增加一个“开关”功能按F8键显示或隐藏FPS。5.1 理解Harmony补丁Harmony允许你在目标方法执行的前后插入你自己的代码或者完全替换它。有三种主要的补丁类型Prefix在目标方法之前执行。可以修改传入的参数甚至可以跳过原始方法的执行。Postfix在目标方法之后执行。可以读取或修改原始方法的返回值。Transpiler最强大也最复杂直接修改目标方法的IL代码中间语言。用于进行更底层的修改初学者慎用。我们将使用Postfix来监听游戏的更新循环以便检测按键。5.2 实现按键切换功能修改FPSPlugin.cs添加一个Harmony补丁类和一个静态变量来控制显示状态。using HarmonyLib; // ... 其他using语句 ... [HarmonyPatch] public class PatchGameUpdate { // 静态变量控制FPS显示开关 public static bool ShowFPS true; // 5.1 确定要修补的目标方法 // 假设我们想修补游戏主循环的Update方法。一个常见的目标是 UnityEngine.Application 或某个管理类的Update。 // 更实际的做法是修补游戏玩家控制器或UI管理器的Update。 // 这里我们假设游戏有一个 GameManager 类它有 Update 方法。 // 你需要使用 dnSpy 或 ILSpy 等反编译工具查看游戏的 Assembly-CSharp.dll找到合适的方法。 // 例如我们找到了一个名为 PlayerController 的类它有 Update 方法。 [HarmonyPostfix] [HarmonyPatch(typeof(PlayerController), nameof(PlayerController.Update))] static void Postfix_PlayerControllerUpdate(PlayerController __instance) { // 5.2 在游戏每帧更新后检查按键 // Harmony补丁方法可以是静态的第一个参数可以是目标类的实例如果原方法不是静态的 // 这里我们不需要__instance只是借用这个更新循环。 if (Input.GetKeyDown(KeyCode.F8)) { ShowFPS !ShowFPS; // 切换状态 FPSPlugin.Log.LogInfo($FPS显示已{(ShowFPS ? 开启 : 关闭)}); } } } // 修改之前的FPSDisplay类中的OnGUI方法 public class FPSDisplay : MonoBehaviour { // ... Start和Update方法保持不变 ... void OnGUI() { // 只有开关打开时才绘制 if (!PatchGameUpdate.ShowFPS) return; float fps 1.0f / _deltaTime; GUI.Label(new Rect(10, 10, 200, 50), $FPS: {fps:0.}, _style); } }关键点解析[HarmonyPatch(typeof(PlayerController), nameof(PlayerController.Update))]这行代码告诉Harmony我们要修补PlayerController类的Update实例方法。你需要根据实际游戏替换PlayerController为正确的类名。[HarmonyPostfix]声明这是一个后置补丁将在原Update方法执行后运行。Postfix_PlayerControllerUpdate(PlayerController __instance)补丁方法。参数__instance是Harmony提供的特殊参数代表调用该方法的PlayerController实例对象。双下划线前缀是Harmony的约定。我们在补丁方法中检测F8按键并修改静态变量ShowFPS。在OnGUI中根据ShowFPS的值决定是否绘制。5.3 使用反编译工具定位目标方法上面代码的关键在于找到正确的PlayerController.Update。99%的Mod开发时间都花在“找对目标”上。你需要使用反编译工具打开游戏的Assembly-CSharp.dll。推荐工具dnSpy或ILSpy。它们可以浏览游戏的所有类、方法、字段。搜索策略寻找明显的管理类如GameManager、Player、UIManager、InputManager。在这些类中寻找Update、LateUpdate、FixedUpdate、OnGUI这类Unity生命周期方法。查看方法的代码逻辑确认它是否每帧都在运行通常Update方法里会有一些每帧更新的逻辑。一个更取巧的办法是寻找游戏中已知功能对应的代码。例如如果你知道按“E”键互动可以搜索字符串“E”或KeyCode.E找到处理输入的方法再从那个类里找Update循环。找到正确的方法后将[HarmonyPatch]特性中的类名和方法名替换成你找到的即可。这个过程需要耐心和一些C#和Unity基础知识的积累。实操心得在编写Harmony补丁时尤其是Prefix如果要跳过原方法务必谨慎。不正确的跳过可能导致游戏逻辑断裂引发崩溃或存档损坏。始终先在Postfix中尝试读取数据理解游戏逻辑后再考虑修改。另外将Harmony补丁类与插件主类分开放在不同的文件中是保持代码清晰的好习惯。6. 进阶技巧与生态工具当你掌握了基础开发后以下工具和技巧能极大提升你的开发效率和Mod质量。6.1 配置系统让Mod可定制BepInEx内置了强大的配置系统。让我们为FPS插件添加颜色和位置配置。using BepInEx.Configuration; // ... 在FPSPlugin类中 ... private ConfigEntryColor _fpsColor; private ConfigEntryint _fpsPosX; private ConfigEntryint _fpsPosY; private void Awake() { Log Logger; // 创建配置项 _fpsColor Config.Bind(显示设置, // 配置章节 颜色, // 配置项键名 Color.green, // 默认值 FPS显示文字的颜色); // 描述 _fpsPosX Config.Bind(显示设置, 水平位置, 10, new ConfigDescription(FPS显示的X坐标, new AcceptableValueRangeint(0, Screen.width))); _fpsPosY Config.Bind(显示设置, 垂直位置, 10, new ConfigDescription(FPS显示的Y坐标, new AcceptableValueRangeint(0, Screen.height))); // ... 其余初始化代码 ... } // 修改FPSDisplay类 public class FPSDisplay : MonoBehaviour { private GUIStyle _style new GUIStyle(); void Start() { _style.fontSize 24; _style.fontStyle FontStyle.Bold; // 从配置读取颜色 _style.normal.textColor FPSPlugin.Instance._fpsColor.Value; } void OnGUI() { if (!PatchGameUpdate.ShowFPS) return; float fps 1.0f / _deltaTime; // 从配置读取位置 int posX FPSPlugin.Instance._fpsPosX.Value; int posY FPSPlugin.Instance._fpsPosY.Value; GUI.Label(new Rect(posX, posY, 200, 50), $FPS: {fps:0.}, _style); } } // 需要在FPSPlugin类中添加一个静态实例引用以便访问 public static FPSPlugin Instance { get; private set; } private void Awake() { Instance this; // ... 其他初始化 ... }编译并运行后在BepInEx/config目录下会生成com.yourname.fpsdisplay.cfg文件。玩家可以直接编辑这个文件或者使用下面提到的配置管理器来修改。6.2 必备的开发者插件在游戏内安装以下插件能让你开发和调试Mod事半功倍BepInEx.ConfigurationManager为所有BepInEx插件提供一个游戏内的图形化配置界面。按F1呼出可以实时修改配置并看到效果无需重启游戏。BepInEx Debug Console在游戏中开启一个类似Unity Editor的控制台可以执行命令、查看日志、甚至调用游戏内部方法需谨慎。对于调试复杂Mod非常有用。Unity Explorer或Runtime Unity Editor功能强大的游戏内调试器。可以查看场景层次结构、游戏对象组件、实时修改属性、甚至调用方法。是理解游戏运行时状态的终极工具。6.3 依赖管理与版本控制当你的Mod依赖其他Mod例如依赖一个通用的UI库时需要在插件元数据中声明。[BepInDependency(com.other.author.dependencymod, BepInDependency.DependencyFlags.HardDependency)] [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class FPSPlugin : BaseUnityPlugin { // ... }BepInDependency特性告诉BepInEx当前插件硬依赖于GUID为com.other.author.dependencymod的插件。如果依赖的插件缺失当前插件将不会加载。这保证了Mod运行环境的完整性。7. 常见问题与排查技巧实录即使按照指南操作你也难免会遇到问题。这里汇总了一些典型场景和解决思路。7.1 游戏启动崩溃或无反应症状点击游戏后无任何窗口弹出或弹出即崩溃。排查步骤检查日志第一时间查看BepInEx/LogOutput.log。如果日志文件是空的说明BepInEx连初始化都没完成。版本不匹配这是最常见原因。确认你下载的BepInEx版本是否与游戏使用的Unity版本兼容。较新的Unity游戏如使用Unity 2020可能需要BepInEx 5.4.x的特定版本或测试版。去游戏社区找别人验证过的版本。杀毒软件拦截某些杀毒软件会将BepInEx的引导DLL视为病毒误杀。尝试将游戏目录添加到杀毒软件的白名单。运行库缺失确保系统已安装必要的运行库如 .NET Desktop Runtime 和 VC Redistributable 。7.2 Mod不生效症状游戏能正常启动但预期的Mod功能没有出现。排查步骤检查日志查看LogOutput.log搜索你的插件GUID或名称。看是否有Loaded [你的插件名]的记录。如果没有说明插件未被加载。检查插件位置确认你的.dll文件是否放在了正确的BepInEx/plugins目录下或其中的子目录。文件路径不能有中文或特殊字符。检查依赖如果日志显示插件加载失败并提示缺少依赖请确保所有依赖的Mod都已正确安装。检查游戏版本Mod可能只针对特定的游戏版本。游戏更新后旧版Mod可能失效。等待Mod作者更新或寻找替代品。Mod冲突两个Mod修改了游戏的同一处代码可能导致其中一个或全部失效。尝试逐个禁用Mod来排查。7.3 开发时编译错误或游戏内报错症状Visual Studio中代码报红或者游戏日志中出现大量的红色错误信息指向你的插件。排查步骤引用错误确保项目正确引用了Assembly-CSharp.dll和所有必要的BepInEx、Harmony库。检查这些DLL的版本是否与游戏运行时使用的版本匹配。Harmony补丁目标错误这是开发中最常见的运行时错误。仔细检查[HarmonyPatch]中指定的类名、方法名、参数列表是否完全正确。使用反编译工具再次确认。注意方法是静态的还是实例的。空引用异常你的代码试图访问一个为null的游戏对象或组件。在访问前使用if (obj ! null)进行判断。使用调试工具如Unity Explorer在游戏运行时检查对象是否存在。查看完整堆栈跟踪LogOutput.log中的错误信息会包含详细的堆栈跟踪精确指出是哪一行代码出了问题。学会阅读堆栈跟踪是调试的基本功。7.4 性能问题症状安装Mod后游戏明显变卡。排查思路低效的OnGUIOnGUI方法每帧调用多次非常耗性能。避免在OnGUI中做复杂计算或创建大量GUI样式。对于需要持续更新的UI考虑使用Unity的uGUI或IMGUI的优化写法或者使用社区成熟的UI库如UnityEngine.UI的封装。频繁的Harmony补丁尤其是在Update方法上打的补丁里面的逻辑要尽可能轻量。避免在每帧补丁中进行查找对象 (GameObject.Find)、实例化等重型操作。内存泄漏确保你创建的游戏对象在不需要时被正确销毁Destroy特别是那些你通过new GameObject()创建并附加了自定义组件的对象。
