BepInEx 安装上手全攻略：5 分钟给游戏搭好插件框架

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

深夜十一点，你终于腾出时间折腾游戏 Mod。网上早就有人做出了"显示 Boss 血条"的插件，可你下载回来一看，全是一堆 DLL 文件；照着教程找到的文件夹根本不存在，改完配置文件游戏反而黑屏。别急，BepInEx 游戏插件框架就是为这个时刻准备的——它把"插件安全加载进游戏"这件事压缩成"下载—部署—验证"三步，5 分钟就能跑通全流程。

你可以把它理解成一个万能转接头：游戏（插座）只有一种接口，各种插件（电器）却长着不同的插头，BepInEx 插在中间，让任何规格的插件都能稳定通电。它内部叫Chainloader（链式加载器），会在游戏启动时扫描BepInEx/plugins/目录、自动解析插件依赖、接管日志与配置——作为玩家，你几乎不用碰任何代码。

卡住你的那一步，其实只需要解压

绝大多数人不是不想装 Mod，而是被"框架怎么搭"劝退。痛点通常集中在三个地方：不知道插件放哪个文件夹、不知道自己的游戏属于哪种类型、改错配置导致游戏崩。BepInEx 的解法很朴素：解压一次安装包到游戏根目录，首次启动自动补全所有文件夹，之后插件往里一丢就能生效。原来让人望而却步的安装，只是一次解压加一次启动而已。

你能拿它做什么：三个马上能用的场景

与其纠结"它是什么"，不如看"它能帮你做什么"：

• 📦装现成的游戏 Mod：从社区下载插件 DLL，丢进BepInEx/plugins/，重启游戏即生效。这是 90% 玩家的日常用法。
• ⚙️不改游戏本体，只调配置：插件参数会写进BepInEx/config/下的配置文件，改数值、开开关，全程不碰原文件，想还原就删插件。
• 🚀自己动手写插件：基于BaseUnityPlugin基类写几十行 C#，就能做出自己的小功能。

先对号入座确认你的游戏属于哪种类型，因为不同类型对应不同发行包：

这张兼容表直接来自项目 README——市面上绝大多数 Unity 单机游戏和 XNA 复古游戏，都有对应的 BepInEx 玩法。

动手前自检：三件事先打勾

安装前花 3 分钟确认，能省下后面 30 分钟的排查时间：

• 确认游戏技术类型：打开游戏安装目录，找UnityPlayer.dll（Unity Mono 游戏）或GameAssembly.dll（Unity IL2CPP 游戏）；都找不到，多半是 .NET/XNA 类游戏。不同类型对应不同发行包。
• 选对版本分支：日常游玩选稳定发行版（目前 Unity Mono 的稳定支持最完善）；想尝鲜再考虑 Bleeding Edge 预览版（BepInEx 6 分支），更新快但可能不稳定。
• 备份游戏文件：把游戏根目录整个复制一份，或至少备份doorstop_config.ini和被覆盖的原生文件，折腾坏了随时还原。

快速安装路线：普通玩家 4 步搞定

第一步，下载：打开 BepInEx 官方发布页面，下载与你游戏类型匹配的预编译压缩包——普通玩家完全不需要自己编译。

第二步，解压：把压缩包内容直接解压到游戏根目录，也就是和游戏主程序.exe同一个文件夹，不是里面任何子文件夹。放错层级是新手最常见失误。

第三步，确认目录结构。装完后根目录应该长这样：

游戏根目录/ ├─ BepInEx/ │ ├─ core/ # 框架本体，一般不用动 │ ├─ plugins/ # 插件统一放这里（首次启动后自动生成） │ └─ config/ # 配置文件目录 ├─ doorstop_config.ini ├─ winhttp.dll # Windows 下的启动引导文件 └─ 游戏主程序.exe

第四步，启动游戏：正常运行即可。首次启动时 BepInEx 会自动补全plugins/、config/目录并生成日志文件——这一步不需要你做任何额外操作。

开发者路线：源码构建最新代码

想追最新代码或自己改框架？仓库提供了基于 .NET 的自动化构建脚本，完整说明在docs/BUILDING.md。前提是装好.NET 6.0 或更高版本，然后克隆并执行：

git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx ./build.sh --target Compile

