BepInEx 6.0 终极指南：5步快速搭建Unity游戏插件框架并跑通第一个模组

BepInEx 6.0 终极指南5步快速搭建Unity游戏插件框架并跑通第一个模组【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx 想给Unity游戏打模组官方渠道却全是封闭的BepInEx是面向 Unity Mono、Unity IL2CPP 和 .NET 系游戏的插件/模组框架它让游戏启动时就加载你自己的模组代码还能挂钩游戏自身的方法。本文带你过一遍环境准备、构建、写插件和部署一次跑通。 项目概览一个框架注入三种运行时BepInEx全称 Bepis Injector Extensible让你不改一行游戏代码只要把插件 DLL 放进游戏目录框架就会在启动时加载并运行它。它覆盖三种运行时环境运行时WindowsmacOSLinuxARMUnity Mono✔️✔️✔️N/AUnity IL2CPP✔️❌✔️❌.NET / XNA✔️MonoMonoN/A上表来自官方 README 的平台兼容表。以本文写作时为准仓库主分支处于 6.0.0 预发布阶段稳定发行版只覆盖 Unity Mono 线5.x 最新标签为 v5.4.23.5许可为 LGPL-2.1。 快速上手三步从克隆到加载第一个插件第一步克隆并构建源码构建脚本要求 .NET 6.0 或更高 SDK要求见 docs/BUILDING.mdgit clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx ./build.sh --target MakeDist # Windows 用 build.cmd构建结束后bin/dist目录会出现可分发安装包只想编译就用--target Compile。第二步部署到游戏目录把发行包放进游戏目录形成BepInEx/core框架核心程序集与BepInEx/plugins你放模组的位置。启动脚本和 Doorstop 配置由框架提供Linux/macOS 下指定游戏可执行文件即可./run_bepinex_mono.sh ./MyGame.x86_64第三步验证加载结果启动游戏看控制台两件事BepInEx 横幅以及加载了几个插件。日志同时写入BepInEx/LogOutput.log。插件数量大于 0说明环境就绪。 核心模块深挖三个关键机制逐个看Doorstop 引导链BepInEx 如何进入游戏进程这回答了框架凭什么抢得先手。BepInEx 依赖 UnityDoorstopv4.5.0README 列出的核心库之一Linux 用LD_PRELOAD、macOS 用DYLD_INSERT_LIBRARIES在游戏进程早期预载一个共享库等游戏入口点执行前先加载配置里target_assembly指定的预加载程序集Unity MonoBepInEx/core/BepInEx.Unity.Mono.Preloader.dllUnity IL2CPPBepInEx/core/BepInEx.Unity.IL2CPP.dll另需指定 CoreCLR 路径coreclr_path配置模板在 Runtimes/Unity/Doorstop/可用DOORSTOP_DISABLE环境变量临时禁用整条链。Chainloader插件依赖解析与加载顺序这决定你的插件能不能跑得稳。BepInEx.Core/Bootstrap/ 里的链式加载器用 Cecil 静态解析 plugins 目录下的 DLL读取[BepInPlugin]、[BepInDependency]、[BepInProcess]特性解析出依赖顺序再逐个实例化。一个最小插件长这样[BepInPlugin(com.example.mymod, MyMod, 1.0.0)] [BepInProcess(MyGame)] public class MyMod : BaseUnityPlugin { void Awake() Logger.LogInfo(Hello from BepInEx!); }BaseUnityPlugin见 BaseUnityPlugin.cs自带Logger和Config两个属性每个插件自动获得一份以 GUID 命名的独立配置文件。IL2CPP 支持在原生游戏里跑 CoreCLRIL2CPP 把 C# 编译成原生 C传统托管补丁全部失效。BepInEx 的方案是在游戏进程里装一个完整的 .NET 6.0.7 CoreCLR用 Cpp2ILv2022.1.0把游戏原生代码反编回 IL再用 Il2CppInteropv1.5.3把类型重新绑定到托管对象上原生函数拦截由 Dobby 和 Funchook 两套 Hook 实现承担见 Hook 目录。该线支持 Windows 和 Linux不支持 macOS 与 ARM。 常见报错速查5个高频现象与解法❗现象游戏正常启动但插件加载数为 0原因预加载程序集没被注入游戏走了原流程。 解决核对 doorstop 配置里target_assembly是否指向正确的 dllLinux 下确认游戏可执行文件位数与 libdoorstop 一致。❗现象日志立刻报 BepInPlugin attribute is missing原因继承了BaseUnityPlugin却忘了挂[BepInPlugin]特性这个检查发生在构造阶段。 解决补上特性GUID 一旦发布就不要改。❗现象插件没加载日志提示依赖版本不满足原因BepInEx 6 改了版本语义——[BepInDependency(xxx, 1.2.0)]现在是精确匹配不再是1.2.0 及以上。 解决改用区间写法如1.2.0。❗现象Linux 下脚本拒绝启动提示必须用 Wine/Proton原因启动脚本里的executable_name指向了 Windows 的 PE32 可执行文件。 解决指向游戏的 Linux 可执行文件玩 Windows 游戏请用 Proton 并安装 Windows 版 BepInEx。❗现象IL2CPP 游戏里补丁不生效、类型绑定失败原因CoreCLR 运行时或托管库路径没配对。 解决确认 doorstop 配置中coreclr_path dotnet\coreclr.dll、corlib_dir dotnet指向发行包内的 dotnet 目录再看日志定位。 一句话收束与资源索引BepInEx 把改游戏变成装插件注入链路跑通之后剩下的就是普通的 C# 开发。常用资料均为仓库内相对路径构建指南docs/BUILDING.md贡献指南docs/CONTRIBUTING.md核心框架链式加载、配置、日志BepInEx.Core/Mono 预加载器Runtimes/Unity/BepInEx.Unity.Mono.Preloader/IL2CPP 运行时Runtimes/Unity/BepInEx.Unity.IL2CPP/Doorstop 配置与启动脚本Runtimes/Unity/Doorstop/许可声明LICENSE【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考