1. 项目概述为什么你需要BepInEx如果你是一个Unity游戏的玩家尤其是那些支持创意工坊的游戏你肯定对“模组”这个词不陌生。从《星露谷物语》里增加新作物到《英灵神殿》里优化建造体验再到《觅长生》里引入全新的功法系统模组极大地扩展了游戏的可玩性和生命周期。但你是否想过这些形态各异的模组是如何被“注入”到游戏进程里并和谐共存的这背后一个强大而低调的框架功不可没——它就是BepInEx。简单来说BepInEx是一个为Unity引擎游戏设计的、开源的模组加载与插件框架。它的核心工作是在游戏启动时将自己“嵌入”到游戏进程中为后续所有模组在BepInEx的语境下通常称为“插件”提供一个稳定、统一的运行环境和管理平台。你可以把它想象成一个“模组操作系统”所有第三方代码都运行在这个系统之上由它来负责加载、初始化、管理依赖和提供通用服务从而避免了模组之间直接冲突、覆盖文件等混乱局面。为什么说它是“终极”选择因为在Unity游戏模组领域BepInEx几乎已经成为事实上的标准。相比早期的注入工具如UnityInjector或者一些游戏专用的模组加载器BepInEx的优势是全方位的它支持跨平台Windows, Linux, macOS拥有强大的插件依赖管理通过BepInDependency特性提供了丰富的内置工具如配置管理器、日志查看器并且其代码是开源的社区活跃文档相对完善。对于模组开发者而言使用BepInEx意味着更低的入门门槛和更稳定的运行环境对于普通玩家则意味着更简单、更安全的模组安装与管理体验。这篇指南的目的就是让你在5分钟内理解BepInEx的核心并能够动手为你的游戏配置好它开启模组之旅。2. BepInEx核心架构与工作原理拆解要玩转BepInEx不能只停留在“复制粘贴”文件的层面。理解其基本架构能帮助你在遇到问题时快速定位甚至自己动手开发简单的插件。2.1 核心组件与启动流程BepInEx的安装包解压后你会看到几个核心文件和文件夹BepInEx/core/: 存放BepInEx框架自身的核心库如BepInEx.dll、BepInEx.Harmony.dll等。这是框架的“心脏”。BepInEx/plugins/: 这是所有第三方插件即我们常说的模组的默认存放目录。每个插件通常是一个独立的文件夹里面包含其DLL文件、资源和配置文件。BepInEx/config/: 存放各个插件的配置文件.cfg文件。BepInEx内置了ConfigurationManager插件通常需要额外安装可以让你在游戏内图形化地修改这些配置。BepInEx/patchers/: 用于存放“补丁器”Patcher插件。这是一种更底层的插件能在游戏程序集加载的早期阶段对其进行修改通常用于为其他插件提供运行基础或进行复杂的底层Hook。doorstop_config.ini和winhttp.dll(Windows下): 这是BepInEx实现“无感注入”的关键。它们利用操作系统的DLL劫持机制在游戏启动时优先加载BepInEx的引导程序从而将框架注入游戏进程。对玩家来说这个过程是完全透明的。启动流程可以简化为你点击游戏图标 → 操作系统加载游戏执行文件 →winhttp.dll被重定向率先被加载 → 它启动BepInEx的引导程序 → 引导程序准备环境、加载BepInEx/core/下的核心库 → 核心库扫描plugins/和patchers/目录加载并初始化所有插件 → 最后将控制权交还给游戏原主程序。至此一个搭载了模组系统的游戏就运行起来了。2.2 Harmony库运行时“打补丁”的魔法BepInEx的强大功能很大程度上依赖于一个名为Harmony的库。Harmony是一个强大的.NET库用于在运行时对已编译的程序如游戏进行方法级别的修改即“打补丁”。这是实现游戏功能修改的核心技术。想象一下游戏代码是一本已经印刷好的书。你想修改某一页的某一段话。传统模组可能需要你替换整本书替换游戏文件风险高且易冲突。而Harmony的做法是允许你在这本书的特定段落旁贴上一些“便利贴”上面写着“当读到这句话时请先执行我的代码然后再决定是否继续读原文或者完全替换掉原文的内容。”在技术上这主要通过三种补丁实现前缀补丁 (Prefix): 在原方法执行之前运行。可以修改传入的参数甚至可以完全跳过原方法的执行。后缀补丁 (Postfix): 在原方法执行之后运行。可以读取或修改原方法的返回值也可以访问原方法的参数。变址补丁 (Transpiler): 这是最强大也是最复杂的一种。它直接修改原方法的IL代码.NET的中间语言指令可以实现极其精细和复杂的逻辑修改。普通模组开发者很少需要直接使用它。通过Harmony模组开发者可以在不接触游戏原始代码的情况下改变游戏的行为。例如一个修改玩家金钱的模组可能会找到游戏内部处理金钱增加的AddMoney方法用一个后缀补丁在每次加钱后额外再乘以一个系数。注意Harmony补丁虽然强大但必须谨慎使用。错误地修改关键方法可能导致游戏崩溃或不稳定。良好的实践是尽量针对功能单一、职责明确的方法进行补丁在补丁中加入充分的空值检查和异常处理并利用BepInEx的日志功能输出调试信息。3. 五分钟实战为你的游戏安装BepInEx理论说再多不如动手做一遍。下面我们以一款典型的Windows平台Unity游戏为例演示如何安装BepInEx。请注意不同游戏可能略有差异但核心步骤通用。3.1 准备工作与版本选择确定游戏信息首先找到你的游戏安装目录。通常可以通过Steam库 - 右键游戏 - “管理” - “浏览本地文件”快速定位。下载BepInEx访问BepInEx的GitHub发布页。这里有一个关键选择下载哪个版本BepInEx_x64_5.4.xx.zip: 适用于64位x64游戏。这是目前绝大多数Unity游戏的标准。BepInEx_x86_5.4.xx.zip: 适用于32位x86游戏较老的游戏可能使用。BepInEx_unix_5.4.xx.zip: 适用于Linux/macOS系统。BepInEx_net35_5.4.xx.zip: 适用于使用较老.NET 3.5框架的游戏多见于2018年以前的Unity游戏。 如果你不确定优先选择x64版本。如果游戏启动失败再尝试net35版本。版本号选择最新的稳定版如5.4.x即可。3.2 标准安装步骤假设我们的游戏是64位的安装路径是D:\Steam\steamapps\common\MyUnityGame。解压将下载的BepInEx_x64_5.4.xx.zip文件解压。你会得到一个名为BepInEx的文件夹以及doorstop_config.ini、winhttp.dll等几个文件。复制将解压出的所有文件和文件夹全部复制到游戏的根目录即MyUnityGame文件夹下。你的游戏目录结构应该变成这样MyUnityGame/ ├── Game.exe ├── UnityPlayer.dll ├── winhttp.dll (来自BepInEx) ├── doorstop_config.ini (来自BepInEx) ├── BepInEx/ (来自BepInEx) │ ├── core/ │ ├── plugins/ │ └── ... └── (其他游戏原有文件和文件夹)首次运行直接双击Game.exe启动游戏。如果安装成功游戏启动时你可能会在屏幕角落看到BepInEx的版本号一闪而过或者启动时间稍长一些。进入游戏主菜单后立即退出游戏。这一步至关重要目的是让BepInEx完成初次启动的目录结构生成和基础配置。验证安装再次打开游戏根目录检查BepInEx文件夹。里面应该自动生成了config、LogOutput.log等文件或文件夹。打开BepInEx/plugins/文件夹此时它应该是空的除非BepInEx包自带了示例插件。打开BepInEx/LogOutput.log文件如果能看到包含[Info]的启动日志没有大量的[Error]恭喜你BepInEx框架安装成功3.3 安装进阶配置与调优首次安装后你可能需要根据游戏情况调整doorstop_config.ini。用文本编辑器打开它关注以下几个关键配置[General] ; 是否启用Doorstop。如果设为falseBepInEx将不会被加载。 enabledtrue ; 目标程序集。通常不需要修改BepInEx会自动寻找UnityPlayer.dll或GameAssembly.dll。 targetAssemblyDoorstop.dll ; 重定向的DLL名称。在Windows上是winhttp.dll。除非与游戏其他组件冲突否则不要改。 redirectOutputLogtrue ; 是否将Unity的日志也重定向到BepInEx的日志文件建议保持true便于排查问题。 [BepInEx] ; BepInEx核心配置文件路径一般无需改动。 doorstopTypeDoorstop实操心得如果游戏启动崩溃首先检查LogOutput.log文件的末尾几行。常见的错误包括游戏位数x86/x64与BepInEx版本不匹配游戏使用的.NET框架版本3.5/4.x/等与BepInEx不兼容或者winhttp.dll与游戏自带的某个系统DLL冲突极少见。对于冲突问题可以尝试将doorstop_config.ini中的redirectAssemblyDirs和ignoreDisableSwitch等高级选项进行配置或查阅BepInEx官方Wiki的故障排除部分。4. 模组插件的安装与管理框架搭好了接下来就是往里面“装软件”——也就是安装模组插件。4.1 插件安装的通用法则绝大多数为BepInEx开发的插件发布时都是一个压缩包解压后通常包含以下一种或多种结构直接DLL文件一个单独的.dll文件。这是最简单的情况直接将它复制到BepInEx/plugins/目录下即可。带文件夹的插件一个以插件命名的文件夹里面包含.dll文件和其他资源如图片、配置文件模板等。需要将整个文件夹复制到BepInEx/plugins/下。包含plugins和patchers目录的发布包有些大型模组或框架如Mod管理器会直接提供仿照BepInEx目录结构的压缩包。你需要将其内容合并到游戏根目录的BepInEx文件夹里通常是覆盖plugins和patchers子目录。安装后启动游戏插件会自动加载。你可以在游戏内很多插件会添加配置菜单或游戏外的BepInEx/config/目录下找到生成的配置文件来调整插件设置。4.2 依赖管理与冲突解决随着安装的模组增多两个问题会浮现依赖和冲突。依赖管理很多插件会依赖其他插件提供的功能。例如一个UI扩展插件可能依赖BepInEx.ConfigurationManager来提供游戏内配置界面。负责任的插件作者会在发布页写明依赖项。BepInEx自身有简单的依赖加载机制如果插件A声明依赖插件B那么B会在A之前被加载。对于玩家你需要手动确保所有依赖的插件都已安装。一个良好的习惯是在安装新模组前仔细阅读其说明文档的“Requirements”需求部分。模组冲突当两个或多个模组修改了游戏的同一处代码或资源时就会发生冲突。表现可能是游戏崩溃、功能失效或行为异常。解决冲突没有银弹但可以遵循以下步骤隔离排查禁用所有模组然后逐个或分批次启用找到引起冲突的具体模组。检查加载日志LogOutput.log文件会记录每个插件的加载顺序和任何Harmony补丁应用信息。有时冲突会在这里留下线索。查阅社区去该游戏的模组社区如Nexus Mods, GitHub Issues搜索是否有其他人报告相同冲突及解决方案。调整加载顺序有些模组管理器如r2modman for Risk of Rain 2允许手动调整插件加载顺序这有时能解决因加载时机导致的冲突。4.3 必备辅助插件推荐为了让模组体验更顺畅有几个BepInEx生态下的“神器”级插件推荐安装Configuration Manager: 如前所述它提供了一个游戏内的图形化界面默认按F1键打开让你可以实时查看和修改所有已安装插件的配置无需再手动编辑文本cfg文件。BepInEx Console: 在游戏中开启一个类似命令行的控制台窗口默认按~键可以直接执行命令、查看日志、甚至调用游戏内部方法是高级玩家和开发者的调试利器。Mod Manager (游戏特定): 许多热门游戏都有社区开发的专用模组管理器如《英灵神殿》的r2modman或《星露谷物语》的SMAPI虽然SMAPI本身是另一个框架但很多BepInEx插件也兼容。它们提供了更友好的模组下载、启用/禁用、更新和依赖管理功能。注意事项安装任何插件后第一次启动游戏时请务必查看LogOutput.log。如果插件加载失败通常会在这里留下红色的[Error]日志指明是缺少依赖、版本不兼容还是代码有错误。养成看日志的习惯能解决你90%的模组问题。5. 从玩家到创造者BepInEx插件开发入门如果你不满足于使用模组还想亲手创造那么了解如何开发一个最简单的BepInEx插件是很有意义的。这不仅能让你更深入地理解模组工作原理还能让你有能力定制专属功能。5.1 开发环境搭建你需要准备集成开发环境 (IDE)推荐使用Visual Studio 2022 Community Edition免费。安装时记得勾选“.NET 桌面开发”工作负载。.NET SDK根据你的游戏目标框架安装。对于较新的Unity游戏使用IL2CPP后端你需要安装**.NET Framework 4.7.2或4.8开发者包**不是.NET Core。对于使用Mono后端的老游戏可能需要.NET 3.5。BepInEx 开发包从GitHub下载BepInEx发布包我们需要的其实是其中的核心DLL文件作为开发引用。通常将BepInEx/core/下的BepInEx.dll、BepInEx.Harmony.dll、0Harmony.dll、MonoMod.RuntimeDetour.dll等文件保存到一个专门的引用文件夹备用。目标游戏的程序集要修改游戏你需要知道游戏里有什么。使用如dnSpy或ILSpy这样的反编译工具打开游戏目录下的GameAssembly.dllIL2CPP游戏或Assembly-CSharp.dllMono游戏来浏览游戏的内部类和方法。这是寻找“打补丁”目标的关键步骤。5.2 创建你的第一个插件一个简单的“Hello World”让我们创建一个插件在游戏启动时在BepInEx的日志中打印一条消息。新建项目在Visual Studio中新建一个“类库(.NET Framework)”项目命名为MyFirstPlugin目标框架选择与游戏匹配的例如.NET Framework 4.7.2。添加引用在解决方案资源管理器中右键“引用” - “添加引用” - “浏览”找到你之前保存的BepInEx核心DLL文件添加BepInEx.dll和0Harmony.dll如果用到Harmony。编写插件主类删除默认的Class1.cs新建一个类文件例如HelloWorldPlugin.cs。using BepInEx; using BepInEx.Logging; using HarmonyLib; using System.Reflection; // 定义插件的元数据 [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class HelloWorldPlugin : BaseUnityPlugin // 必须继承BaseUnityPlugin { // 插件的唯一标识符通常使用“作者名.插件名”的格式确保全球唯一 public const string PluginGUID com.myname.helloworld; public const string PluginName My Hello World Plugin; public const string PluginVersion 1.0.0; // 内部日志记录器用于向BepInEx日志输出信息 internal static ManualLogSource Log; // Awake方法在插件被加载时由BepInEx自动调用 private void Awake() { // 初始化日志记录器 Log Logger; // 输出一条信息级日志 Log.LogInfo($Plugin {PluginName} is loaded!); // 应用Harmony补丁如果后续有补丁代码 // Harmony.CreateAndPatchAll(Assembly.GetExecutingAssembly()); } }编译与部署在Visual Studio中按F6生成项目。在项目的bin/Debug/或bin/Release/目录下你会找到生成的MyFirstPlugin.dll文件。将这个DLL文件复制到游戏的BepInEx/plugins/目录下。测试启动游戏然后打开BepInEx/LogOutput.log文件。你应该能在日志中搜索到一行类似[Info : My Hello World Plugin] Plugin My Hello World Plugin is loaded!的信息。恭喜你的第一个插件成功运行了5.3 深入一步使用Harmony修改游戏行为现在让我们做一个更有趣的插件假设我们想修改游戏里某个方法让玩家每次获得经验时额外多获得一点。首先你需要用dnSpy找到处理经验增加的方法。假设这个方法叫做Player.AddExp(int amount)。创建补丁类在你的项目中新建一个类例如ExpPatch.cs。编写Harmony补丁using HarmonyLib; [HarmonyPatch(typeof(Player))] // 指定要补丁的类 [HarmonyPatch(AddExp)] // 指定要补丁的方法名 class ExpPatch { // 这是一个后缀补丁在原方法执行后运行 static void Postfix(Player __instance, ref int amount) { // __instance 是原方法所属的Player对象实例 // amount 是传入的参数我们通过ref关键字可以修改它 int extraExp 1; // 额外经验值 amount extraExp; // 修改最终增加的经验值 // 使用之前插件主类里的日志记录器输出信息 HelloWorldPlugin.Log.LogInfo($玩家获得了 {amount} 点经验 (已额外增加 {extraExp} 点)); } }启用补丁回到HelloWorldPlugin.cs的Awake方法取消注释或添加应用补丁的代码private void Awake() { Log Logger; Log.LogInfo($Plugin {PluginName} is loaded!); // 应用所有标记了[HarmonyPatch]特性的补丁 Harmony.CreateAndPatchAll(Assembly.GetExecutingAssembly()); }重新编译并测试编译项目将新的DLL覆盖到plugins目录启动游戏。当你触发获得经验的行为时查看日志文件应该能看到你自定义的日志输出并且实际获得的经验值会比原版多1点。开发心得开发过程中最耗时的是“寻找正确的目标方法”。你需要仔细阅读反编译出的代码理解游戏逻辑。善用dnSpy的“分析”功能查看方法的调用者和被调用者能帮你快速定位。另外在补丁中务必进行空值检查如if (__instance null) return;因为游戏代码可能在非预期的情况下调用该方法。发布插件前请在纯净的BepInEx环境下充分测试。6. 常见问题排查与进阶技巧实录即使按照指南操作也难免会遇到问题。这里记录了一些常见场景及其解决方案。6.1 安装与启动类问题问题现象可能原因排查步骤与解决方案游戏完全无法启动无任何错误提示。1. BepInEx版本与游戏位数/框架不匹配。2.winhttp.dll冲突。1. 确认游戏是x86还是x64看主exe属性换用对应版本BepInEx。老游戏尝试net35版本。2. 暂时重命名游戏原生的winhttp.dll如果有的话或修改doorstop_config.ini中的redirectAssemblyDirs选项。游戏启动到一半闪退。1. 某个已安装的插件有严重错误。2. Harmony补丁冲突。1. 查看LogOutput.log末尾的[Error]信息定位出错的插件将其从plugins文件夹移除。2. 采用“二分法”移出一半插件测试逐步缩小范围找到冲突插件。BepInEx日志文件未生成或为空。Doorstop注入失败。1. 检查doorstop_config.ini中enabled是否设为true。2. 以管理员身份运行游戏试试。3. 某些杀毒软件或Windows Defender可能拦截了DLL注入尝试临时关闭。插件似乎安装了但游戏内无效果。1. 插件放置位置错误。2. 插件依赖未满足。3. 插件与当前游戏版本不兼容。1. 确认DLL文件或插件文件夹在BepInEx/plugins/下而不是BepInEx/core/。2. 阅读插件说明安装所有必需的依赖插件。3. 去插件发布页面查看支持的游戏版本。6.2 插件开发与调试类问题问题现象可能原因排查步骤与解决方案插件DLL放入后游戏日志显示加载成功但无任何效果。1. 补丁的目标方法名或签名错误。2. 补丁类未正确应用。1. 使用dnSpy仔细核对方法的全名、参数类型和返回类型。注意区分重载方法。2. 确保补丁类使用了[HarmonyPatch]特性并且在插件Awake中调用了Harmony.CreateAndPatchAll。打上补丁后游戏崩溃。1. 补丁代码逻辑错误如空引用。2. 修改了不应修改的底层数据。1. 在补丁方法开始处添加大量的Log.LogDebug输出检查变量状态。务必添加空值判断。2. 使用try-catch块包裹补丁代码将异常信息记录到日志。如何调试插件代码需要附加调试器。1. 在Visual Studio中选择“调试” - “附加到进程”找到游戏进程附加。2. 在插件代码中设置断点。这需要你的插件DLL是带调试符号PDB文件的Debug版本并且游戏未进行高强度代码优化IL2CPP调试非常复杂。对于Mono游戏此方法相对可行。6.3 性能与稳定性维护技巧日志管理LogOutput.log文件会越来越大。可以定期备份后删除。BepInEx 5.4支持按日期滚动的日志可在BepInEx/config/BepInEx.cfg中配置。插件清理定期检查plugins文件夹移除不再使用或已过时的插件。长期不更新的插件在新游戏版本下可能是潜在的不稳定因素。备份存档在安装或更新大量模组前务必手动备份你的游戏存档。模组冲突可能导致存档损坏。使用模组管理器对于模组生态丰富的游戏强烈建议使用社区维护的专用模组管理器。它们能自动处理依赖、解决部分冲突、并方便地进行模组包的备份和恢复。关注更新游戏更新后模组很可能失效。关注你常用模组的发布页面如Nexus Mods, GitHub看作者是否发布了兼容新版本的更新。在游戏更新后不要急于启用所有模组应先逐一测试核心模组。从框架安装到插件开发BepInEx为你打开了一扇深度定制Unity游戏的大门。它降低了模组开发的门槛也规范了模组运行的环境。无论是作为玩家享受社区创作的乐趣还是作为创造者实现自己的游戏想法理解并掌握这套工具链都能让你的游戏体验提升一个维度。记住耐心阅读日志、仔细查阅文档、积极参与社区讨论是解决一切模组相关问题的黄金法则。