BepInEx 插件框架 3 步上手装插件、改配置、查报错一次讲清【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInExBepInEx 是一个给 UnityMono 和 IL2CPP以及 .NET 系游戏XNA、FNA、MonoGame 等做插件加载的框架。简单说它把游戏启动流程劫持一下在游戏初始化之前替你扫描、加载BepInEx/plugins/里的插件程序集并给每个插件提供统一的配置和日志接口。这篇文章写给两类人给游戏装模组的玩家以及想读懂或扩展这套框架的开发者。所有目录名、文件名都能直接对着磁盘照做。1. 动手前先判断你的游戏属于哪种类型选错版本是最大的坑。BepInEx 对三种目标分别有各自的预加载入口装之前先确认游戏走的是哪条路。怎么分辨 Unity Mono 和 IL2CPP看游戏根目录里游戏名_Data/Windows 上常叫xxx_DataLinux 上就是Data里面的东西有Managed/子目录里面一堆.dll→Unity Mono这是目前唯一有稳定发布版的路线没有Managed/只有一个Game.dll且Plugins/x86_64/下有GameAssembly.dll→Unity IL2CPP需要走 Doorstop 额外注入组件平台支持一览来自仓库 README 的兼容性表IL2CPP 在 macOS 上不支持.NET 游戏在 macOS/Linux 上走 Mono 运行时目标WindowsmacOSLinuxUnity Mono✔✔✔Unity IL2CPP✔✘✔.NET / XNA✔MonoMono2. 把 BepInEx 解压进游戏根目录装完应该长什么样官方发布包解压到游戏根目录和game.exe同级之后结构应该是这样的。这份结构不是凭空来的是 BepInEx.Core/Paths.cs 里SetExecutablePath逐项写死的可以对着源码核对游戏根目录/ ├── game.exe ├── doorstop_config.ini ├── BepInEx/ │ ├── core/ # 框架自身的 DLL │ ├── config/ # BepInEx.cfg 各插件的 .cfg │ ├── plugins/ # 第三方插件放这里 │ ├── patchers/ # 预加载期的 Patcher 插件 │ └── LogOutput.log两个容易漏的点doorstop_config.ini和游戏可执行文件在同一层不是放在BepInEx/里面解压后游戏根目录里只能有一个BepInEx/。如果你发现BepInEx/BepInEx/这种嵌套说明上次解压多套了一层doorstop_config.ini 在管什么Mono 路线下是 Doorstop 这个前置钩子把 BepInEx 预加载器挂进游戏进程的。看 Runtimes/Unity/Doorstop/doorstop_config_mono.ini 就能明白关键的两行在干嘛[General] enabled true target_assembly BepInEx\core\BepInEx.Unity.Mono.Preloader.dllenabled true表示钩子生效target_assembly指向真正要执行的预加载程序集。游戏启动后什么都不发生多半就是enabled被改成了false。3. 第一个实际目标装上一个能跑的插件插件文件放进 BepInEx/plugins/ 就完事插件就是普通的 .NET 程序集。把xxx.dll放进BepInEx/plugins/有依赖 DLL 就一起放进去启动游戏Chainloader 会自动扫描并加载不需要任何注册步骤。注意两点它们直接决定插件能不能被识别见 BepInEx.Core/Bootstrap/BaseChainloader.cs 的ToPluginInfo插件类型上必须有[BepInPlugin]特性且GUID、名称、版本三者都合法缺任何一个这个类型会被跳过并在日志里记一条 Warning程序集必须引用BepInEx.Core否则扫描阶段直接判定不是插件依赖不满足时会发生什么插件用[BepInDependency]声明依赖的 GUID用[BepInIncompatibility]声明互斥项。依赖缺失时插件不会被加载日志里会写明缺的是哪个 GUID——照着去补那个插件而不是盲目重装。4. 改配置找对 BepInEx/config 下的 .cfg 文件全局配置和插件配置不是一回事BepInEx/config/下会有两类文件BepInEx.cfg—— 框架自己的全局配置日志级别等路径由 BepInEx.Core/Paths.cs 中BepInExConfigPath config/BepInEx.cfg固定[作者].[插件名].cfg—— 每个插件自己的配置文件TOML 语法插件启动时由ConfigFile自动生成插件的 TOML 配置大概长这样方括号是分区等号两边留空格[Graphics] # 是否开启高清纹理 EnableHiRes true # 缩放倍数 Scale 2改动是即时的ConfigFile默认SaveOnConfigSet true插件里每次 set 都会落盘见 BepInEx.Core/Configuration/ConfigFile.cs所以游戏运行中改过的值下次启动会保留。配置改了不生效先查这三点改错文件了——全局行为看BepInEx.cfg插件行为看对应的[作者].[插件名].cfg值不在允许范围内——插件用AcceptableValueList/AcceptableValueRange限定了取值越界的值会被拒掉日志里有记录插件根本没加载成功——先翻日志确认插件在不在已加载列表里再谈配置5. 启动失败或插件没反应时从 LogOutput.log 查起日志文件叫LogOutput.log就放在BepInEx/根目录BepInEx.Core/Bootstrap/BaseChainloader.cs 里通过DiskLogListener创建文件名写死为LogOutput.log如果文件被占用打不开会自动改用LogOutput.2.log这样的名字。日志里先搜哪几个词WARNING里带 Skipping → 某个插件类型因 GUID/版本不合法被跳过Failed to load→ 插件程序集加载失败往下找AssemblyResolutionException看缺的是哪个依赖你插件的 GUID 或名称 → 确认它出现在加载列表里Exception/Stack trace→ 插件自己抛错堆顶的 DLL 名能告诉你锅在谁头上磁盘日志默认只写 Info 级别及以上DiskLogListener的displayedLogLevel默认值是LogLevel.Info想看到更多细节去BepInEx/config/BepInEx.cfg的[Logging]分区把级别调低。6. 想写插件或从源码构建从这里入手源码目录怎么分工BepInEx.Core/ —— 与运行时无关的核心配置系统Configuration/、日志Logging/、插件契约Contract/IPlugin.cs和Attributes.cs、启动链Bootstrap/Runtimes/Unity/—— Unity 特有部分Mono 版 Chainloader 在BepInEx.Unity.Mono/IL2CPP 版在BepInEx.Unity.IL2CPP/含 Il2CppInterop 对接和原生 hookRuntimes/NET/—— .NET Framework / .NET Core 游戏的加载入口BepInEx.Preloader.Core/—— 游戏真正初始化之前跑的预加载逻辑Patcher 机制在这里写插件的最小路径参考BepInEx.Unity.Mono/BaseUnityPlugin.cs的基类结构给自己的类加上[BepInPlugin]特性即可。本地构建一个发行包构建文档在 docs/BUILDING.md需要 .NET 6.0 或更新版本。拿到仓库后git clone https://gitcode.com/GitHub_Trending/be/BepInEx在仓库根目录执行构建脚本Compile目标会拉取依赖并产出二进制./build.sh --target Compile要打包分发用的 zip把 target 换成Publish产物会进bin/dist/。收尾注意事项游戏每次大版本更新后先单跑一遍 BepInEx不装任何插件确认框架本身能启动再逐个装回插件更新前把整个BepInEx/目录尤其是config/备份一份插件配置是插件作者的代码之外的另一份状态报问题给别人之前附上最近的LogOutput.log片段和 BepInEx 版本号版本号在日志开头几行就能找到IL2CPP 路线目前是预发布性质遇到问题先看日志里的Harmony/Il2CppInterop相关报错再下结论下一步建议装好框架后先读一遍BepInEx/config/BepInEx.cfg里每个分区对应的注释再决定要不要动全局日志级别【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考