1. 项目概述为什么选择BepInEx如果你是一个Unity游戏玩家尤其是对《英灵神殿》、《星露谷物语》、《觅长生》这类支持社区模组的游戏情有独钟那你大概率听说过“插件”或“Mod”这个词。这些插件能让你在游戏里添加新功能、修改游戏规则甚至创造全新的玩法。而BepInEx就是让这一切成为可能的“幕后英雄”——一个专为Unity游戏设计的插件加载与运行框架。简单来说BepInEx是一个桥梁。它一头连接着未经修改的Unity游戏本体另一头连接着开发者编写的插件代码。它的核心任务是在游戏启动时将自己“注入”到游戏进程中接管一部分游戏初始化的流程从而为第三方插件提供一个安全、稳定、标准化的运行环境。这意味着插件开发者不再需要各自为战去研究如何破解游戏文件、如何绕过反作弊或者如何让不同插件之间不互相冲突。BepInEx把这些底层、复杂且容易出错的工作都包揽了开发者只需要专注于用C#编写插件逻辑本身。我选择深入BepInEx是因为在尝试为几款热门独立游戏制作插件时发现社区教程要么过于零散要么直接丢给你一个编译好的DLL文件对背后的原理和完整开发流程语焉不详。这导致一旦插件运行出错排查起来如同大海捞针。因此这份指南的目标是带你从零开始不仅学会如何使用BepInEx更要理解它每一步背后的工作原理最终能够独立开发、调试并发布高质量的Unity游戏插件。无论你是刚接触C#的编程新手还是想将Mod开发作为副业的资深玩家这份完全指南都将为你铺平道路。2. 核心架构与工作原理深度解析要精通BepInEx绝不能停留在“复制粘贴配置文件”的层面。我们必须深入其内部理解它是如何“无中生有”在游戏进程中开辟出一块属于插件的天地。这有助于你在遇到诡异Bug时能快速定位问题是出在框架、游戏兼容性还是你自己的代码逻辑上。2.1 BepInEx的启动流程从注入到初始化BepInEx的启动是一个精密的“外科手术”过程主要分为预加载、注入、引导、插件加载四个阶段。第一阶段预加载与注入。当你双击游戏启动器时操作系统会加载游戏的主执行文件通常是.exe。BepInEx通过一个名为winhttp.dll或doorstop的机制在游戏进程创建的早期阶段就被操作系统加载。这个机制利用了Windows的DLL搜索顺序劫持或Unity的启动参数注入确保BepInEx的引导代码能抢在游戏主逻辑开始前执行。这一步是关键它让BepInEx获得了宝贵的“先手”优势。第二阶段引导程序Bootstrap执行。被加载的BepInEx引导程序BepInEx.dll开始工作。它的首要任务是准备运行时环境。它会检查游戏使用的是Mono运行时还是IL2CPP运行时这是Unity的两种脚本后端然后相应地加载BepInEx的核心库。对于Mono游戏它会设置一系列钩子Hooks来拦截游戏对程序集的加载对于IL2CPP游戏过程更复杂需要利用Unity的UnityLinker和GameAssembly进行干预。第三阶段核心初始化与路径管理。引导程序会创建BepInEx所需的目录结构通常是在游戏根目录下生成一个BepInEx文件夹里面包含plugins插件、config配置文件、patchers补丁器、core核心库等子目录。同时它会初始化自己的日志系统你看到的LogOutput.log文件就是这时创建的。日志是排查问题的生命线框架和插件所有的运行信息都会记录于此。第四阶段插件扫描与加载。这是最激动人心的阶段。BepInEx会遍历BepInEx/plugins目录及其子目录寻找所有有效的插件程序集.dll文件。对于每一个找到的DLL它会使用反射Reflection技术加载程序集并查找继承了BaseUnityPlugin类的类型。找到后它会创建该插件类的实例并依次调用其Awake()、Start()、Update()等生命周期方法如果存在的话从而将插件逻辑“挂载”到游戏的运行循环中。注意很多新手会疑惑为什么我的插件类必须继承BaseUnityPlugin这是因为BepInEx需要通过这个基类来识别和管理插件。它提供了插件的元数据如GUID、名称、版本和标准的Unity MonoBehaviour生命周期钩子确保了插件加载的顺序性和可控性。2.2 关键组件详解不仅仅是Plugins文件夹一个标准的BepInEx安装目录远不止一个plugins文件夹。理解每个组件的职责是进行高级开发和故障诊断的基础。BepInEx/core/: 存放BepInEx框架自身的核心库如BepInEx.Core.dll、0Harmony.dll等。通常用户不需要改动这里。BepInEx/plugins/: 用户插件的主目录。你可以直接放.dll文件也可以按作者或功能创建子文件夹来分类管理。框架会递归搜索所有子目录。BepInEx/patchers/: 存放“补丁器”Patcher的目录。这是BepInEx更高级的功能。插件Plugin是在游戏运行时动态加载的而补丁器是在游戏程序集被加载时或前对游戏的原始代码IL代码进行永久性修改的工具。例如修改某个方法的内部逻辑或者给某个类添加新的字段。这需要用到Harmony库进行IL注入风险更高但能力也更强。BepInEx/config/: 每个插件都可以拥有自己的配置文件.cfg文件。BepInEx内置了强大的配置管理功能插件可以在这里定义可被用户调整的选项框架会自动生成和读写这些文件。doorstop_config.ini / winhttp.dll: 这是BepInEx的注入器。doorstop适用于大多数跨平台和Windows游戏通过环境变量和配置文件工作而winhttp.dll则是针对某些特定Windows游戏的DLL劫持方案。它们共同的目标只有一个让游戏先加载BepInEx。2.3 Mono vs IL2CPP两种运行时的兼容性策略Unity游戏有两种主要的脚本后端BepInEx对它们的处理方式截然不同。对于Mono后端游戏这是BepInEx的传统优势领域。Mono运行时动态加载和管理.NET程序集DLL。BepInEx通过拦截游戏对Assembly.Load等方法的调用能够无缝地将自己的核心库和插件库加入到游戏的程序域AppDomain中。整个过程相对直接兼容性最好调试也最方便。对于IL2CPP后端游戏IL2CPP是Unity将C#代码提前AOT编译成C再编译为本地机器码的技术。这意味着游戏发布后原始的.NET程序集结构已不存在传统的反射和程序集加载机制失效。BepInEx为此采用了名为“UnityDoorstop”或“BepInEx.IL2CPP”的专门分支。它的原理更加底层注入点通常通过修改游戏的UnityPlayer.dll或注入到GameAssembly.dll的初始化函数中。通信桥梁在本地代码C层面和托管代码C#层面之间建立一个通信通道如Named Pipe或共享内存。托管域重载在IL2CPP初始化后手动创建一个新的.NET运行时域并将BepInEx和插件代码加载到这个新域中运行。实操心得开发插件前第一件事就是确定目标游戏是Mono还是IL2CPP。方法很简单用解包工具查看游戏目录如果存在GameAssembly.dll通常还有UnityPlayer.dll就是IL2CPP如果存在GameName_Data/Managed/Assembly-CSharp.dll就是Mono。针对IL2CPP游戏开发插件对开发环境需要对应版本的Unity Editor和IL2CPP构建支持和调试工具的要求更高初学者建议从Mono游戏入手。3. 开发环境搭建与第一个插件理论说得再多不如动手写一行代码。让我们从零开始创建一个最简单的“Hello World”插件。3.1 环境准备工具链的选择与配置你需要以下工具集成开发环境IDEVisual Studio 2022 Community免费是首选。它对C#和.NET开发的支持最完善。安装时务必勾选“.NET桌面开发”和“使用Unity的游戏开发”工作负载。.NET Framework开发包大部分Unity游戏基于.NET Framework 4.x如4.7.2或.NET Standard 2.0。你需要在Visual Studio Installer中安装对应的目标包。BepInEx框架包不要只下载游戏用的BepInEx安装包。你需要的是BepInEx开发包。前往BepInEx的GitHub Releases页面下载名为BepInEx-pack-xxx.zip的包例如BepInEx_win_x64_5.4.21.0.zip。解压后我们主要需要其中的BepInEx.dll、0Harmony.dll、BepInEx.Harmony.dll等核心DLL文件作为我们项目的引用。目标游戏的程序集为了编写插件你需要引用游戏本身的代码。找到游戏目录下的GameName_Data/Managed/文件夹将整个文件夹复制到你的开发目录中备用。关键文件是Assembly-CSharp.dll它包含了游戏的大部分逻辑代码。3.2 创建插件项目从Visual Studio开始打开Visual Studio新建一个项目。选择“类库(.NET Framework)”模板命名为MyFirstBepInExPlugin。目标框架选择与游戏匹配的版本如果不确定选.NET Framework 4.7.2通常兼容性较好。在解决方案资源管理器中右键“引用” - “添加引用”。点击“浏览”找到你之前准备的BepInEx开发包添加BepInEx.dll和0Harmony.dll。再次“添加引用” - “浏览”找到你复制的游戏Managed文件夹添加Assembly-CSharp.dll。此外通常还需要添加UnityEngine.dll、UnityEngine.CoreModule.dll等Unity核心库它们也在Managed文件夹里。3.3 编写“Hello World”插件代码现在删除自动生成的Class1.cs新建一个名为MyFirstPlugin.cs的类文件。输入以下代码using BepInEx; using BepInEx.Logging; using UnityEngine; // 插件元数据 [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class MyFirstPlugin : BaseUnityPlugin // 必须继承BaseUnityPlugin { // 定义插件的唯一标识符、名称和版本 public const string PluginGUID com.yourname.myfirstplugin; public const string PluginName My First BepInEx Plugin; public const string PluginVersion 1.0.0; // 内部日志记录器 internal static ManualLogSource Log; // Awake方法在插件被加载时立即执行一次 private void Awake() { // 将基类的Logger赋值给我们的静态Log变量方便其他方法使用 Log Logger; // 在BepInEx的控制台和日志文件中输出信息 Log.LogInfo($Plugin {PluginGUID} is loaded!); // 尝试在游戏画面中创建GUI文字需要游戏有UI环境 // 更稳妥的做法是在Update或OnGUI中处理这里仅为演示 GameObject textObj new GameObject(MyPluginText); textObj.AddComponentGUIText().text Hello from BepInEx!; DontDestroyOnLoad(textObj); // 防止场景切换时被销毁 Log.LogInfo(Hello World GameObject created.); } // Update方法每一帧都会调用 private void Update() { // 示例按下F1键在日志中输出一条消息 if (Input.GetKeyDown(KeyCode.F1)) { Log.LogInfo(You pressed F1!); } } }代码解析与注意事项[BepInPlugin]属性这是插件的“身份证”包含了GUID全局唯一标识符建议使用反向域名格式防止冲突、显示名和版本号。BepInEx靠这个属性来识别和加载你的插件。继承BaseUnityPlugin这赋予了你的类Unity MonoBehaviour的生命周期方法Awake, Start, Update, OnGUI等并自动关联了日志器Logger。Awake()vsStart()Awake()在插件实例创建后立即调用用于初始化。Start()则在Awake()之后在插件实例第一次启用Enabled时调用。对于BepInEx插件通常只在Awake()中做初始化就够了。日志记录永远使用Logger.LogInfo/Warning/Error()来输出信息而不是Console.WriteLine()或Debug.Log()。前者会输出到BepInEx的专属日志文件和控制台是调试的黄金标准。操作游戏对象直接在Awake()中创建GameObject在某些游戏或时机下可能导致错误因为UI系统可能还未初始化。更健壮的做法是在Start()中创建或者监听游戏场景加载完成的事件。3.4 编译、部署与测试在Visual Studio中按CtrlShiftB编译项目。成功后在项目的bin/Debug或bin/Release目录下找到生成的MyFirstBepInExPlugin.dll文件。将你的MyFirstBepInExPlugin.dll文件复制到目标游戏的BepInEx/plugins/目录下。你可以创建一个子文件夹如BepInEx/plugins/MyFirstPlugin/方便管理。启动游戏。观察游戏根目录下的BepInEx/LogOutput.log文件可以用文本编辑器实时打开并监控尾部。你应该能看到类似这样的日志[Info :My First BepInEx Plugin] Plugin com.yourname.myfirstplugin is loaded! [Info :My First BepInEx Plugin] Hello World GameObject created.在游戏中按下F1键检查日志是否出现了You pressed F1!。如果一切正常恭喜你你的第一个BepInEx插件已经成功运行。4. 进阶开发配置、热重载与Harmony补丁一个只会打印日志的插件显然不够。接下来我们探索几个让插件变得实用和强大的核心功能。4.1 为插件添加可配置项让用户能自定义插件行为是优秀插件的基本素质。BepInEx内置了基于Tomlet库的配置系统使用起来非常直观。修改MyFirstPlugin.cs在Awake()方法之前添加配置绑定代码using BepInEx.Configuration; // ... 元数据定义 ... public class MyFirstPlugin : BaseUnityPlugin { // ... 常量定义和Log ... // 声明配置项 private ConfigEntrybool ConfigShowGreeting; private ConfigEntryKeyboardShortcut ConfigGreetingKey; private ConfigEntryfloat ConfigGreetingScale; private void Awake() { Log Logger; Log.LogInfo($Plugin {PluginGUID} is loaded!); // 1. 绑定配置项 // 参数配置分区可选配置项键名默认值配置描述 ConfigShowGreeting Config.Bind(General, // 分区名 ShowGreeting, // 键名 true, // 默认值 Whether to show the greeting text on screen.); // 描述 ConfigGreetingKey Config.Bind(General, GreetingHotkey, new KeyboardShortcut(KeyCode.F2), // 默认快捷键F2 Hotkey to toggle the greeting text.); ConfigGreetingScale Config.Bind(Appearance, GreetingScale, 1.0f, new ConfigDescription(Scale of the greeting text., new AcceptableValueRangefloat(0.5f, 3.0f))); // 定义可接受的值范围 // 2. 根据配置初始化 if (ConfigShowGreeting.Value) { CreateGreetingText(); } Log.LogInfo(Configuration loaded.); } private void Update() { // 检测配置的快捷键是否被按下 if (ConfigGreetingKey.Value.IsDown()) { ConfigShowGreeting.Value !ConfigShowGreeting.Value; // 切换布尔值 Config.Save(); // 重要将更改保存回配置文件 if (ConfigShowGreeting.Value) { CreateGreetingText(); Log.LogInfo(Greeting text enabled.); } else { DestroyGreetingText(); Log.LogInfo(Greeting text disabled.); } } } private GameObject greetingTextObj; private void CreateGreetingText() { if (greetingTextObj ! null) return; greetingTextObj new GameObject(GreetingText); var guiText greetingTextObj.AddComponentGUIText(); guiText.text Hello Configurable World!; guiText.transform.position new Vector3(0.1f, 0.9f, 0); guiText.fontSize Mathf.RoundToInt(20 * ConfigGreetingScale.Value); DontDestroyOnLoad(greetingTextObj); } private void DestroyGreetingText() { /* 销毁对象的代码 */ } }编译并部署插件后运行游戏。BepInEx会自动在BepInEx/config/目录下生成一个以你插件GUID命名的.cfg文件如com.yourname.myfirstplugin.cfg。用户可以直接用文本编辑器修改这个文件下次启动游戏时就会生效。更棒的是很多社区工具如BepInEx Configuration Manager插件能为此类配置文件生成图形化的设置界面。4.2 实现插件热重载Hot Reload热重载意味着你可以在不重启游戏的情况下重新加载修改后的插件代码极大提升开发效率。这需要借助BepInEx的Chainloader和文件监视功能。原理监听plugins目录下DLL文件的更改事件。当检测到变化时卸载旧插件从游戏内存中移除其所有类型和对象然后重新加载新的DLL。实现要点简化概念使用FileSystemWatcher监视你的插件DLL文件。当文件改变时调用Chainloader.PluginInfos[YourPluginGUID].Instance来获取当前插件实例并尝试将其GameObject设为无效或销毁。更复杂但更安全的方法是利用Assembly.LoadFile重新加载程序集然后使用反射创建新的插件实例。但这需要精心处理静态变量和事件订阅避免内存泄漏。注意事项热重载在开发简单插件时非常方便但对于已经创建了复杂游戏对象、注册了事件或持有非托管资源的插件实现完全无副作用的热重载非常困难。生产环境的插件通常不内置此功能而是作为开发者的独立工具使用。社区有现成的热重载插件如BepInEx.HotReload建议在熟悉基础后直接使用它们。4.3 使用Harmony进行游戏代码补丁这是BepInEx插件开发中最强大也最危险的部分。Harmony库允许你在运行时修改游戏原有方法的IL代码。你可以前置Prefix、后置Postfix或完全替换Transpiler一个方法。场景假设你想让某个游戏里的武器伤害永远翻倍。你找到了计算伤害的方法CalculateDamage。添加Harmony引用确保项目引用了0Harmony.dll。创建补丁类using HarmonyLib; [HarmonyPatch(typeof(Weapon))] // 指定要补丁的类 [HarmonyPatch(CalculateDamage)] // 指定要补丁的方法名 class WeaponDamagePatch { // Prefix补丁在原方法执行前运行 static bool Prefix(ref float __result, Weapon __instance) { // __instance 是原方法的thisWeapon实例 // 我们可以直接设置结果并返回false来跳过原方法 // 但更常见的是修改传入的参数或进行预处理 // 例如我们获取原方法的计算结果然后翻倍 // 这需要用到Postfix或者更复杂的Transpiler // 这里演示一个简单的Prefix直接返回翻倍后的固定值仅作演示逻辑不完整 // __result 100f; // 直接设置结果为100 // return false; // 跳过原方法执行 return true; // 继续执行原方法 } // Postfix补丁在原方法执行后运行 static void Postfix(ref float __result) { // __result 是原方法的返回值我们可以修改它 __result * 2.0f; // 伤害翻倍 Log.LogInfo($Damage calculated: {__result}); } }在插件Awake中应用补丁private void Awake() { Log Logger; var harmony new Harmony(PluginGUID); // 使用插件GUID创建Harmony实例 harmony.PatchAll(); // 自动搜索当前程序集中所有[HarmonyPatch]标签的类并应用补丁 Log.LogInfo($Harmony patches applied.); }重要警告兼容性噩梦Harmony补丁直接修改游戏代码。游戏更新后目标方法签名或内部逻辑可能改变导致补丁失效甚至游戏崩溃。务必做好错误处理并明确声明兼容的游戏版本。性能影响不当的补丁尤其是Transpiler可能引入性能开销。理解IL复杂的修改需要你能阅读和理解C#编译后的中间语言IL。社区工具如dnSpy或ILSpy可以帮助你反编译游戏代码进行分析。5. 调试、发布与社区规范5.1 高效调试插件代码打印日志Logging是最基本也是最重要的调试手段。但有时你需要更强大的工具。附加调试器这是最有效的调试方式。确保你的Visual Studio项目是Debug编译配置。启动游戏。在Visual Studio中点击菜单栏的“调试” - “附加到进程”。在进程列表中找到你的游戏进程例如valheim.exe选择它并确保“附加到”选择的是“托管(.NET Core/ .NET 5)”或“托管(.NET 4.x)”代码类型。点击“附加”。现在你可以在插件代码中设置断点当游戏执行到那里时就会暂停你可以查看所有变量值、调用堆栈进行单步调试。使用Debug.Log与游戏控制台一些游戏内置了开发者控制台通常按F5或~键打开。你可以使用UnityEngine.Debug.Log()将信息输出到那里。但注意BepInEx的Logger输出更可靠两者可以结合使用。实时监控与插件管理工具安装社区插件如BepInEx.ConfigurationManager提供图形化设置和插件列表和BepInEx.Console增强游戏内控制台可以方便地查看日志、管理插件、甚至执行简单C#命令。5.2 打包与发布插件一个专业的插件发布包不应该只是一个DLL文件。标准的插件发布包结构应包含MyAwesomePlugin-v1.0.0.zip │ ├── BepInEx/ │ └── plugins/ │ └── YourName/ (可选但推荐用于分类) │ └── MyAwesomePlugin/ │ ├── MyAwesomePlugin.dll (主程序集) │ ├── README.md (说明文档) │ ├── CHANGELOG.md (更新日志) │ └── manifest.json (元数据文件用于Mod管理器) │ └── icon.png (可选插件图标)README.md用Markdown编写必须包含插件名称、描述、安装方法、配置说明、快捷键、常见问题解答FAQ、源代码链接如GitHub、联系方式。CHANGELOG.md清晰列出每个版本的改动。manifest.json这是一个标准文件供Mod管理器如r2modman, Thunderstore识别你的插件。内容示例{ name: My Awesome Plugin, version_number: 1.0.0, website_url: https://github.com/yourname/MyAwesomePlugin, description: This plugin does awesome things!, dependencies: [ BepInEx-BepInExPack-5.4.2100 ], authors: [YourName] }5.3 避坑指南与最佳实践GUID冲突这是最常见的问题。确保你的插件GUID全球唯一。使用反向域名格式如com.github.yourname.modname能极大避免冲突。游戏版本锁定在插件描述和日志中明确声明支持的游戏版本。使用[BepInDependency]属性声明依赖的其他插件或特定BepInEx版本。优雅降级如果你的插件依赖游戏的某个特定方法而该方法在新版本中可能被移除或更改使用try-catch块或反射前先检查方法是否存在避免游戏直接崩溃。内存管理如果你创建了GameObject、订阅了事件如Application.quitting,SceneManager.sceneLoaded务必在插件被禁用或游戏退出时妥善清理在OnDestroy()方法中取消订阅、销毁对象。内存泄漏在长期运行的游戏中会逐渐累积导致问题。多线程安全Unity的API大部分不是线程安全的。如果你使用了多线程或异步任务如Task,async/await来执行耗时操作在需要操作Unity对象如GameObject, Transform时必须使用UnityMainThreadDispatcher社区有相关库将操作派发回主线程。尊重玩家与开发者不要开发破坏游戏平衡、影响其他玩家体验在多人游戏中或侵犯开发者权益的插件。明确你的插件是“辅助性”还是“修改性”并遵守目标游戏社区的模组政策。从在日志中看到第一行“Plugin loaded”的兴奋到成功用Harmony修改了游戏核心机制的巨大成就感BepInEx插件开发是一条充满挑战和乐趣的道路。它不仅仅是技术活更是对耐心、细心和创造力的考验。最宝贵的经验往往来自于解决那些日志里没有报错但功能就是不对劲的玄学问题。多读社区其他优秀插件的源代码多参与讨论你会发现这个生态充满了热情和分享精神。现在你已经掌握了从入门到精通的关键知识是时候打开你最喜欢的Unity游戏开始创造属于你自己的独特体验了。