• Windows 命令行用build.cmd --target Compile，PowerShell 用./build.ps1 --target Compile
• 想直接产出可分发的成品包，用--target Publish，压缩包会生成在bin/dist目录

装完怎么验证：安装成功自检清单

游戏跑起来后，对照下面四条逐项确认：

• 出现黑色命令行窗口：启动瞬间弹出加载窗口，滚动显示初始化信息，正常现象，不要关
• 目录自动生成：BepInEx/plugins/和BepInEx/config/已被自动创建
• 日志文件存在：BepInEx/LogOutput.log已生成，里面能看到插件加载记录
• 游戏正常进入：没有闪退、没有卡黑屏，顺利进到主界面

四条全过，说明框架已稳稳挂载，接下来就可以去装插件了。

两个配置文件分别管什么

很多人分不清这两个文件，其实分工非常明确：

最常用的三个配置开关，逐个说清楚：

1.doorstop_config.ini里的enabled—— 这是整个框架的"总电闸"，必须保持true。游戏更新后框架打不开，八成是它被更新脚本改回了false。

2.target_assembly入口程序集—— 指向框架的入口程序集（Mono 版默认指向BepInEx\core\BepInEx.Unity.Mono.Preloader.dll）。除非你是开发者，否则不要动它，改错会导致框架完全无法启动。

3.[UnityMono]段的dll_search_path_override—— 部分魔改过的游戏缺失系统库，靠它告诉 Mono 去哪里找核心库。只有出现相关报错时才需要调整。

常见问题急救包

Q1：启动游戏直接黑屏或闪退

• 症状：点击图标后黑屏，几秒后闪退，或干脆没反应。
• 原因：启动引导文件缺失，或doorstop_config.ini里的enabled被改掉了。
• 三步解决：① 检查游戏根目录的winhttp.dll是否存在，没有就从安装包重新解压；② 确认[General]下enabled = true；③ 查看output_log.txt或BepInEx/LogOutput.log，把报错行复制去搜解决方案。

Q2：插件放好了，游戏里却没生效

• 症状：插件 DLL 已放进plugins/，进游戏毫无变化。
• 原因：版本不匹配、插件依赖的另一个插件没装、或目录放错了层级。
• 三步解决：① 确认 DLL 直接放在BepInEx/plugins/下（或其中任意一层子文件夹），而不是core/里；② 核对插件作者声明的最低 BepInEx 版本是否与你的发行版兼容；③ 打开BepInEx/LogOutput.log，搜索Error或插件名，看具体报错。

Q3：日志文件越滚越大，占了几百 MB

• 症状：LogOutput.log体积爆炸，磁盘告急。
• 原因：日志级别开得太细，插件把大量调试信息写进了日志。
• 三步解决：① 把BepInEx.cfg里的LogLevel从Info改成Warning，过滤无关输出；② 定期清理LogOutput.log，或直接删除让它下次启动重新生成；③ 排查是否有插件在循环里疯狂写日志，有的话反馈给作者。

进阶彩蛋：写出你的第一个插件

不满足于"装别人的 Mod"？那就试试"写自己的 Mod"。插件接口与特性定义都在BepInEx.Core/Contract/目录下，Unity Mono 游戏的插件基类是BepInEx.Unity.Mono/下的BaseUnityPlugin。一个最小可用的插件长这样：

using BepInEx; namespace MyFirstPlugin; [BepInPlugin("com.yourname.example", "My First Plugin", "1.0.0")] public class ExamplePlugin : BaseUnityPlugin { private void Awake() { Logger.LogInfo("Hello from BepInEx!"); } }

编译成 DLL 丢进BepInEx/plugins/，启动游戏，你就能在LogOutput.log里看到自己的第一条插件日志。想深入的话，仓库的docs/目录下有构建与贡献指南，社区里也有大量现成插件可以对照学习——从"玩家"到"作者"，只差这几十行代码。

现在就去试试

装插件不该是少数人的特权。BepInEx 把"给游戏加功能"这件听起来很技术的事，简化成了"解压—复制—启动"三步。现在就按这份自检清单走一遍，5 分钟后，你就能亲手把游戏改造成自己喜欢的样子——别让那个血条插件继续躺在下载文件夹里了。

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