BepInEx Unity游戏Mod开发实战：从环境搭建到Harmony补丁-代码聚汇网

BepInEx Unity游戏Mod开发实战：从环境搭建到Harmony补丁

郑哲东·2026-08-29·阅读 23 GEO检测（免费）

BepInExUnityMod开发

|难度：普通|阅读约 35 分钟

做Unity游戏mod这事，BepInEx算是绕不开的一个名字。无论你是想在存档里给自己塞点装备、给角色换个模型，还是想彻底搞清楚游戏内部到底怎么运作的，BepInEx都能给你一个相对干净、稳定、可控的入口。这篇文章是我从零开始用BepInEx开发Unity游戏mod的完整记录，包括框架选型、环境搭建、第一个插件从编译到运行的整个过程，以及我在实际项目里踩过的几个坑。适合刚接触mod开发的新手，也适合那些已经写过几个小mod、但想系统理解BepInEx工作原理的同学。

1. 选型：Unity modding的几把钥匙，为什么我最终锁定了BepInEx

Unity游戏的mod方式其实不止一条路。官方创意工坊是首选，但不是每个游戏都给你开这个口子，很多单机游戏、独立游戏压根没有官方mod支持。这种情况下，社区里最常见的方案无非三种：BepInEx、MelonLoader，以及绕开框架直接用Harmony手写注入。我个人的经验是，这三种我都试过，BepInEx是目前综合体验最好的选择，但不是唯一选择，选型前需要先搞清楚它们各自的边界。

1.1 主流mod框架横向对比

MelonLoader和BepInEx在功能上有大量重叠，两者都能做到注入游戏进程、加载插件、调用游戏内部方法。但设计理念差异很大。BepInEx定位是“轻量核心+插件生态”，框架本身不掺和太多游戏逻辑，每个插件都是独立的DLL，互不干扰，出问题也好排查。MelonLoader更偏向“开箱即用”，内置了一套Mod偏好设置、Il2Cpp支持和一些常用工具，对新手更友好，但遇到游戏版本更新时，它的维护压力往往更大，兼容性翻车的情况我遇到过不止一次。

再说裸Harmony方案。直接引用0Harmony.dll，手动写补丁、手动组装加载器，这种玩法适合那些想彻底掌控一切的极客。问题在于，一旦游戏里装了多个mod，你就得自己处理程序集加载顺序、依赖冲突、命名空间隔离，这些本来BepInEx已经帮你解决好的问题，裸写全要自己做。我写过一次之后就再也不想了：为了调一个DLL加载顺序，耗时比写核心功能还长。

所以我的结论很简单：如果目标是长期维护、频繁加功能、多个mod共存，闭眼选BepInEx。它不花哨，但稳，社区资料多，遇到问题基本搜得到。

1.2 BepInEx的核心工作方式：从Mono到IL2CPP

要真正理解BepInEx，得先理解Unity游戏的两种脚本后端：Mono和IL2CPP。

Mono时代，游戏的C#代码编译成.NET程序集，直接以DLL文件的形式躺在游戏目录的Managed文件夹里。这种模式的优点是对mod开发者极其友好：你可以直接用dnSpy反编译这些DLL，看到所有类名、方法名、字段名，甚至直接引用它们写代码。缺点是太透明了，游戏厂商没法保护任何逻辑。

IL2CPP是Unity为了性能和代码保护推出的方案。C#代码在发布时会被转换成C++，再编译成原生二进制，游戏目录里不再有可以直接反编译的.NET程序集。很多人以为IL2CPP游戏没法做mod了，但mod社区很早就找到了对策——Il2CppDumper可以从global-metadata.dat文件中提取出类、方法、字段的元数据，虽然不能还原成完整的C#源码，但足够让BepInEx通过Il2Cpp Interop机制生成互操作程序集，让你在mod里像调用Mono程序集一样调用游戏内部方法。

