如果你和我一样玩《英灵神殿》时折腾过MOD又或者翻遍了某个Unity游戏的模组论坛发现想实现的小功能根本没有现成成品那这篇BepInEx插件开发实战就是给你准备的。我会用Visual Studio 2022从零跑通一个能加载、能输出日志的Unity Mod同时把环境搭建、调试排查、进阶补丁这些环节里最容易卡住的地方一次说清。无论你是第一次接触Mod开发还是以前只改过配置文件只要会最基础的C#这篇内容都能让你在半小时内看到自己的插件被游戏加载。很多人以为写Unity Mod必须先精通Unity引擎其实不是。BepInEx作为目前最主流的Unity Mod加载框架把大部分脏活累活都包掉了。你要做的只是在Visual Studio里建一个C#类库写一个继承BaseUnityPlugin的类然后让BepInEx在游戏启动时把这个DLL捞起来执行。听起来很美好真正动手时却有一堆细节坑引用的DLL放哪、目标框架选哪个、为什么日志乱码、为什么插件加载了却没效果。这些东西才是“实战”二字的真正含金量。1. 动手前先搞清楚BepInEx、Unity Mod和Visual Studio到底各管哪一段1.1 BepInEx不是Mod是Mod的“插排”很多刚接触MOD圈的朋友会把“装BepInEx”和“装MOD”混为一谈。你去英灵神殿的社区逛一圈管理员常常说“先装前置”这个前置指的就是BepInEx。它本身不改变游戏内容只负责提供一个统一的插件加载环境。你可以把BepInEx理解成一个插排Mod是插在插排上的小家电。游戏启动时BepInEx会提前进入Unity运行时扫描BepInEx/plugins目录下的所有DLL找到带[BepInPlugin]特性的类并实例化然后调用对应的生命周期方法。这种设计最大的好处是Mod开发者和玩家都不需要直接改游戏主程序。Unity游戏的主程序在启动时会加载UnityEngine.dll等运行时程序集BepInEx利用Unity的Mono运行时注入机制在游戏准备阶段把自己的程序集也塞进去。这样一来Mod就可以访问到游戏内部的各种类型和对象同时又不会破坏原版文件。玩家不想玩Mod了删掉BepInEx文件夹就恢复原样非常干净。1.2 为什么2024年还在用BepInExMono运行时与加载机制的适配BepInEx也不是万能钥匙。它最初主要针对Unity的Mono运行时版本也就是Windows上绝大多数独立游戏默认采用的架构。判断标准非常简单打开游戏根目录如果能看到*_Data/Managed/Assembly-CSharp.dll这个文件那基本就是Mono运行时BepInEx可以直接用。如果只看到GameAssembly.dll游戏走的是IL2CPP架构传统的BepInEx插件就别想了得用BepInEx的IL2CPP变体或者其他专门适配IL2CPP的方案。2024年写Unity Mod选择BepInEx 6仍然是主流。它支持较新的Unity版本插件项目也统一到了.NET Framework 4.7.2。这个选择不是拍脑袋定的BepInEx在加载阶段会把自己的运行时托管给Unity的Mono环境使用.NET Framework才能保证类型加载不出幺蛾子。用更高版本的.NET会引发访问权限或类型不一致的问题新手经常在这个地方踩坑后面我会详细说。1.3 你的第一个Mod本质上是个C#类库理解了BepInEx的角色再看Visual Studio就顺了。你不需要开发完整游戏不需要写Unity场景也不需要做素材。你要做的是创建一个“类库”项目平时我们叫它DLL。这个DLL里有一个类继承了BaseUnityPlugin并且标注了插件信息。BepInEx启动时会按类库的引用关系把所有依赖一起加载然后执行你的代码。Visual Studio在这里承担三个职责写代码、编译DLL、调试日志。有人问能不能用记事本加命令行csc编译能但那个体验太折磨了。VS提供了一套完整的IntelliSense和断点调试尤其是断点调试配合BepInEx的运行时日志可以让你看到游戏里每一帧发生了什么。所以我的建议很直接正常安装Visual Studio 2022 Community版本把“.NET 桌面开发”工作负载勾上就足够用了。2. 环境搭建从游戏目录到VS2022的每一步都不能错2.1 安装Visual Studio 2022时最容易漏掉的“工作负载”Visual Studio 2022本身是个巨无霸但新手常常只安装默认组件等建项目时发现找不到“类库(.NET Framework)”模板然后又去网上搜一堆加装教程。其实只要在安装器里勾选“ASP.NET 和 Web 开发”底下的“.NET Framework 4.7.2 开发工具”或者直接勾选“.NET 桌面开发”工作负载就能获得创建.NET Framework类库的能力。你也许会问为什么需要4.7.2而不是4.8BepInEx 6核心程序集编译时基于.NET Framework 4.7.2如果你的插件目标框架更高运行时加载阶段很可能触发“无法加载文件或程序集”的异常。反过来目标框架低了引用某些C#新特性又会报编译错误。为了不给自己找麻烦直接在项目属性里把目标框架设置为.NET Framework 4.7.2。安装完成之后打开VS选择“创建新项目”搜索“类库”在模板列表里挑那个写着“.NET Framework”的版本而不是“类库(C#)”所对应的.NET Core/.NET 5模板。这两个名字很像新手容易选错。一旦选成.NET 6或.NET 8最后生成的DLL引用了一堆不兼容的程序集BepInEx加载时直接静默忽略连日志都不给你提示。2.2 下载并解压BepInEx 6到游戏目录BepInEx的发布页面在GitHub上文件名一般长这样BepInEx_win_x64_6.0.0-pre.1.zip。下载前先看一眼游戏本身是32位还是64位。2024年的Unity游戏大部分是64位但一些老游戏或独立游戏可能是32位需要找win_x86的包。版本选6.x没错不要用5.x去套新游戏很多新模板和API都以6.x为主网上教程也普遍基于6.x。解压时要注意不是把压缩包解压后把文件夹放到游戏目录而是要把压缩包里的BepInEx文件夹、doorstop_config.ini、winhttp.dll这些文件直接释放到游戏exe所在的根目录。比如SteamLibrary/steamapps/common/Valheim/下面。winhttp.dll是BepInEx用来伪装成系统库实现预加载的关键文件如果把它的层级搞错了游戏启动时根本没反应。首次运行游戏BepInEx会完成初始化自动生成BepInEx/config目录和BepInEx/LogOutput.log。这一步很重要因为后面的插件都要放进BepInEx/plugins目录。如果没有这个目录自己新建也可以但最好让游戏先跑一次把配置文件和目录结构自动生成出来避免权限或路径问题。2.3 确认游戏是Mono版本而不是IL2CPP版本我见过不少人在某款游戏上装BepInEx折腾一晚上发现游戏进程都进不去最后才知道那个游戏是IL2CPP架构。这个检查一定要在搭建环境之前做。打开游戏根目录找到类似GameName_Data的文件夹进去看Managed目录。如果看到Assembly-CSharp.dll恭喜这是Mono运行时BepInEx可以直接注入。如果Managed里几乎没有Assembly-CSharp.dll游戏根目录反而躺着一个体积很大的GameAssembly.dll那就是IL2CPP架构。IL2CPP会把C#代码转成C再编译成原生代码托管侧留给Mod的入口非常有限所以传统的BepInEx插件方案不适用。有些游戏虽然主程序是IL2CPP但也会附带GameAssembly.dll以加速启动这并不代表不能做Mod只是要用BepInEx的IL2CPP分支或者配合Cpp2IL等工具链。复杂度高不少不适合第一篇实战内容。我的建议是第一次练手找一款确认是Mono架构的Unity游戏比如《英灵神殿》《腐蚀》或者一些国产Unity独立游戏把整个流程跑通后再考虑那些硬骨头。3. 第一个插件让游戏启动时在日志里跟你打个招呼3.1 新建类库项目时的框架选择打开Visual Studio 2022新建一个C#类库项目目标框架选择.NET Framework 4.7.2。项目名字可以叫MyFirstMod名称空间的根命名最好别用“Mod”因为后续编译出的DLL文件名会变成MyFirstMod.dll放进plugins目录后一眼就能认出来。项目创建后解决方案资源管理器里会看到一个默认的Class1.cs我习惯直接删掉或者重命名为Plugin.cs。这个文件就是插件的入口不需要Program.cs也不需要Main函数。BepInEx通过特性扫描来定位插件实例而不是按照固定方法名去找Main。类库项目里没有Main这点和普通控制台程序完全不同。3.2 添加BepInEx.Core引用注意Copy Local设为False写插件代码前必须让项目能识别BepInEx命名空间。右键“引用”选“添加引用”再点“浏览”去游戏根目录下的BepInEx/core文件夹里找BepInEx.Core.dll。如果你用的是BepInEx 6这个文件基本都在core子目录下如果看到的是BepInEx.dll也可以引用命名不同而已类型是一样的。这里有一个极其关键的设置选中刚添加的引用在属性面板里把“复制本地”改为False。如果不改编译时会把BepInEx.Core.dll一股脑复制到你的输出目录到时候你顺手把整个输出文件夹丢进pluginsBepInEx在加载插件的同时发现这个目录下还有一份核心DLL轻则版本冲突重则直接崩溃。保留为False输出的只有你的插件DLL干净利落。同样的道理如果你以后要写Harmony补丁需要引用0Harmony.dll这个DLL也在core目录下同样把“复制本地”改成False。3.3 用BepInPlugin特性标记插件元信息现在打开Plugin.cs写一段最基础的代码using BepInEx; namespace MyFirstMod { [BepInPlugin(com.example.myfirstmod, My First Mod, 1.0.0)] public class Plugin : BaseUnityPlugin { private void Awake() { Logger.LogInfo(My First Mod loaded successfully!); } } }[BepInPlugin]有三个参数GUID、名称、版本号。GUID是插件的唯一标识BepInEx用它来判断哪些插件重复也用它写配置文件的存放路径。GUID最好带上你的域名前缀比如com.example这样不容易和其他开发者撞车。名称会显示在日志或者某些Mod管理工具里可以写得友好一点。版本号用1.0.0这种标准语义化格式后续每次发布新版本都要记得递增。Logger是BaseUnityPlugin自带的日志对象。在插件里不要用Console.WriteLineUnity游戏通常没有控制台即使有输出也不会重定向到BepInEx的日志界面。Logger.LogInfo会走BepInEx的日志管道统一输出到调试窗口和LogOutput.log后续排查全靠它。3.4 编译输出与部署到plugins目录写完代码后按F6编译。如果没有报错去项目目录下的bin/Debug或bin/Release里找到MyFirstMod.dll。把DLL复制到游戏根目录BepInEx/plugins下。如果plugins目录不存在手动新建一个。然后正常启动游戏。如果一切顺利游戏启动过程中你应该会看到BepInEx的调试窗口或者打开BepInEx/LogOutput.log里面有一行类似[Info : MyFirstMod] My First Mod loaded successfully!的记录。看到这行日志就意味着你的第一个Unity Mod已经被游戏加载了。这行日志本身没什么功能但它证明了整个链路是通的。接下来所有复杂的补丁、配置界面、游戏内UI修改都建立在这个链路之上。4. 没有加载成功按这条链路排查日志和乱码4.1 第一次运行的预期结果与日志位置新手跑通流程后最常见的反应是“我明明没看到什么变化”。这太正常了因为你只是让插件打了句日志没改任何游戏内容。但如果你连日志都没有看到那就要排查了。BepInEx的日志有两个去处。一是启动时弹出的黑色调试窗口按F8可以打开完整控制台二是BepInEx/LogOutput.log文件。我强烈建议第一次测试以文件为主因为控制台窗口的编码问题可能会让你看到一堆乱码而日志文件本身是UTF-8内容通常是可读的。如果LogOutput.log里连“Loading plugins”这种信息都没有说明BepInEx根本没进入加载流程先检查winhttp.dll是否在游戏根目录。如果能看到BepInEx加载日志但没有你的插件DLL名称大概率是插件没有被识别去确认DLL是否在plugins根目录下而不是放在子文件夹里。BepInEx默认只扫描plugins目录第一层的DLL子文件夹要额外配置。4.2 常见加载失败原因对照表把这两年常遇到的加载问题整理成一张表方便你对着排查症状可能原因处理方式游戏启动时没有BepInEx窗口winhttp.dll缺失或层级别错重新解压BepInEx到游戏exe同级目录日志里有BepInEx信息但没有插件DLL名称插件没放到plugins根目录移动到BepInEx/plugins/xxx.dll日志报“Could not load file or assembly”项目目标框架不对或缺少引用检查目标框架是否为.NET Framework 4.7.2检查引用路径插件DLL存在但没有任何日志缺少[BepInPlugin]特性父类继承错误确认类继承BaseUnityPlugin控制台中文全部变成乱码Windows控制台代码页与UTF-8冲突看LogOutput.log或修改系统区域设置4.3 控制台中文乱码的三种解法“bepinex乱码”是社区里高频搜索词我当初也卡过。BepInEx控制台输出的内容默认按UTF-8编码但Windows命令行窗口默认使用GBK或系统代码页所以中文日志变成一堆问号或菱形。这个问题不解决读日志会非常痛苦。第一种办法最简单直接不看控制台看BepInEx/LogOutput.log用VS Code或Notepad打开选择UTF-8编码乱码立即消失。第二种办法是启动游戏前在系统“区域设置”里勾选“Beta版使用Unicode UTF-8提供全球语言支持”然后重启控制台就能正常显示中文。但这个办法会影响整个系统有些老软件可能因此乱码不建议推荐给普通玩家。第三种办法是修改BepInEx的配置文件在BepInEx/config里找到BepInEx.cfg把Logging.Console下的LogConsoleEncoding改成对应代码页但不同版本配置项不太一样最稳妥的还是直接用日志文件。我的实际习惯是从第一天起就用英文写日志内容。不是崇洋媚外而是跨平台和编码兼容性最好。调试信息一般也就自己看英文日志配合LogOutput.log几乎不会再被乱码困扰。如果你一定要输出中文也不要输出到控制台写进配置文件或UI里。5. 从Hello World到真ModHarmony补丁、配置项和反编译知识5.1 为什么游戏方法改不动可以直接引用游戏程序集吗日志插件跑通后下一个问题是“怎么改游戏”。比如说我想让角色最大生命值提升50%直观想法是引用Assembly-CSharp.dll然后在插件里调用游戏的类型。但真的这么干你会发现两个问题一是游戏程序集很大直接引用会把整个依赖图拉进来稍不注意就版本冲突二是游戏更新后程序集里的类名、方法名经常变你的插件也会跟着碎掉。更常用的做法是使用Harmony补丁库。Harmony不是BepInEx的一部分但它和BepInEx是黄金搭档。它通过动态修改方法指令在游戏方法执行前或执行后“插入”你的代码。这个过程不需要改动游戏原文件也不要求你在编译时引用游戏程序集因为Harmony是通过字符串或类型名在运行时解析的解耦效果非常好。要用Harmony先在项目里引用0Harmony.dll然后安装一个Harmony实例using HarmonyLib; private void Awake() { var harmony new Harmony(com.example.myfirstmod); harmony.PatchAll(); }PatchAll会自动扫描当前程序集里所有带[HarmonyPatch]特性的类并完成补丁安装。这个设计非常方便你只需要写补丁类不需要手动管理生命周期。5.2 Harmony Patch的基本套路从给角色加BUFF的伪代码说起下面是一个经典的Harmony补丁示例假设游戏里Player类的GetMaxHealth方法返回浮点数我想让结果变为1.5倍using HarmonyLib; [HarmonyPatch(typeof(Player), nameof(Player.GetMaxHealth))] internal static class PlayerMaxHealthPatch { [HarmonyPostfix] static void MultiplyMaxHealth(ref float __result) { __result * 1.5f; } }这里的typeof(Player)引用游戏类型需要你项目里已经引用了Assembly-CSharp.dll。如果你不想引用可以使用AccessTools按名字解析。[HarmonyPostfix]表示在原始方法执行完之后运行ref float __result是Harmony注入的一个特殊参数专门用来修改返回值。Harmony还有Prefix前缀补丁在原始方法运行前执行可以跳过原方法也有Transpiler直接修改方法的IL指令用来处理一些返回值无法满足的改动。对新手来说先掌握Postfix和Prefix就够了。修改数值、增加掉落、跳过动画这些常见的Mod需求都能覆盖。要注意补丁类最好设为internal避免命名空间污染。补丁的GUID不要和插件GUID混用最好单独写一个字符串常量。5.3 让玩家可配置使用ConfigEntry绑定BepInEx配置文件很多Mod不是写给自己玩的发布出去之后别人总想调整参数。如果每次都要改代码重新编译玩家体验就很差。BepInEx自带一套轻量配置系统你可以在插件里声明配置项玩家修改BepInEx/config目录下生成的配置文件即可。示例private ConfigEntryfloat healthMultiplier; private void Awake() { healthMultiplier Config.Bind(Gameplay, HealthMultiplier, 1.5f, Max health multiplier.); var harmony new Harmony(com.example.myfirstmod); harmony.PatchAll(); }然后在补丁方法里读取配置值。注意配置项的读取最好缓存到一个静态字段里因为Harmony补丁在游戏热更新时可能会频繁调用每次读取配置会产生性能开销。我的习惯是在Awake里赋值一次后续如果玩家改了配置通过BepInEx的SettingChanged事件动态更新。配置文件的读写由BepInEx自动完成插件第一次加载时会生成默认值玩家用记事本打开就能改不需要任何额外UI。这对命令行习惯不友好的玩家也足够简单了。5.4 反编译是Mod开发者的必修课GameAssembly.dll的正确认知很多新手问“我要怎么知道游戏内部有哪些方法”答案不是猜而是反编译。Mono运行时的游戏核心逻辑在Assembly-CSharp.dll里用dnSpy或ILSpy打开这个文件就能看到几乎所有游戏类的字段、方法和事件。你可以把dnSpy当成一个加强版的VS对象浏览器直接搜索Player、GetMaxHealth等方法。这里要澄清一个常见误会网上搜“GameAssembly.dll的作用”得到的答案是IL2CPP游戏的核心文件里面是原生代码不包含可直接阅读的托管元数据。但如果你的游戏是Mono架构真正需要关注的是*_Data/Managed/Assembly-CSharp.dll而不是根目录的GameAssembly.dll。有些教程把两者混在一起导致新手打开GameAssembly.dll后什么都看不懂。反编译仅仅用于学习不要直接照抄商业游戏的代码并发布更不要涉及任何加密绕过功能。Mod开发应当尊重游戏创作者和玩家社区的共识只做合理的扩展不碰利益相关的作弊或者反作弊绕过。6. 自己写完Mod后我踩过的发布与兼容性坑6.1 插件发布的目录整理插件开发完成后下一步是发布给其他人用。不要把整个VS项目打包给玩家你要交付的只有一个DLL最多加一个说明文件。把编译配置从Debug切换到Release再次编译生成的DLL体积更小、性能也更好。然后把DLL压缩成一个zip压缩包内不要套一层文件夹直接让玩家解压后能看到DLL再附上一段话先安装BepInEx再把DLL放到BepInEx/plugins。我自己第一次发布时图省事把整个bin/Debug文件夹压缩了结果里面塞了很多重复引用的副本玩家解压后插件加载失败还找不出原因。后来才明白发布前要检查输出目录除了插件DLL其他文件都别带。因为BepInEx会自动从core目录补充依赖你的输出目录里如果有版本不一致的BepInEx.Core.dll就是一颗定时炸弹。6.2 避免与其它Mod冲突的命名空间和ID规范多人联机游戏里每个玩家装的Mod可能不同你的插件GUID如果取得太随意比如叫MyFirstMod很容易和其他人撞车。一旦撞车BepInEx会拒绝加载后出现的插件症状同样是“插件没生效”。所以GUID一定要使用域名反转规则没有域名就用com.github.你的用户名.项目名。补丁类尽量起一个不常用的内部类名避免多Mod时出现成员签名冲突。Harmony补丁是另一个冲突重灾区。如果你Patch了同一个游戏方法另一个Mod也Patch了同一个方法顺序不同可能导致结果不同。比如某个Mod把生命值改为1.5倍你的Mod改为2倍后执行的补丁会覆盖前一个的结果。我见过最头疼的问题是两个Mod用同一种方式修改同一返回值其中一个让游戏直接崩溃。这种情况下要么避免修改核心方法要么在文档里明确告知玩家“与某类Mod不兼容”。6.3 我在实际开发中的几点体会写完第二个Mod之后我养成了一个习惯每次启动游戏不是直接扔到后台而是盯着BepInEx控制台和LogOutput.log看前30秒。很多加载期异常只出现一次如果错过了下次复现可能要看运气。另外尽量把日志写得详细一点。在Awake里打印插件版本在Harmony补丁安装完成后打印一句“installed”在配置读取后打印实际生效的参数。这些日志在你自己开发时是噪音但等玩家反馈“加载了但没效果”时它们就是救命线索。让玩家把LogOutput.log发给你你可以直接定位是补丁没装上还是配置被改成了极端值。最后说一个和工具链相关的点我见过有人把BepInEx的core DLL和插件DLL都丢进同一文件夹然后让VS自动引用“输出目录里的DLL”结果某次游戏更新后DLL多了个版本后缀整个项目编译不过。所以我的建议是引用要指向游戏目录里的原始BepInEx文件不要指向项目输出目录每次游戏更新后确认BepInEx是否同步升级再重新编译你的插件。这个习惯能帮你省去大量“昨天还能用今天就不行了”的排查时间。从搭环境到发布BepInEx插件开发这条路并不陡但它确实有一些“只可意会”的细节。希望这篇内容能让你少走点弯路也祝你在写出第一个Hello World之后能把这个能力用在自己真正喜欢的游戏上。