BepInEx 使用指南给 Unity 游戏加装插件框架的完整方案【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInExBepInEx 是一个面向游戏模组的插件框架让 C# 编写的插件俗称 Mod能够被游戏在启动时自动加载并生效。它主要服务三类游戏Unity Mono 运行时、Unity IL2CPP 运行时以及 XNA / MonoGame 等 .NET 系游戏。读完这篇指南你会知道 BepInEx 能做什么、如何从零构建并装进游戏目录、它的启动链条长什么样以及出问题时该从哪里查起。先说清一个关键事实目前只有Unity Mono线提供稳定发布版本IL2CPP 支持可在 Windows 与 Linux 上使用但仍属于较新的能力macOS 上的 IL2CPP 与 ARM 平台暂不支持。选对运行时路线能少走大半弯路。BepInEx 解决什么问题普通玩家安装 Mod往往要手动替换游戏文件、祈祷不同 Mod 之间不打架。BepInEx 把这件事标准化了统一入口所有插件放进同一个plugins/目录框架负责发现、校验、按依赖顺序加载。统一基础设施每个插件自动获得独立的日志源和一份 TOML 配置文件不用再自己造轮子。行为修改能力内置对 HarmonyX一个运行时方法热补丁库的支持插件可以不改游戏原始代码就改变其行为。多运行时适配Mono 与 IL2CPP 走不同的加载通道但对插件作者暴露的 API 基本一致。安装步骤从源码到跑起来1. 准备工具链构建 BepInEx 需要 .NET 6.0 或更高版本的 SDK。仓库构建说明位于docs/BUILDING.md官方提供了基于 CakeBuild 的跨平台脚本Windows 下是build.cmd/build.ps1Linux 下是build.sh。拿到源码git clone https://gitcode.com/GitHub_Trending/be/BepInEx2. 构建产物在仓库根目录执行以 Linux 为例./build.sh --target CompileCompile目标会自动拉取依赖并编译各运行时二进制MakeDist会额外为每个分发目标打包Publish则再压缩成归档。仓库版本前缀在Directory.Build.props中统一维护当前为 6.0.0 系列。产物输出到bin/下的统一目录按目标运行时分文件夹存放。3. 放进游戏目录并改配置把构建产物部署到游戏根目录最终形成BepInEx/文件夹其中core/存放框架自身的 DLL。然后修改 Doorstop负责在游戏进程启动瞬间“截胡”的拦截组件的配置。Mono 与 IL2CPP 各有一份模板分别位于Runtimes/Unity/Doorstop/doorstop_config_mono.ini和doorstop_config_il2cpp.ini。Mono 配置里最需要确认的两项[General] enabled true target_assembly BepInEx\core\BepInEx.Unity.Mono.Preloader.dlltarget_assembly指向预加载器程序集路径写错是“游戏照常启动但没有任何日志”的头号原因。IL2CPP 配置还额外要求两项coreclr_path指向内置的 .NET 运行时核心库默认dotnet\coreclr.dll和corlib_dir托管核心库目录默认dotnet。Linux 与 macOS 用户通常不直接改 ini而是编辑随附的启动脚本Runtimes/Unity/Doorstop/run_bepinex_mono.sh或 IL2CPP 对应脚本把executable_name设为游戏可执行文件名然后赋予脚本可执行权限后运行。脚本内部会自行处理 32/64 位检测与库注入路径。工作原理BepInEx 的启动链条把整个流程想象成一条接力赛四棒依次交接Doorstop 拦截通过动态库预加载Linux 的LD_PRELOAD、macOS 的DYLD_INSERT_LIBRARIES在游戏进程初始化最早期插入libdoorstop读取上一步的 ini决定要不要接管。它还提供DOORSTOP_DISABLE环境变量作为“逃生门”置位后游戏会绕过 BepInEx 正常启动。预加载器PreloaderMono 线加载BepInEx.Unity.Mono.Preloader.dllIL2CPP 线加载BepInEx.Unity.IL2CPP.dll。这一棒负责修复环境如控制台输出、运行时小补丁并准备运行时上下文。链式加载器Chainloader核心代码在BepInEx.Core/Bootstrap/BaseChainloader.cs。它会扫描plugins/目录用 Cecil 静态分析每个程序集提取插件元数据GUID、名称、版本跳过 GUID 非法、版本缺失的插件再解析依赖与进程过滤条件后按序实例化。插件本体插件继承BaseUnityPlugin实现IPlugin契约见BepInEx.Core/Contract/IPlugin.cs自动拿到Info自身元数据、Logger独立日志源与Config专属配置文件三样东西。IL2CPP 的特殊之处IL2CPP 把 C# 编译成 C 原生代码后原始托管程序集并不存在于运行时。BepInEx 的处理方式是借助 Cpp2IL 与 Il2CppInterop 两个工具从原生二进制反推出生成互操作程序集写入BepInEx/interop/目录相关配置集中在Runtimes/Unity/BepInEx.Unity.IL2CPP/Il2CppInteropManager.cs中例如UpdateInteropAssemblies控制游戏更新后是否自动重新生成互操作层。原生函数拦截则依赖Runtimes/Unity/BepInEx.Unity.IL2CPP/Hook/下的 Dobby 与 Funchook 两套实现。常见问题排查出问题时优先看两个日志BepInEx 自己的BepInEx/LogOutput.log以及 Unity 控制台输出ini 中redirect_output_log可将其重定向到output_log.txt。现象一游戏启动正常但完全没有 BepInEx 日志检查doorstop_config_*.ini中enabled是否为truetarget_assembly路径是否真实存在注意 Windows 反斜杠与 Linux 正斜杠的差异。检查是否设置了DOORSTOP_DISABLE环境变量ignore_disable_switch项的作用就是忽略该变量一般保持false。Linux/macOS 下确认启动脚本中executable_name已填写且用脚本方式启动而非直接双击游戏。现象二日志显示“加载插件数为 0”插件 DLL 是否真的放在plugins/而非core/。插件引用的 BepInEx 版本比当前框架新大版本号不一致、次版本号更高链式加载器会直接拒绝属于“插件为 7.x 编写却装在 6.x 上”的典型错误。插件声明了依赖但游戏进程中不存在依赖目标或进程名过滤器[BepInProcess]不匹配。现象三IL2CPP 游戏启动即退出或类型缺失报错确认BepInEx/interop/已生成且与游戏版本匹配游戏大版本更新后需要重新生成。核对coreclr_path与corlib_dir指向的运行时文件齐全该线内置的是 dotnet-runtime 6.0.7。平台限制IL2CPP 线不支持 macOS 与 ARM遇到直接排除。现象四插件互相冲突用ConfigFile而非手写文件管理开关日志源按插件隔离搜索自己插件的 GUID 即可定位是哪一个先抛错。插件开发上手一个最小插件需要三件事用特性声明元数据[BepInPlugin(com.you.mymod, My Mod, 1.0.0)]GUID 只允许字母数字及. _ -。继承BaseUnityPlugin在Awake()里做轻量初始化。需要改游戏行为时引用 HarmonyX 打补丁需要用户可调参数时用Config.Bind绑定到 TOML 配置。配置系统本身支持自定义类型转换Runtimes/Unity/BepInEx.Unity.Mono/UnityTomlTypeConverters.cs展示了为 Unity 类型注册转换器的做法也支持可接受值范围与列表校验见BepInEx.Core/Configuration/目录。几条减少坑的实践静态构造函数里别做重活资源加载放在协程里分帧完成反射能换成编译期引用就换掉卸载时释放非托管资源。下一步做什么✅ 装好后先跑一次“空载”不放任何插件启动游戏确认日志中出现框架版本与插件目录扫描记录。再放入一个已知可用的简单插件验证LogOutput.log中有其初始化记录。计划写插件的话先在BepInEx.Core/Contract/与Bootstrap/两个目录通读一遍契约与加载流程这比读任何教程都更接近真实约束。升级游戏或框架大版本后重新核对互操作层IL2CPP与插件引用的 BepInEx 版本这是回归故障最多的两个点。按上面顺序走一遍BepInEx 从“装进去”到“查得出问题”的路径就完整了。【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考