理解这一点后，BepInEx的工作机制就清楚了。它本质上干了三件事：通过doorstop注入器把winhttp.dll注入到游戏进程；在进程内建立插件加载环境，扫描BepInEx/plugins目录加载所有mod插件；通过Harmony补丁系统把mod代码插入到游戏逻辑的执行流程里。这三层玩明白了，后面写mod就是水到渠成的事。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备：一次装对工具链，后面能省十个小时

环境准备是整个过程中最容易被轻视、也最容易出错的一步。很多人下载了BepInEx安装包直接往游戏目录一扔，结果游戏崩了、日志空白、插件不加载，全是因为细节没处理到位。我把一套比较稳的流程拆开讲。

2.1 BepInEx版本怎么选：5系与6系的差别，Mono和IL2CPP怎么判断

BepInEx目前有5系和6系两条主线。5系是老牌稳定版本，分x64和x86两种架构，你要先确认游戏的运行架构，绝大多数Steam游戏都是64位，下载时选x64就对了。6系是当前的主力开发版本，它在架构上做了整合，不再区分Mono和Il2Cpp两个安装包，统一入口，插件API也做了调整，新项目建议直接上6系。

还有一个小原则：如果游戏比较老，比如Unity 2017、2018时代的作品，可能有些老插件只支持BepInEx 5，这时候别固执，老游戏用老框架、新游戏用新框架，是最省力的做法。

怎么判断游戏是Mono还是IL2CPP？一个土办法是看游戏目录：找到GameName_Data文件夹，如果里面有Managed文件夹且包含一堆dll，大概率是Mono；如果看到Native文件夹或者libil2cpp相关文件，那就是IL2CPP。更准确的判断方式：装好BepInEx后启动游戏，看LogOutput.log，启动日志里会明确打印脚本后端类型。

2.2 把BepInEx塞进游戏目录，以及怎么判断注入成功

BepInEx安装包的目录结构是这样的：

code复制BepInEx/
  config/
  core/
  plugins/
  ...
doorstop_config.ini
winhttp.dll

核心就两个关键文件：winhttp.dll负责注入，doorstop_config.ini负责告诉游戏进程该加载什么。把整个BepInEx文件夹连同winhttp.dll、doorstop_config.ini一起复制到游戏根目录，不要自作聪明只复制BepInEx文件夹，那样注入器找不到入口文件，必挂。

复制完成后，第一次启动游戏非常重要。BepInEx会在首次运行时自动生成BepInEx/config、BepInEx/plugins等目录，并创建一个LogOutput.log日志文件。如果这些目录是启动前就有的也没关系，关键是以玩家身份运行一次游戏，让BepInEx完成初始化。

怎么确认注入成功？看游戏目录下的BepInEx/LogOutput.log，打开后应该能看到类似这样的内容：

code复制[Info   : BepInEx] BepInEx 6.0.0-pre.1 - 6.0.0
[Info   : BepInEx] Running under Unity 2021.3.16f1
[Info   : BepInEx] CLR language: IL2CPP
[Info   : BepInEx] Loading plugins from BepInEx\plugins

有这些内容说明注入成功了。如果日志文件是空的，或者只有启动信息没有插件加在信息，优先检查winhttp.dll是否还在根目录、杀毒软件有没有静默拦截。Windows Defender偶尔会把winhttp.dll当恶意软件处理，这在BepInEx用户里很常见，需要把游戏目录加入白名单。

2.3 配套工具：dnSpy、Il2CppDumper、AssetStudio各有什么用

做mod不只是写代码，前置分析阶段往往会花掉一半时间。以下是三个我常用的工具：

dnSpy：Mono游戏的最强反编译工具。它不仅能看代码，还能直接改程序集、断点调试。我一般用它在游戏程序集里搜索关键词，比如要找伤害逻辑就搜“Damage”、“TakeDamage”、“Health”，几秒钟就能定位到相关类和方法的签名。

