BepInEx 使用指南从安装到排错一次讲透 Unity 游戏模组框架【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInExBepInExBepis Injector Extensible是一个面向 Unity Mono、Unity IL2CPP 以及 .NET 游戏XNA、FNA、MonoGame 等的插件加载与模组框架。游戏本身不开放修改入口而 BepInEx 通过在游戏启动阶段注入自己的运行时替你完成挂钩这一步之后你只需往指定目录丢 .dll 插件它负责加载、排序、注入配置与日志。本文按你会实际遇到的问题来讲先选对版本再装、再用、再排错最后给想动手写插件的人指个路。选对版本Mono、IL2CPP 还是 .NET装错版本是最常见的翻车原因。BepInEx 针对不同游戏运行时提供了独立分支三者不能混用分支适用游戏WindowsmacOSLinuxUnity Mono以 C# 脚本运行、目录里有*_Data/Managed的 Unity 游戏完整支持完整支持完整支持Unity IL2CPP编译为 C 的 IL2CPP 构建 Unity 游戏支持不支持支持.NET / XNAXNA、FNA、MonoGame 等非 Unity 游戏支持经 Mono 运行经 Mono 运行判断方法很简单看游戏目录。存在GameName_Data/Managed且里面是 .NET 程序集的基本就是 Mono 版只有GameName_Data/Plugins/x86_64这类原生库、Managed 目录几乎为空的多半是 IL2CPP。需要说明的是目前只有 Unity Mono 分支有稳定的正式发行版IL2CPP 与 .NET 分支更偏向尝鲜使用。各分支的实现分别位于 Runtimes/Unity/ 与 Runtimes/NET/ 两个源码目录可以对照上文理解结构。安装步骤解压、放置、验证目录以 Unity Mono 版本为例流程只有三步下载与你的游戏对应的 BepInEx 压缩包解压到游戏根目录与游戏启动 exe 同级启动一次游戏让框架初始化生成剩余文件。完成后正确的目录结构应该长这样路径逻辑见 BepInEx.Core/Paths.cs游戏根目录/ ├── game.exe或 .app ├── BepInEx/ │ ├── core/ ← 框架核心程序集 │ ├── plugins/ ← 你放插件的地方 │ ├── patchers/ ← 补丁类插件 │ ├── config/ ← 配置文件含全局 BepInEx.cfg │ ├── cache/ ← 元数据缓存 │ └── LogOutput.log └── doorstop_config.iniLinux 下还有 run_bepinex_mono.sh几个容易踩的坑别嵌套如果出现BepInEx/BepInEx/说明解压时多套了一层把内层文件平移到游戏根目录即可。权限Linux/macOS 下确保游戏目录可写Steam 部署的保护模式Steam Protect需要先在 Steam 中关闭。平台注入方式Windows 靠劫持启动入口Linux/macOS 则通过 Doorstop 组件把libdoorstop预加载进游戏进程doorstop_config_mono.ini里的target_assembly指向BepInEx/core/BepInEx.Unity.Mono.Preloader.dll就是这一步的证据一般无需改动。日常使用插件怎么放、依赖怎么管装插件把插件主 .dll 放进BepInEx/plugins/即可无需注册、无需改配置下次启动游戏时框架会自动扫描并加载。部分插件依赖较多作者会额外附上几个配套 dll 或要求安装公共库如 0Harmony照说明把它们一并放进plugins/或游戏根目录即可。依赖与冲突BepInEx 的插件通过元数据声明彼此关系框架据此决定加载顺序或直接拒绝加载[BepInDependency(某插件GUID, DependencyFlags.HardDependency)]→ 强依赖缺失时本插件不加载并报错DependencyFlags.SoftDependency→ 软依赖缺失时照常运行[BepInIncompatibility(某插件GUID)]→ 与指定插件不兼容共存时本插件跳过加载并给出警告。这套声明逻辑定义在 BepInEx.Core/Contract/Attributes.cs也是排查为什么我的插件没加载的第一手资料。一个实用的习惯新装插件后单独启动一次游戏看日志确认它正常初始化再叠加下一个插件。这样出问题时可以立刻定位是哪一次变更引入的。修改配置读懂两个 .cfg 文件配置文件分两层全部是 TOML 格式的文本放在BepInEx/config/下BepInEx.cfg—— 全局配置日志级别、控制台行为等由框架自身维护插件自己的 .cfg如MyPlugin.cfg—— 插件创建并保存配置项文件名通常与插件同名。一个典型的插件配置长这样# General options for MyPlugin [General] # Enable the feature? EnableFeature true # Player movement speed multiplier PlayerSpeed 1.5规则只有三条值得记住用[Section]分组、#写注释、等号两边留空格便于阅读。插件默认在每次修改后立即写盘SaveOnConfigSet机制所以改配置不需要什么特殊操作——关闭游戏、用纯文本编辑器改值、存为 UTF-8、再开游戏。如果改了配置却不生效先怀疑两点值写到了错误的 Section 下Section 和 Key 都区分大小写或者文件编码带 BOM 导致解析异常。实在没把握时直接删掉该 .cfg 重启游戏插件会按默认值重建一份干净的配置。排错方法用 LogOutput.log 30 秒定位问题BepInEx/LogOutput.log记录了从注入成功到游戏关闭的全过程是排错时唯一要盯的文件。它的条目按严重度从高到低分为六档Fatal→Error→Warning→Message→Info→Debug定义见 BepInEx.Core/Logging/LogLevel.cs。排错的顺序建议是先搜Error插件崩溃、类型加载失败几乎都在这里异常堆栈会直接指出是哪个 dll 的哪一行再看启动段日志开头会逐条列出被扫描的插件及其状态。你的插件名根本没出现 → 文件没放对目录或不是有效的 .NET 程序集出现了但状态异常 → 看它紧跟的 Error依赖报错出现 Dependency not found 之类字样时按提示补装对应 GUID 的插件对照实验仍无法定位时把plugins/清空只留问题插件再启动能跑起来就逐个加回二分法很快。平时嫌日志输出太多可以在BepInEx.cfg的[Logging]段把 Level 从Debug调到Info日志文件的增长速度和干扰都会明显下降。进阶构建源码与写一个最小插件如果你要自己构建项目流程见 docs/BUILDING.md环境需要 .NET 6.0 或更高然后git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx ./build.sh --target Compile # Linux/macOSWindows 下对应 build.cmd --target Compile构建目标有三个Compile只编译二进制MakeDist额外生成可分发的发行包Publish再打成压缩包产物都输出到bin/dist。写插件的门槛比想象中低一个类继承BaseUnityPlugin挂上元数据特性框架就会在启动时实例化它并自动注入Logger本插件专属日志和Config本插件专属配置文件两个对象using BepInEx; using BepInEx.Core; using BepInEx.Unity.Mono; using BepInEx.Logging; using BepInEx.Configuration; [BepInPlugin(com.example.mymod, MyMod, 1.0.0)] [BepInDependency(BepInEx.BepInEx, 5.0.0)] public class MyMod : BaseUnityPlugin { ConfigEntrybool _enabled; public override void Awake() { _enabled Config.Bind(General, Enabled, true, 开关); Logger.LogInfo(MyMod 已加载当前状态 _enabled.Value); } }编译出的 dll 丢进任意已装 BepInEx 的游戏的plugins/目录即可测试。Unity 侧的基类与链加载逻辑在 Runtimes/Unity/BepInEx.Unity.Mono/需要挂钩游戏方法时再引入 HarmonyX 做运行时补丁。游戏大版本更新后重新跑一遍清空 plugins → 逐个装回的流程是目前验证插件兼容性最直接的办法。现在就去把对应版本的 BepInEx 解压进游戏目录装第一个插件然后打开 LogOutput.log 看看它说了什么。【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考