BepInEx 实用指南：从选版本到给 Unity 游戏装上第一个插件

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

你想给 Unity 游戏加个 HUD 或者跳过开场动画，但不想动游戏的一个字节——这就是 BepInEx 插件框架要解决的问题。它是一个跑在 Unity Mono、Unity IL2CPP 和 .NET 游戏里的插件加载器，把 dll 丢进指定目录，游戏启动时自动加载并执行你的代码，插件出问题时删掉那个目录就行，游戏本体不改动。

📦 BepInEx 是什么：不改原文件的运行时插件框架

BepInEx 用 Unity Doorstop 在进程启动早期注入预加载器，再由 Chainloader 扫描插件目录、按 GUID 解析依赖顺序加载。非侵入式——所有代码运行时加载，不写游戏原文件。

统一契约——插件实现IPlugin接口并带[BepInPlugin]特性，加载器自动识别 GUID 和依赖关系。跨运行时——同一套核心接口覆盖 Unity Mono、Unity IL2CPP、.NET Framework 三种引擎。当前仓库版本是 6.x，只有 Unity Mono 有稳定发布，IL2CPP 和 .NET 仍处开发阶段，各平台支持如下：

🚀 环境准备与安装：从选版本到跑通第一个插件

安装前先判断游戏用的是哪种运行时，看两个文件就行：游戏根目录里有UnityPlayer.dll就是 Unity Mono，有GameAssembly.dll就是 Unity IL2CPP，.NET 游戏则基于 .NET Framework 运行。

按下面 4 步装：

1. 克隆源码仓库：

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

2. 装好 .NET 6.0 或更高版本的 SDK，在仓库目录里执行构建（CakeBuild 需要 .NET 6.0+）：

./build.sh --target Compile # Linux / macOS build.cmd --target Compile # Windows

3. 把bin/dist下对应运行时的发行包解压到游戏根目录，最终结构长这样：

游戏根目录/ ├─ BepInEx/ │ ├─ core/ # 核心 dll，含 Preloader │ ├─ patchers/ # 补丁插件 │ ├─ plugins/ # 你自己的插件 dll 放这里 │ ├─ config/ # BepInEx.cfg 和每个插件的 .cfg │ └─ LogOutput.log # 启动后自动生成的运行日志 ├─ doorstop_config.ini # Doorstop 注入配置 ├─ winhttp.dll # Windows 门文件（Linux 用 libdoorstop.so） └─ 游戏可执行文件

4. Linux 用户不直接依赖 winhttp 注入，仓库里带了一个Runtimes/Unity/Doorstop/run_bepinex_mono.sh启动脚本：把脚本顶部的executable_name改成游戏二进制名，然后./run_bepinex_mono.sh就能带上 BepInEx 启动。

验证装好没有，看两个现象：游戏启动时弹出一个控制台窗口显示 BepInEx 版本号，游戏目录多出一个BepInEx/子目录且里面有LogOutput.log文件。

⚙️ 关键配置：3 个改完就有用的配置项

启动行为由doorstop_config.ini控制，放在游戏根目录：

[General] enabled = true target_assembly = BepInEx\core\BepInEx.Unity.Mono.Preloader.dll

enabled是整个 Doorstop 注入的总开关，改成 false 游戏就走干净启动、BepInEx 完全不加载，这是排查插件冲突时最常用的开关。target_assembly指向预加载器的 dll，Mono 游戏是BepInEx.Unity.Mono.Preloader.dll，IL2CPP 游戏换成BepInEx.Unity.IL2CPP.dll，一般不用改。

运行时行为由BepInEx/config/BepInEx.cfg控制，首次启动自动生成：

[Logging.Disk] Enabled = true LogLevels = "Fatal, Error, Warning, Message, Info"

LogLevels决定哪些级别的日志会写进LogOutput.log，加上Debug就能在日志里看到每次加载了哪些程序集、每个 patch 打在哪，是排查插件问题时的第一站。

🩺 常见问题排查：从启动失败到插件没加载

现象：游戏正常启动，但没弹控制台、BepInEx/目录也没生成。可能原因：Doorstop 注入没生效，最常见是doorstop_config.ini里enabled没开，或者门文件（Windows 的winhttp.dll、Linux 的libdoorstop.so）和 ini 不在同一目录。解决：确认enabled = true，门文件和 ini 一起放在游戏根目录。

现象：控制台有 BepInEx 启动日志，但你的插件没生效。可能原因：dll 没放对位置，或者插件声明的BepInDependency依赖没装。解决：把 dll 移到BepInEx/plugins/，打开BepInEx/LogOutput.log搜索插件 GUID 或Error关键字，日志里会明确告诉你哪个依赖缺失。

现象：控制台窗口一闪就关，看不清输出。解决：在BepInEx.cfg里把[Logging.Console]段的PreventClose改成true，窗口就会保留到游戏退出。

🎯 装好之后做什么

BepInEx 的价值在于把改游戏这件事从"动原文件"降级成"扔 dll 进目录"，插件坏了直接删，游戏本体一个字节都不变。下一步去插件社区挑一个 UI 类或画质类插件，把 dll 丢进BepInEx/plugins/重启游戏，LogOutput.log里能看到它的加载日志就算成功。写自己的插件时，参考Runtimes/Unity/BepInEx.Unity.Mono/BaseUnityPlugin.cs看官方基类结构，再配一份BepInEx.cfg里LogLevels加 Debug 的调试环境，Unity 插件开发入门这条路就通了。

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