Il2CppDumper：处理IL2CPP游戏的必备工具。它需要两个输入：游戏目录里的GameAssembly.dll 和 global-metadata.dat，输出一堆.cs文件，虽然不是完整源码，但类结构、方法名、字段名都很清晰，足够用来写Harmony补丁了。

AssetStudio：查看游戏资源的神器，贴图、字体、模型、动画都能预览。有时候你想给游戏加个装备、换张贴图，第一步往往就是用AssetStudio找资源路径和名称。

这三个工具配合BepInEx使用，基本能覆盖90%的Unity游戏mod开发场景。分析阶段多花点时间把游戏结构搞清楚，写代码的时候会顺畅很多。

3. 第一个mod的完整开发流程：从零到游戏里弹出一行字

环境准备做好后，就可以开始写第一个mod了。这里我以BepInEx 6 + IL2CPP游戏为例，但Mono游戏流程几乎一样，差异只在引用程序集的方式上。

3.1 新建插件项目与必需依赖

我用Visual Studio 2022，新建一个.NET Framework 4.7.2类库项目（BepInEx 6也可以选.NET 6，但4.7.2兼容性最稳）。项目建好后，需要在引用里加上几个关键DLL：

BepInEx.Core.dll：提供BaseUnityPlugin基类、日志、配置系统
0Harmony.dll：Harmony补丁的核心库
BepInEx.Harmony.dll：BepInEx对Harmony的封装层

这几个dll在你下载的BepInEx包里的BepInEx/core目录可以找到。另外还需要引用游戏程序集：Mono游戏直接引用GameName_Data/Managed/Assembly-CSharp.dll；IL2CPP游戏需要先用BepInEx的Il2Cpp Interop生成互操作程序集，或者在首次运行插件后让BepInEx自动生成，然后引用生成出来的Interop.Assembly-CSharp.dll。

这里有个坑：直接引用游戏程序集时，Copy Local属性一定要设为false，不然编译输出目录会带着游戏DLL，可能导致加载冲突。我一开始没注意这个，结果mod一运行就报程序集加载错误，排查了半天。

3.2 插件主类：BepInPlugin、Awake与Start的时机区别

先看一个最小可运行插件：

csharp复制using BepInEx;
using BepInEx.Logging;

namespace MyFirstMod
{
    [BepInPlugin("com.example.mymod", "My First Mod", "1.0.0")]
    public class MyModPlugin : BaseUnityPlugin
    {
        private void Awake()
        {
            Logger.LogInfo("Hello from My First Mod!");
        }
    }
}

这里有几个关键点。**[BepInPlugin]**特性是必须的，它声明了插件的GUID、名称和版本。GUID建议用反向域名风格，避免和其他mod冲突。**Awake()**方法会在插件加载时执行一次，适合做初始化、加载配置、注册Harmony补丁。因为BaseUnityPlugin继承自MonoBehaviour，所以Awake、OnEnable、Start、Update这些Unity生命周期方法都能用。

Awake和Start的区别需要注意：Awake在插件实例创建时立刻执行，Start在Unity下一帧调用，如果你需要确保其他组件已经初始化，放在Start更稳。但大部分mod初始化逻辑放Awake就够了，问题不大。

编译这个项目后，把生成的DLL放到游戏目录的BepInEx/plugins文件夹下，启动游戏，看LogOutput.log，如果出现“Hello from My First Mod!”，恭喜，你已经有自己的第一个mod了。

3.3 Harmony补丁的三种姿势：Prefix、Postfix、Transpiler

只打印日志显然不够过瘾，mod的灵魂在于“改”。Harmony补丁就是改游戏逻辑的利器。它支持三种主要补丁类型：

Prefix：在目标方法执行前运行。你可以修改传入参数，也可以返回false跳过原方法。适合做“事件前拦截”，比如把伤害清零、把掉落概率改成100%。

Postfix：在目标方法执行后运行。可以拿到目标方法的返回值，甚至修改返回值。适合做“事件后处理”，比如偷看敌人血量、在玩家死亡后触发额外逻辑。

