BepInEx：免费的 Unity Mod 插件框架，安装构建与排障指南

【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx

想让 Unity 游戏跑 Mod，不用再自己写注入和钩子。BepInEx 是免费的 Unity Mod 插件框架：插件 DLL 放进 plugins 目录，启动即自动发现、按依赖排序并加载，同时覆盖 IL2CPP 与 .NET 系游戏（XNA、FNA、MonoGame）。玩家拿来即用，开发者也能基于它写插件。

快速上手：从零到可用的 4 步

插件安装步骤：只想装来用

1. 下载对应运行时的发布包：Unity Mono 选稳定版，IL2CPP 选 Bleeding Edge 版。
2. 把解压出的BepInEx文件夹整个拷到游戏根目录（即 exe 所在处）。
3. 把要用的插件 DLL 放进BepInEx/plugins。
4. 正常启动游戏，打开游戏根目录的LogOutput.log，确认能看到各插件的加载记录、没有 ERROR 行。

第 4 步看不到任何 BepInEx 输出时，通常是注入层没生效，直接看下文排障清单第 1 条。

源码构建指南：想自己构建

前提：安装.NET 6.0或更高版本，这是构建脚本的硬性要求。

git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx

然后按系统执行编译命令：

./build.sh --target Compile # Linux

build.cmd --target Compile # Windows

要打包出分发包，把目标换成--target MakeDist（会再走一遍 Compile），细节见 docs/BUILDING.md。

各运行时平台支持情况：

原理 3 分钟看懂：它是怎么跑起来的

把整个加载过程想成货运站的安检闸机：游戏本体是一辆要出发的卡车，插件是货箱。卡车到闸机口（Doorstop 注入层）先被截下，扫描仪逐箱读运单——GUID、版本号、依赖项、目的地进程；同 GUID 的旧货箱直接拦下，目的地不符的也拦下；调度员按依赖顺序重新码好货箱，才放卡车走。

落到代码上：

• 闸机开关在doorstop_config_mono.ini：enabled = true，target_assembly指向BepInEx/core/BepInEx.Unity.Mono.Preloader.dll，游戏一启动就先执行这个预加载程序。
• 扫描由BaseChainloader完成：遍历 plugins 目录，用 Cecil 逐 DLL 读出[BepInPlugin]等特性，元数据缓存到 cache 目录，二次启动跳过重复解析。
• 排序在同处完成：按 GUID 去重、按[BepInDependency]排出先后，全部加载结束才把控制权交还给游戏主流程。

目录结构（路径全部写死在代码里，不是约定俗成）：

游戏根目录/ ├── BepInEx/ │ ├── core/ # 框架核心 DLL 与预加载入口 │ ├── plugins/ # 插件 DLL 放这里 │ ├── patchers/ # 预加载修补程序，先于主循环执行 │ ├── config/ # 各插件的 .cfg 配置，含全局 BepInEx.cfg │ └── cache/ # 插件元数据缓存，加速二次启动 └── LogOutput.log # 磁盘日志，崩溃排查先看它

路径定义见 BepInEx.Core/Paths.cs，扫描与排序逻辑见 BepInEx.Core/Bootstrap/BaseChainloader.cs。

进阶可选项：值得动手调的地方

• redirect_output_log：改 Runtimes/Unity/Doorstop/doorstop_config_mono.ini 为 true。效果：Unity 原生日志重定向到当前目录的 output_log.txt。适合排查 BepInEx 接管之前发生的错误。
• InstantFlushing：在BepInEx/config/BepInEx.cfg的 Logging.Disk 段设为 true（定义见 BaseChainloader.cs）。效果：每条日志立即写盘，高频日志时有性能损耗。适合崩溃现场取证。
• ConcurrentFileLimit：同在 Logging.Disk 段，默认 5。效果：限制并发写入的日志文件数，一个游戏实例占一个文件。适合同时调试多个实例。
• dll_search_path_override：doorstop ini 的 [UnityMono] 段，默认"BepInEx\core"。效果：Mono 查找核心库时的首选目录。适合原游戏 Managed 目录被裁剪的发行版。
• [BepInDependency] / [BepInProcess]：定义在 BepInEx.Core/Contract/Attributes.cs。效果：前者声明必须先加载的插件（区分硬依赖与软依赖），后者限定只在指定进程加载。适合写插件时控制加载条件。

排障清单：常见问题与修复

现象：游戏能进主界面，但 plugins 里的插件全都没反应。 原因：注入层 Doorstop 没生效，或 target_assembly 指错了程序集。 修复：打开 doorstop 配置，确认enabled = true，且 target_assembly 指向BepInEx\core\BepInEx.Unity.Mono.Preloader.dll。

现象：启动时报缺少 mscorlib 等核心程序集。 原因：原游戏的 Managed 目录被裁剪过，Mono 找不到基础库。 修复：保留 ini 里的dll_search_path_override = "BepInEx\core"，让 Mono 优先从框架目录取库。

现象：同一插件放了两份不同版本的 DLL，只有一份被加载。 原因：GUID 相同即视为同一插件，框架按版本号只保留最高的一份。 修复：删掉旧版本 DLL，plugins 里只留一份。

现象：插件在 A 游戏正常，换到 B 游戏就不加载。 原因：类上标了[BepInProcess]，只允许在指定进程名下运行。 修复：核对属性里的进程名和当前游戏 exe 文件名是否一致。

现象：⚠️ IL2CPP 游戏装稳定版 BepInEx 无法运行。 原因：官方稳定发布目前只覆盖 Unity Mono，IL2CPP 没有稳定版。 修复：按发布说明改用 Bleeding Edge 构建，或等待官方后续支持。

BepInEx 是当前 Unity Mod 生态的事实基础设施，绝大多数第三方插件都构建在它之上。想深入，从 docs/BUILDING.md 的构建目标看起，再通读 BepInEx.Core/ 里的配置与日志 API。

【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx