给游戏加功能又怕弄坏文件？BepInEx 安装教程与排坑指南

给游戏加功能又怕弄坏文件？BepInEx 安装教程与排坑指南

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

想改游戏，又怕改坏？BepInEx 插件框架的思路

如果你给游戏加功能时最怕"改坏原文件"，BepInEx 插件框架的思路很直接：所有修改都以插件 DLL 的形式外挂加载，游戏启动时由框架统一注入执行，游戏本体文件一个字节都不动。装插件就是把 DLL 丢进BepInEx/plugins/文件夹；想卸载就删掉对应文件，干干净净。框架本身只认三样东西：插件的 DLL 文件、插件自己的配置文件、以及一份统一的启动日志。

先看游戏用的哪个运行时

装 BepInEx 之前，先确认游戏跑在哪种运行时上，这决定你该拿哪个版本的包：

• 游戏目录里有UnityPlayer.dll：Unity Mono 运行时，目前唯一有稳定发布的分支；
• 有GameAssembly.dll、没有UnityPlayer.dll：Unity IL2CPP 运行时，走 Bleeding Edge 构建；
• 基于 .NET Framework / MonoGame / XNA 的游戏：用对应的 .NET 构建。

版本上，普通玩家建议直接用 Unity Mono 的最新稳定发布包；IL2CPP 和 .NET 方向还在快速迭代，适合愿意跟 Bleeding Edge 构建的开发者。拿错分支是最常见的"装完打不开游戏"原因，先看文件再下包，比什么都重要。

三步装好：下载、解压、验证

以最常用的 Unity Mono 游戏为例，BepInEx 安装教程实际就四步：

1. 从官方发布页下载对应运行时和平台的压缩包；
2. 把内容解压到游戏根目录（Steam 游戏在steamapps/common/游戏名下，Epic 在Epic Games\游戏名下）；
3. 确认根目录生成了doorstop_config.ini和平台对应的注入文件（Windows 为winhttp.dll，Linux 为libdoorstop.so，macOS 为libdoorstop.dylib）；
4. 启动游戏，验证安装是否成功。

验证成功的三个信号：启动时出现控制台窗口打印加载信息；BepInEx/目录自动生成core、plugins、config、cache四个子文件夹；BepInEx/LogOutput.log出现，并且末尾列出已加载的插件清单。只看日志里插件列表，才是框架真正生效的证据。

习惯动手的开发者也可以从源码编译，仓库自带 CakeBuild 脚本，需要 .NET 6.0 或更高版本环境：

git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx # Windows 用 build.cmd --target Compile，macOS/Linux 用 ./build.sh ./build.ps1 --target Compile

插件是怎么挂进游戏进程的

原理分两层，理解这两层后大部分"为什么没生效"的问题都能自己回答。第一层是 UnityDoorstop：游戏进程真正跑起来之前先执行它，它读取doorstop_config.ini，按配置把 BepInEx 预加载程序集加载进进程——Mono 分支是BepInEx\core\BepInEx.Unity.Mono.Preloader.dll。第二层是 Chainloader：预加载器初始化路径后，扫描plugins目录，用 Cecil 逐个解析 DLL 里带[BepInPlugin]特性的类，取出 GUID、名称、版本，按[BepInDependency]声明排好加载顺序，再依次实例化并调用Awake。整个过程 BepInEx 只是往游戏里"借"了一段执行流程，游戏数据、存档、资产文件全程没被写过。

真正值得动的配置只有几项

日常用得到的配置集中在两个文件。doorstop_config.ini里只有两项常用：enabled = true决定 Doorstop 是否生效，target_assembly指向要加载的预加载程序集路径，换运行时分支时只需要改它。

BepInEx/config/BepInEx.cfg里真正影响使用的参数如下：

[Logging.Disk] Enabled = true LogLevels = Fatal | Error | Warning | Message | Info InstantFlushing = false [Logging.Console] Enabled = true [Caching] EnableAssemblyCache = true

磁盘日志默认只记录 Info 及以上级别；InstantFlushing = true会让日志立即落盘，崩溃排错时非常有用，但日志量大时有明显性能开销，平时保持 false。ConcurrentFileLimit默认 5，同时开多个游戏实例调试时可以调大。插件发现缓存默认开启，删了插件想立刻生效时关掉它即可。其余配置保持默认即可，动之前先在日志里确认问题。

游戏打不开？按这个清单排查

启动失败的排查顺序，从最常见到最少见：

1. 注入文件在不在：winhttp.dll（Windows）、libdoorstop.so（Linux）、libdoorstop.dylib（macOS），缺一个都不启动；
2. doorstop_config.ini里enabled = true没有错，target_assembly路径与实际文件一致（注意 Windows 反斜杠和 Linux 正斜杠）；
3. 文件权限：Linux/macOS 下注入库需要可执行权限；
4. 看BepInEx/LogOutput.log。崩溃窗口一闪而过时，日志里最后一条 Error 才是真正原因，不要只看黑屏画面；
5. 确认拿的 BepInEx 分支和游戏运行时匹配。

插件没加载？检查这四样

插件加载失败基本逃不出四种情况：

1. 放错位置：必须是BepInEx/plugins/下的.dll，子目录里的 dll 不会被扫描；
2. 元数据缺失：没有[BepInPlugin]特性的类会被直接跳过，日志里有 "Skipping over type" 警告；
3. GUID 或版本不合法：GUID 只允许字母数字和._-，版本必须能解析；
4. 依赖不满足：[BepInDependency]声明的硬依赖缺失或版本不在范围内时，当前插件不加载并记一条错误日志。

定位技巧：把plugins里的 DLL 逐个移出去二分，哪个移走日志就干净了，冲突就是它；也可以先移走全部插件跑一次纯净启动，确认框架本身正常，再分批加回来。

写个 10 行插件试试

一个最小的 Unity 插件长这样，全部代码不到 10 行：

[BepInPlugin("com.example.hello", "Hello", "1.0.0")] public class Hello : BaseUnityPlugin { private void Awake() { var enabled = Config.Bind("General", "Enabled", true, "插件开关"); Logger.LogInfo($"Hello 已加载，Enabled={enabled.Value}"); } }

编译出 DLL 放进plugins目录，下次启动就会被 Chainloader 发现。继承BaseUnityPlugin后每个插件自动拥有独立的日志通道和一份config/GUID.cfg配置文件，不需要手写读写。声明依赖时用[BepInDependency("其他插件GUID", ">=1.0.0")]，版本范围按 SemVer 语法解析，硬依赖缺失时当前插件会整体跳过而不是半加载。

生态与社区资源

BepInEx 维护三条运行线：Unity Mono（当前唯一稳定发布）、Unity IL2CPP 和 .NET（XNA、FNA、MonoGame 等）。平台覆盖上，Unity Mono 支持 Windows、macOS、Linux；IL2CPP 支持 Windows 和 Linux，不支持 macOS 和 ARM；.NET 线在 Linux/macOS 上依赖 Mono 运行。周边生态上，社区维护了 BSIPA、IPA、MelonLoader、MonoMod、UnityInjector 等一系列插件加载器，很多热门游戏插件就是基于 BepInEx 插件框架的接口写的。遇到问题先翻官方文档站的安装与用户指南，再去 issue tracker 搜一下是否已有相同报告；报 bug 时把 BepInEx 版本、游戏名、日志里的插件列表三样带上，能省掉大量来回。项目采用 LGPL-2.1 许可证，底层依赖 UnityDoorstop、HarmonyX、MonoMod 等开源库，贡献走标准的 issue 与 PR 流程。

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