Transpiler：直接修改目标方法的IL指令。最底层、最强大，也最容易出错，一般用在游戏方法逻辑过于复杂、前缀后缀都处理不了的场景。比如你想在方法中间插入一段逻辑，只用Prefix和Postfix做不到，就得考虑Transpiler。

举个实际例子，把玩家受到的伤害固定改成1点：

csharp复制using HarmonyLib;

[HarmonyPatch(typeof(PlayerHealth), "TakeDamage")]
public static class Patch_TakeDamage
{
    static void Prefix(ref int damage)
    {
        damage = 1;
    }
}

然后在Awake里注册这个补丁：

csharp复制private void Awake()
{
    var harmony = new Harmony("com.example.mymod");
    harmony.PatchAll();
}

PatchAll()会扫描当前程序集里所有带HarmonyPatch特性的类，自动注册，非常方便。Harmony补丁类建议用static类，字段也用static，性能更好、生命周期更清晰。

还有一个容易忽略的点：Harmony补丁方法命名必须是Prefix、Postfix或Transpiler，大小写要准确，Harmony是通过方法名来识别的。如果你定义了一个叫PreFix的方法，它不会被识别。

3.4 调试与日志：LogSource的正确打开方式

日志是mod开发最重要的调试手段，我在实际开发中大部分时间都在跟日志较劲。

BepInEx的Logger支持多个LogSource，最常用的是LogInfo、LogDebug、LogWarning、LogError。区分使用场景：常规信息用LogInfo，调试阶段用LogDebug，可恢复的问题用LogWarning，一出现就会导致功能异常的问题用LogError。日志级别可以在BepInEx配置里调整，开发时把AllLogs设为true，发布前改回默认，避免刷屏。

日志显示在LogOutput.log，开发时建议把ConsoleEnabled设为true，这样你能在游戏启动时看到一个独立的控制台窗口，实时看日志输出，不用反复切出游戏翻文件。

断点调试方面，BepInEx 6支持附加调试器。把mod项目编译成Debug版，启动游戏，用Visual Studio的“附加到进程”选中游戏进程，然后在mod代码里打断点，实测可用。不过IL2CPP游戏断点偶尔会不准确，毕竟是原生代码互操作，不用太纠结，日志才是主力。

4. 配置系统、跨mod通信和UI扩展

mod写多了之后你会发现，硬编码参数是个很蠢的玩法。BepInEx内置配置系统能让你在不动代码的情况下调整mod参数，这个功能一定要用起来。

4.1 ConfigEntry：给你的mod加上一个可调节的旋钮

BepInEx配置系统的使用非常简单，在Awake里用Config.Bind声明配置项：

csharp复制using BepInEx.Configuration;

public class MyModPlugin : BaseUnityPlugin
{
    public static ConfigEntry<int> MaxHealth;
    public static ConfigEntry<float> DropRate;

    private void Awake()
    {
        MaxHealth = Config.Bind("General", "MaxHealth", 100, "玩家最大生命值");
        DropRate = Config.Bind("General", "DropRate", 0.5f, "掉落率倍率");
    }
}

第一次运行mod后，BepInEx/config目录下会生成一个以插件GUID命名的cfg文件，打开就能看到：

code复制[General]
## 玩家最大生命值
MaxHealth = 100

## 掉落率倍率
DropRate = 0.5

玩家可以直接改这个文件调整参数，改完重启游戏生效。如果你想做得更精致，可以再写一个配置热重载管理器，用Harmony监听配置文件变化事件，在游戏中实时应用配置，不用重启。这个高级功能我后面会单独写一篇，这里先提个方向。

配置项的命名尽量用驼峰式，方便阅读。类型支持int、float、bool、string、枚举等，足够覆盖绝大多数场景了。

4.2 事件订阅：镜像游戏内机制（以拾取、伤害为例）

