1. 项目概述为什么是BepInEx如果你在Unity游戏社区里混过一段时间尤其是那些支持Mod的PC游戏比如《星露谷物语》、《鬼谷八荒》、《幻兽帕鲁》或者《饥荒联机版》那你大概率听说过BepInEx这个名字。它不是什么新潮的玩意儿但绝对是当前Unity游戏Mod开发领域里最稳定、最通用、也最受社区信赖的“基础设施”之一。简单来说BepInEx是一个Unity游戏插件/Mod框架它的核心工作是在游戏启动时“嵌入”进去为后续加载我们编写的各种Mod提供一个安全、标准化的运行环境。你可能会问Unity游戏自己不能加载DLL吗为什么需要这么一个框架这就要说到Mod开发的痛点了。直接修改游戏原生DLL程序集是极其危险且不稳定的一次游戏更新就可能让你所有的修改失效甚至导致游戏崩溃。而BepInEx扮演了一个“中间人”和“管家”的角色。它通过一系列精巧的技术我们后面会细说在游戏启动的早期阶段就介入接管了游戏加载程序集Assembly的流程。这样一来我们开发者就可以把精力集中在Mod的功能逻辑上而不用去操心如何破解游戏、如何注入代码、如何管理依赖这些底层又繁琐的事情。从GitHub仓库的简介来看BepInEx支持Unity Mono、IL2CPP以及.NET框架的游戏如XNA、FNA。虽然目前IL2CPP的支持还在完善中但主流的、基于Mono的Unity游戏这也是过去十年大部分Unity游戏的默认脚本后端已经得到了非常成熟和稳定的支持。超过8.2k的Star和活跃的社区讨论也证明了它的可靠性和生态活力。无论你是想为自己喜欢的游戏添加一个新功能还是想系统学习游戏逆向与修改技术BepInEx都是一个绝佳的起点和平台。2. BepInEx核心架构与工作原理拆解要玩转BepInEx不能只停留在“复制粘贴教程”的层面。理解它的核心架构和工作原理能让你在遇到问题时快速定位甚至自己动手解决一些疑难杂症。BepInEx的启动过程可以看作一场精心策划的“潜入行动”。2.1 启动流程从Doorstop到PreloaderBepInEx的启动不依赖于修改游戏主程序而是利用了一个名为Doorstop的库。Doorstop的原理是利用操作系统的环境变量如WINEDLLOVERRIDES在Linux/Proton下或特定的DLL劫持技术在游戏进程创建之初强制让其先加载一个指定的DLL也就是BepInEx的核心组件。这个过程发生在Unity引擎自身初始化之前给了BepInEx一个“先发制人”的机会。当Doorstop成功将BepInEx的Preloader预加载器注入后好戏才真正开始。Preloader是BepInEx启动链条中的第一个环节它的任务非常关键环境准备创建BepInEx所需的目录结构如BepInEx/plugins存放Mod、BepInEx/patchers存放补丁器、BepInEx/config存放配置文件。程序集劫持这是最核心的一步。Preloader会挂钩HookUnity的Assembly.Load等相关方法。当游戏尝试加载其自身的程序集比如Assembly-CSharp.dll这里面就包含了游戏的大部分逻辑代码时控制权会先落到Preloader手里。加载核心与插件Preloader接着加载BepInEx的核心库BepInEx.Core.dll然后根据配置加载所有放置在plugins文件夹下的Mod DLL文件。注意很多新手容易混淆BepInEx的版本。BepInEx 5是当前最稳定、应用最广的版本主要面向Unity Mono。而BepInEx 6Bleeding Edge版本则加强了对Unity IL2CPP的支持。对于绝大多数Mod开发者和玩家除非你明确要修改一个使用IL2CPP编译的游戏一些为反作弊或性能优化而采用的新游戏否则建议优先使用BepInEx 5的稳定版。2.2 Harmony运行时打补丁的利器BepInEx自身提供了基础的插件加载能力但要让Mod真正修改游戏行为最常用的工具是Harmony在BepInEx生态中通常指HarmonyX一个活跃维护的分支。Harmony是一个实现运行时方法补丁Runtime Patching的库。你可以把它理解成一个高级的“代码手术刀”。游戏运行时的所有逻辑都表现为一个个类Class和方法Method。Harmony允许你Prefix前缀在目标方法执行之前运行你的代码。你可以选择跳过原始方法的执行或者修改传入原始方法的参数。Postfix后缀在目标方法执行之后运行你的代码。你可以读取或修改原始方法的返回值或者执行一些清理工作。Transpiler转换器这是更底层的操作它允许你直接修改目标方法的IL指令一种中间语言。这通常用于实现一些Prefix和Postfix无法完成的复杂修改比如修改方法内部的逻辑判断。例如你想在《星露谷物语》中玩家每次收获作物时额外获得金币。你不需要找到源代码重新编译只需要用Harmony定位到处理收获的那个方法用一个Postfix补丁在方法执行后给玩家的金钱加上一个值即可。这种方式非侵入、模块化多个Mod修改同一个方法时Harmony还能尝试协调它们的执行顺序。2.3 插件加载器与跨平台兼容性BepInEx的另一个强大之处在于其设计的包容性。它不仅仅是一个单一的框架还通过“插件加载器”机制兼容了其他一些Mod框架的插件。在它的官方列表中你可以看到BSIPABeat Saber Mod框架、MelonLoader、Unity Mod Manager等框架的加载器适配。这意味着如果一个游戏社区最初使用的是MelonLoader后来想迁移到BepInEx或者开发者想编写能跨框架使用的ModBepInEx提供了这种可能性。对于跨平台BepInEx也做了考量。其核心组件使用.NET编写理论上具有跨平台能力。在Windows上Doorstop通过DLL劫持实现注入在Linux和macOS上则通常通过ProtonSteam Play或特定的Wine环境变量来实现。这也是为什么你在一些Steam Deck基于Linux的游戏社区里也能看到BepInEx Mod教程的原因。3. 从零开始BepInEx Mod开发环境搭建与第一个插件理论说了不少现在我们来点实际的。假设我们要为一款虚构的Unity游戏《幻想农场》开发一个简单的Mod功能是在游戏启动时在控制台打印一条欢迎信息。3.1 环境准备与工具链首先你需要一个开发环境。和普通的Unity游戏开发不同Mod开发通常不需要完整的Unity Editor但需要能分析游戏程序集的工具。开发工具IDE强烈推荐使用Visual Studio 2022或JetBrains Rider。它们对C#和.NET开发的支持最为完善。.NET SDK安装与你目标游戏运行时相匹配的.NET版本。大部分Unity Mono游戏基于**.NET Framework 4.x** 或.NET Standard 2.0。你可以在Visual Studio Installer中安装相应的开发包。逆向分析工具必备dnSpy/dnSpyEx或ILSpy这是Mod开发者的“眼睛”。游戏编译后的代码是IL中间语言或机器码这些反编译工具可以将其转换回可读的C#代码尽管变量名可能丢失变成arg1,var2等。你需要用它来查找你想要修改的类和方法。Unity Assets Bundle Extractor (UABE)如果你想修改游戏资源如UI、贴图、文本这个工具会很有用。目标游戏与BepInEx准备好你的《幻想农场》游戏并确保它已经安装了正确版本的BepInEx。通常Mod社区会提供整合好的安装包或一键安装器。3.2 创建第一个BepInEx插件项目打开Visual Studio创建一个新的类库.NET Framework 或 .NET Standard项目命名为FantasyFarmWelcomeMod。接下来需要通过NuGet包管理器添加必要的引用。右键点击项目 - “管理NuGet程序包”。搜索并安装以下包BepInEx.Core这是BepInEx插件的核心依赖定义了插件的基本结构和接口。HarmonyX用于进行运行时方法补丁。确保安装的是HarmonyX而不是老版本的Lib.Harmony。安装后你的项目引用中应该能看到BepInEx.Core和0HarmonyHarmonyX的包名。3.3 编写插件主类在项目中创建一个新的C#类文件命名为FantasyFarmPlugin.cs。using BepInEx; using BepInEx.Logging; using HarmonyLib; namespace FantasyFarmWelcomeMod { // 1. 定义插件元数据 [BepInPlugin(PluginGuid, PluginName, PluginVersion)] public class FantasyFarmPlugin : BaseUnityPlugin { // 定义插件的唯一标识符、名称和版本 public const string PluginGuid com.yourname.fantasyfarm.welcome; public const string PluginName 幻想农场欢迎Mod; public const string PluginVersion 1.0.0; // 2. 获取日志记录器方便输出信息 internal static ManualLogSource Log; // 3. 插件的启动入口 private void Awake() { // 初始化日志记录器 Log Logger; // 记录插件加载成功的信息 Log.LogInfo($插件 {PluginName} v{PluginVersion} 正在加载...); // 4. 应用Harmony补丁 Harmony.CreateAndPatchAll(typeof(FantasyFarmPlugin).Assembly); Log.LogInfo($插件 {PluginName} 加载完成); } } }代码解析[BepInPlugin]这个属性是必须的它告诉BepInEx这是一个插件并提供了插件的GUID全局唯一标识符必须独一无二、显示名和版本。BaseUnityPlugin所有BepInEx插件的基类。它提供了Logger属性用于日志记录以及Unity MonoBehaviour常见的生命周期方法如Awake,Start,Update。Harmony.CreateAndPatchAll这一行代码会扫描当前程序集你的Mod DLL中所有使用了Harmony属性的类并自动应用补丁。这是一种批量应用补丁的简便方法。3.4 使用Harmony创建第一个补丁现在我们需要用Harmony来实际修改游戏行为。假设我们通过dnSpy分析发现游戏主管理器类GameManager有一个名为Start的方法游戏启动时会被调用。我们在项目中再创建一个类文件GameManagerPatches.cs。using HarmonyLib; using BepInEx.Logging; namespace FantasyFarmWelcomeMod { [HarmonyPatch(typeof(GameManager))] // 指定要修补的类 [HarmonyPatch(nameof(GameManager.Start))] // 指定要修补的方法 class GameManagerStartPatch { // 这是一个Prefix补丁将在原方法执行前运行 static void Prefix(GameManager __instance) { // 使用插件的日志记录器输出信息 FantasyFarmPlugin.Log.LogInfo( 欢迎来到幻想农场愿你收获满满); // 你也可以尝试访问实例的成员如果知道的话 // 例如如果GameManager有个public的playerName字段 // FantasyFarmPlugin.Log.LogInfo($玩家 {__instance.playerName} 已进入游戏。); } } }代码解析[HarmonyPatch]Harmony的核心属性。第一个指定目标类第二个指定目标方法。nameof操作符可以防止方法名拼写错误。Prefix方法这是一个静态方法名字必须是Prefix。Harmony通过特性Attribute来识别它。__instance参数这是一个特殊的命名参数。以__开头的参数是Harmony注入的上下文信息。__instance代表了当前正在执行的目标方法的对象实例如果方法是静态的则为null。通过它我们可以访问和修改该实例的字段和属性。3.5 编译、部署与测试编译在Visual Studio中生成解决方案Build Solution。你会在项目的bin/Debug或bin/Release文件夹下找到生成的FantasyFarmWelcomeMod.dll文件。部署将FantasyFarmWelcomeMod.dll文件复制到游戏目录下的BepInEx/plugins文件夹中。如果plugins文件夹不存在就手动创建一个。测试启动游戏。同时打开游戏根目录下的BepInEx/LogOutput.log文件这是BepInEx的日志文件。你应该能看到类似以下的输出[Info :FantasyFarmWelcomeMod] 插件 幻想农场欢迎Mod v1.0.0 正在加载... [Info :FantasyFarmWelcomeMod] 插件 幻想农场欢迎Mod 加载完成 [Info :FantasyFarmWelcomeMod] 欢迎来到幻想农场愿你收获满满恭喜你你的第一个BepInEx Mod已经成功运行了实操心得在开发初期务必养成查看LogOutput.log的习惯。它是排查Mod问题最重要的窗口。BepInEx的日志级别可以在BepInEx/config/BepInEx.cfg中配置默认的Info级别对于调试通常已经足够。如果遇到Mod没加载首先检查日志文件的前几行看BepInEx核心是否加载成功你的插件DLL是否被识别。4. 深入实战复杂Mod功能实现与架构设计一个简单的欢迎Mod只是开始。真正的Mod往往涉及状态管理、配置读取、UI交互等复杂功能。BepInEx为这些常见需求提供了优雅的解决方案。4.1 配置文件与用户设置很少有Mod是“一刀切”的通常需要让用户自定义一些参数。BepInEx内置了基于Toml的配置系统。让我们扩展之前的Mod允许用户自定义欢迎信息。首先在插件主类的Awake方法中在应用Harmony补丁之前添加配置读取逻辑private void Awake() { Log Logger; Log.LogInfo($插件 {PluginName} v{PluginVersion} 正在加载...); // 1. 绑定配置 WelcomeMessage Config.Bind( General, // 配置节(Section) WelcomeMessage, // 配置键(Key) 欢迎来到幻想农场愿你收获满满, // 默认值 游戏启动时显示的欢迎信息。 // 描述 ); // 2. 应用补丁 Harmony.CreateAndPatchAll(typeof(FantasyFarmPlugin).Assembly); Log.LogInfo($插件 {PluginName} 加载完成); } // 3. 公开一个静态属性供补丁类访问 public static ConfigEntrystring WelcomeMessage { get; private set; }然后修改我们的Harmony补丁类使用配置项[HarmonyPatch(typeof(GameManager))] [HarmonyPatch(nameof(GameManager.Start))] class GameManagerStartPatch { static void Prefix(GameManager __instance) { // 从插件的静态属性中读取配置信息 string message FantasyFarmPlugin.WelcomeMessage.Value; FantasyFarmPlugin.Log.LogInfo(message); } }现在当用户运行游戏后在BepInEx/config文件夹下会生成一个以你的插件GUID命名的.cfg文件例如com.yourname.fantasyfarm.welcome.cfg。用户可以直接用文本编辑器打开它进行修改[General] ## 游戏启动时显示的欢迎信息。 # Setting type: String # Default value: 欢迎来到幻想农场愿你收获满满 WelcomeMessage 这是我自定义的欢迎语下次启动游戏时控制台就会显示用户自定义的文本了。BepInEx的配置系统还支持整数、浮点数、布尔值、枚举甚至自定义类需序列化非常强大。4.2 游戏UI修改与交互许多Mod需要添加新的按钮、窗口或者修改现有UI。这通常需要用到Unity的即时模式GUIIMGUI系统或者更现代的游戏内UI系统。使用IMGUIOnGUI方法 这是最简单直接的方法适合绘制简单的调试信息或控制面板。你可以在你的插件类中继承并实现OnGUI方法。public class FantasyFarmPlugin : BaseUnityPlugin { private bool showWelcomeWindow true; private Rect windowRect new Rect(20, 20, 300, 150); private void OnGUI() { if (!showWelcomeWindow) return; // 创建一个IMGUI窗口 windowRect GUI.Window( 0, // 窗口ID windowRect, // 位置和大小 DrawWindow, // 绘制窗口内容的委托 幻想农场Mod面板 // 窗口标题 ); } private void DrawWindow(int windowId) { // 显示欢迎信息 GUILayout.Label(FantasyFarmPlugin.WelcomeMessage.Value); // 一个按钮示例 if (GUILayout.Button(隐藏本窗口)) { showWelcomeWindow false; } // 允许拖动窗口 GUI.DragWindow(); } }更高级的UI集成 对于复杂的、需要与游戏原生UI风格一致的Mod直接使用IMGUI可能显得突兀。这时就需要更深入的技术查找并修改现有GameObject使用Harmony补丁游戏UI的初始化方法获取到Canvas、Panel等GameObject的引用然后使用GameObject.Instantiate实例化你预先制作好的UI预制体Prefab并将其设置为游戏对象的子物体。使用UI框架社区有一些为BepInEx Mod开发的UI框架例如ConfigurationManager用于生成美观的配置窗口或UIExpansionKit用于某些特定游戏。这些框架封装了复杂的UI操作可以大大简化开发。注意事项UI操作必须在Unity的主线程中进行。如果你在Harmony补丁的方法里它可能在任意线程被调用直接创建GameObject可能会导致崩溃。安全的做法是使用UnityEngine.Object.FindObjectOfType或通过已获取的实例引用来操作或者将UI创建逻辑放在MonoBehaviour的Start或Update方法中。4.3 持久化数据与存档管理有些Mod需要保存自己的数据比如玩家自定义的配方、额外的物品栏状态等。这些数据需要和游戏存档一起保存和加载。方法一利用游戏现有的存储机制这是最安全、兼容性最好的方法。你需要分析游戏是如何保存数据的。例如游戏可能有一个SaveData类里面包含了所有需要保存的字段。你可以用Harmony给这个类添加新的字段并确保补丁了游戏的序列化保存和反序列化加载方法来读写你新增的字段。方法二使用BepInEx的辅助工具或自定义文件如果修改游戏存档结构太复杂可以考虑将Mod数据保存在独立的文件中并以游戏存档的名称或ID来命名关联文件。当游戏加载某个存档时你的Mod也去加载对应的外部数据文件。BepInEx的Paths类提供了方便的路径获取方法如Paths.BepInExRootPath、Paths.PluginPath等你可以将数据文件存放在这些路径下。using System.IO; using BepInEx; string saveDataPath Path.Combine(Paths.BepInExRootPath, MyModData, ${currentSaveSlotId}.dat); // 然后使用JsonUtility、BinaryFormatter或第三方库如Newtonsoft.Json来读写文件。踩坑记录直接使用.NET的BinaryFormatter进行序列化在跨游戏版本时极易出错因为类结构一旦变化就无法反序列化。推荐使用JSON这类文本格式并做好版本管理和数据迁移的逻辑。同时读写文件是IO操作务必做好异常处理try-catch避免因为文件被占用或权限问题导致游戏崩溃。5. 调试、排查与Mod发布全流程开发过程中Bug如影随形。一个成熟的Mod开发者必须掌握高效的调试和问题排查技巧。5.1 调试技术日志、调试器与热重载日志分级输出BepInEx的ManualLogSource提供了不同级别的日志方法LogDebug,LogInfo,LogWarning,LogError。合理使用它们。Debug用于输出最详细的流程信息发布时应关闭在配置文件中设置LogLevels None。Info记录关键步骤如插件加载、配置读取。Warning记录可能有问题但不影响功能的情况如找不到某个可选资源。Error记录错误和异常必须立即关注。附加调试器这是定位复杂问题的终极武器。你可以使用Visual Studio或dnSpy的调试功能附加到游戏进程上。在Visual Studio中点击“调试” - “附加到进程”找到你的游戏进程。在代码中设置断点。当游戏执行到你的补丁方法时调试器就会中断你可以查看所有变量的值、调用堆栈一步步执行。关键点你需要确保你的Mod DLL是带调试符号.pdb文件编译的并且调试器能定位到源代码。热重载与快速迭代频繁重启游戏测试Mod效率极低。社区有一些工具可以实现“热重载”比如针对部分游戏的UnityExplorer等工具它们允许你在游戏运行时重新加载修改后的Mod DLL。但更通用的方法是利用BepInEx的插件链功能结合FileSystemWatcher监听DLL文件变化然后动态卸载和重新加载插件。这需要更高级的编程技巧但对于提升开发效率帮助巨大。5.2 常见问题排查速查表下表列出了BepInEx Mod开发中最常见的一些问题及其排查思路问题现象可能原因排查步骤Mod完全没加载日志中无相关记录。1. DLL未放入BepInEx/plugins文件夹。2. DLL依赖项缺失如未正确引用BepInEx.Core。3. 插件GUID冲突。1. 检查文件路径是否正确。2. 使用ILSpy打开你的DLL查看引用是否正确尝试将依赖项DLL也放入plugins文件夹。3. 检查是否有其他Mod使用了相同的GUID。游戏启动时崩溃日志显示TypeLoadException或MissingMethodException。1. 引用的BepInEx或Harmony版本与游戏运行时的不匹配。2. 使用了游戏程序集中不存在的类或方法名拼写错误或游戏版本更新。1. 确保你的项目引用的BepInEx.Core版本与游戏安装的BepInEx版本一致或兼容。2. 用dnSpy重新检查目标游戏程序集确认类名和方法签名完全正确。补丁方法被执行了但游戏行为未改变。1. Prefix/Postfix方法签名错误参数类型、数量不对。2. 补丁的目标方法不对有重载方法。3. Prefix补丁中未正确设置__result或__runOriginal。1. 仔细核对HarmonyPatch特性中的类名和方法名以及补丁方法的参数。2. 使用[HarmonyPatch(typeof(Class), typeof(Method), new Type[]{paramType1, paramType2})]指定具体重载。3. 检查Prefix逻辑确保没有意外地return false;这会跳过原方法。Mod功能时好时坏或与其他Mod冲突。1. 多个Mod修补了同一个方法执行顺序导致问题。2. Mod有状态依赖未正确处理游戏场景加载/卸载。1. 使用Harmony的Priority属性调整补丁优先级。查看日志中Harmony的调试输出。2. 确保你的插件类正确使用Awake、OnEnable、OnDisable等生命周期方法管理状态。自定义配置不生效。1. 配置键Key名称拼写错误。2. 配置文件是只读的或路径无写入权限。3. 在Awake之后才读取配置。1. 检查Config.Bind中的section和key名称并与生成的.cfg文件对比。2. 检查BepInEx/config目录权限。3. 确保在需要使用配置值之前如补丁方法中已经完成了Config.Bind。5.3 发布与维护打造一个专业的Mod当你的Mod开发完成并经过充分测试后就可以考虑发布了。版本管理使用语义化版本控制如主版本.次版本.修订号。每次发布新版本时更新插件类中的PluginVersion常量。编写说明文档至少应该有一个README.md文件说明Mod的功能、安装方法、配置选项、已知问题等。清晰的文档能减少大量用户咨询。打包发布通常将以下文件打包成ZIP或使用Mod管理器支持的格式你的插件DLL文件。必要的依赖项DLL如果未内嵌。README.md。可选的图标文件。manifest.json如果目标游戏社区有特定的Mod管理器规范如Thunderstore Mod Manager。选择发布平台GitHub Releases适合开源项目便于跟踪问题和版本。游戏专属Mod站如Nexus Mods、Thunderstore能直接触达目标玩家社区。游戏内置创意工坊如果游戏支持如《幻兽帕鲁》这是最方便玩家的方式。社区维护积极回应用户在发布页面的评论和问题。收集反馈修复Bug考虑添加用户请求的新功能。一个活跃维护的Mod生命周期会更长。开发BepInEx Mod是一个不断学习、探索和解决问题的过程。从简单的文本替换到复杂的系统重构其魅力在于你能以开发者的视角深入你喜爱的游戏并与其他玩家分享你的创意和成果。这套工具链和生态已经相当成熟剩下的就取决于你的想象力和对游戏的理解深度了。记住多读社区其他优秀Mod的源码是提升最快的方式之一。