mod经常需要“偷听”游戏内部事件。比如我想在玩家拾取物品时刷一条提示，或者在玩家受到致命伤害时触发保命机制。这类需求最常见的实现方式是在游戏内部方法上打Harmony Postfix后置补丁。

以拾取物品为例，假设游戏里有个ItemPicker类的Pickup方法：

csharp复制[HarmonyPatch(typeof(ItemPicker), "Pickup")]
public static class Patch_ItemPickup
{
    static void Postfix(ItemPicker __instance, Item item)
    {
        // __instance是目标方法的实例引用，可以直接访问它的字段
        var itemName = item?.Name ?? "unknown";
        ManualLogSource.Log.LogInfo($"玩家拾取了: {itemName}");
    }
}

这里有个关键知识点：Harmony会自动给Postfix方法注入名为__instance的参数（前后各两个下划线），它代表目标方法所属的实例。这个参数不需要你主动声明在补丁方法里，Harmony会根据参数名自动识别。同理，可以通过__result拿到方法返回值，通过方法签名里的同名参数拿到原始参数。这些约定写法是Harmony的一大特色，用熟了之后特别顺手。

4.3 跨mod通信和兼容性设计

多个mod一起用的时候，通信和兼容性就成了避不开的话题。BepInEx本身不提供特别完善的跨mod通信框架，但有几个实用手段：

一是通过Harmony的PatchAll注释创建静态类作为“总线”。这个静态类可以放一些全局字典或事件，其他mod通过反射读取。简单粗暴，但维护性差。

二是用BepInEx的Features机制。BepInEx 6提供了MonoMod和Features API，插件可以注册自定义Feature，其他插件通过依赖注入获取。这个方案更正规，但学习曲线陡峭一些。

更常见的做法是直接用Harmony补丁游戏事件作为通信点。比如A mod修改了玩家金币数，B mod想监听金币变化，A mod不需要主动通知B，B只需在金币变化的游戏方法上打Postfix，就能模拟事件订阅。这种“镜像游戏内部机制”的思路，比搞一套独立事件系统更符合Unity mod的生态习惯，代码也更少。

关于兼容性，我的经验是：写mod时尽量避免修改游戏静态字段的默认值，避免直接覆盖其他mod设置的全局变量，能用Postfix就用Postfix，能不改就不改。mod之间干起来，玩家可不会怪游戏，只会说“这俩mod有冲突”。

5. 常见问题与排查实录

到了分享踩坑经验的时候。这部分全是真金白银换来的教训，每一条我都亲身碰过，写出来帮大家少走弯路。

5.1 BepInEx乱码问题：日志和配置文件显示乱码怎么办

网上搜“bepinex乱码”能搜到一堆帖子，这个问题集中在中文玩家群体里。现象是LogOutput.log里中文日志变成一堆看不懂的字符，或者cfg配置文件里的中文注释显示成乱码。

根本原因是编码问题。BepInEx 5.x和6.x的配置文件默认使用UTF-8（带BOM）编码，但游戏目录、系统区域设置可能会影响编码识别。如果你用记事本打开cfg文件时显示正常，但BepInEx读出来是乱码，多半是文件被保存成了ANSI或GBK编码。

解决办法分两步：

修改BepInEx核心配置，在BepInEx/config/BepInEx.cfg里把Logging.EnableUnityLogging设为true，这样Unity日志和BepInEx日志会同时输出，有时能规避一部分编码问题。
如果ConfigEntry的中文注释乱，最稳的方案是改用英文注释，或者确保cfg文件用UTF-8 with BOM编码保存。Visual Studio Code打开文件后，右下角点编码选“通过编码保存”，选择UTF-8 with BOM即可。

还有一个容易被忽略的点：如果你的mod日志输出中文乱码，可能是你的C#源文件本身编码不对。用Visual Studio保存源文件时，确认文件编码是UTF-8 with BOM，别用默认的ANSI。源文件编码不对，编译出来的DLL里字符串就是乱码，怎么调BepInEx配置都没用。

5.2 Patch不生效，一步步排查的思路

Harmony补丁打了，但游戏行为完全没变化，这是新手最容易遇到也最让人抓狂的问题。我总结了一套排查思路：

确认日志里有没有插件加载成功。如果插件都没加载，其他都白搭。看LogOutput.log开头有没有你的插件GUID和版本信息。
确认补丁有没有注册。在PatchAll()后加一行日志，确保Harmony确实执行了所有补丁注册。如果补丁类不在插件程序集里，PatchAll扫描不到，需要手动调用CreateClassProcessor。
确认方法签名没写错。游戏更新后方法签名变了，或者反编译时看错了参数类型，都会导致补丁失败。Harmony注册补丁会在日志里打警告，提示“Failed to apply patch...”，仔细看。
确认游戏程序集有没有被混淆。有些游戏会对程序集做混淆，类名和方法名不再是普通的可读名称，这种情况下只能靠偏移量或特征码定位，难度陡增。先用dnSpy或Il2CppDumper确认一下方法名是否和补丁里写的一致。

按这个顺序排查，大多数问题都能定位。记住，补丁不生效的时候别急着翻代码逻辑，先看看补丁到底注册成功没有。

5.3 游戏更新后mod失效，代码保护与版本适配

游戏厂商更新游戏后，mod失效是必然会发生的事。Unity游戏更新可能导致三种情况：

一是方法签名变化，比如TakeDamage(int damage)改成TakeDamage(float damage, bool isCrit)，Harmony补丁立刻失效。这时候只能重新反编译游戏程序集，更新补丁方法签名。

二是方法所在类被重命名，或者整个程序集结构大改。这种情况在IL2CPP游戏里尤其常见，更新后global-metadata.dat变化巨大，之前的分析结果全部作废，需要重新跑一遍Il2CppDumper。

三是游戏加了代码保护或混淆。有些游戏会上混淆工具，类名方法名全变成不可读的字符，这时候定位目标方法的工作量会增加很多。我的经验是：优先从游戏行为反推关键方法，比如搜字符串、搜UI文本（玩家的血条数字“HP”）、搜音效文件名，这些特征在混淆后通常不会被改掉。

所以维护一个长期mod，版本适配工作比写代码本身还耗时。我的策略是：把游戏版本和对应的mod版本号记录清楚，更新mod时一并说明适配的游戏版本，玩家才知道该不该升级。

5.4 性能与稳定性注意事项

最后说几个容易被新handbook忽略的性能点。

首先是避免在Update里做重逻辑。很多mod作者喜欢在Update里每帧查状态、找对象，这会拖垮游戏帧率。能用事件订阅解决的就别轮询，BepInEx插件虽然继承了MonoBehaviour的Update，但你不一定要用，很多场景用Harmony补丁或配置文件事件就够了。

其次是注意对象销毁和引用泄漏。Unity的GameObject、Transform这些对象在场景切换后可能被销毁，你的mod如果缓存了它们的引用，需要监听场景卸载事件及时清空。否则游戏玩到一半，mod突然报NullReferenceException，很影响体验。

最后是发布前测试要完整。我一般在发布mod前会跑三遍流程：第一遍验证核心功能，第二遍验证配置项修改后的变化，第三遍开着任务管理器观察内存和CPU占用。三遍跑完没问题，才敢发出去。

我自己在实际操作中的体会是，做mod最有趣的部分不是写代码本身，而是“解构游戏”的过程。当你能通过BepInEx看清楚一个游戏是怎么跑起来、哪里能改、哪里不能改，你对Unity的理解会提升一个档次。最后再分享一个小技巧：写完mod后，记得在config里留一个Enabled开关，玩家可以一键关闭你的mod来排查冲突，这个细节能让你的mod口碑上一个台阶。整个项目做下来，我对Unity和C#的掌握都比以前扎实了，这算是做mod最大的意外收获。