如何用 BepInEx 6 给 Unity 游戏注入模组：新手完整指南

如何用 BepInEx 6 给 Unity 游戏注入模组新手完整指南【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInExBepInEx 是一个面向 Unity 和 .NET 游戏的插件框架让普通游戏装上模组就像放进一个 DLL 一样简单同时覆盖 Mono、IL2CPP、.NET 三种运行环境。这篇文章带你看懂它、装好它出问题时也知道先查哪里。一句话介绍BepInEx 是什么BepInEx 解决的问题很简单游戏官方不给你改代码的入口它就自己撬开一个。给谁用想给自己的 Unity 游戏装 Mod 的玩家以及想给游戏写插件的开发者。怎么工作在游戏启动流程的最前面插入自己然后扫描并加载你放进BepInEx/plugins目录里的插件 DLL。值得用的原因目前 Unity 模组圈事实上的标准框架Unity Mono 环境已有稳定版本6.0.0IL2CPP 与 .NETXNA/FNA/MonoGame环境也有对应支持。一个诚实的提醒 目前只有Unity Mono 有稳定发布版IL2CPP 版属于实验性质装机前先看你的游戏是哪种运行时下面教怎么判断。三分钟看懂原理为什么 IL2CPP 特别麻烦可以把两种运行时想象成菜谱还在不在厨房Mono 游戏自带 C# 程序集IL 字节码就像菜谱摆在明面上插件想改哪个方法直接查表就能找到。IL2CPP 游戏则把 C# 先编译成了 C 原生代码运行时菜谱已经不在插件根本不知道目标方法在哪。BepInEx 用两步解决这件事借门而入依赖 UnityDoorstopv4.5.0在游戏正式启动前截住启动流程先跑 BepInEx 的预加载器。重建现场Mono 下直接读取 DLL 即可IL2CPP 下先由 Cpp2IL 把原生代码逆向还原出 C# 图纸再用 Il2CppInteropv1.5.3在运行时现场重建类型插件的调用这才有了落点。上手走一遍从裸游戏到插件生效第一步备好 .NET 6 构建工具链做什么确认电脑上有 Git 和 .NET SDK构建脚本明确要求 .NET 6.0 或更新版本。关键点终端跑git --version和dotnet --info后者输出里SDK版本号 ≥ 6.0 即可。怎么判断成功两条命令都不报错且 dotnet 版本号符合要求。容易踩的坑⚠️只装了 .NET运行时不算数构建需要完整SDK另外别被 IL2CPP 需要的dotnet-runtime 6.0.7绕晕——那是打包进游戏目录的运行时和你构建机的 SDK 是两回事。第二步把源码拉下来并打包做什么克隆仓库用官方构建脚本一条命令完成拉依赖 → 编译 → 生成发行包。关键命令# 获取源码 git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx # 构建并生成可直接分发的压缩包输出在 bin/dist # 用 --target MakeDist 而不是 Compile省得自己手动打包 ./build.sh --target MakeDist # Windows 上对应 build.cmd --target MakeDist怎么判断成功bin/dist文件夹里出现了带版本号的分发包zip。容易踩的坑PowerShell 用户跑build.ps1前需允许脚本执行构建文档在 docs/BUILDING.md三个 targetCompile/MakeDist/Publish的区别都写在那里。第三步把框架文件铺进游戏目录做什么把发行包内容解压到游戏根目录让目录结构长这样游戏根目录/ ├── 游戏主程序.exe ├── doorstop_config.ini ├── libdoorstop.so或 .dll └── BepInEx/ ├── core/ ← 框架核心 DLL ├── plugins/ ← 你的插件 DLL 放这里 └── LogOutput.log怎么判断成功BepInEx/core里能看到BepInEx.Unity.Mono.Preloader.dll等核心文件根目录多了doorstop_config.ini。容易踩的坑路径里带中文或特殊字符时部分游戏加载程序集会失败源码注释里专门提到过游戏目录尽量用纯英文路径。第四步让门童知道该加载什么做什么doorstop_config.ini就是 UnityDoorstop 的开关面板核心只有两项必须正确。仓库里的默认配置在 Runtimes/Unity/Doorstop/Mono 版长这样; doorstop_config.ini 关键项Mono 版默认值 [General] enabled true ; 总开关必须是 true否则整个框架静默不工作 ; 游戏启动时第一个被执行的程序集路径错了直接白屏/闪退 target_assembly BepInEx\core\BepInEx.Unity.Mono.Preloader.dll [UnityMono] ; 告诉 Mono 优先从 BepInEx\core 找核心库避免用到游戏自带的旧版本 dll_search_path_override BepInEx\core怎么判断成功三项enabled、target_assembly、dll_search_path_override与上面一致若你的游戏是 IL2CPPtarget_assembly应指向BepInEx\core\BepInEx.Unity.IL2CPP.dll且还要填[Il2Cpp]段的coreclr_path和corlib_dir指向 dotnet 运行时目录。容易踩的坑先判断游戏类型——游戏目录里有Data/Managed/文件夹说明是 Mono只有Data/Plugins/x86_64/之类的原生库、没有 Managed多半是 IL2CPP。IL2CPP 版还不支持 macOS。第五步首跑并确认插件真的加载了做什么启动游戏Linux/macOS 可用发行包里的run_bepinex_mono.sh脚本拉起它会处理LD_PRELOAD这类环境细节等游戏进入主界面。怎么判断成功看两个信号——游戏里能看到 BepInEx 弹出的控制台窗口以及BepInEx/LogOutput.log里出现Chainloader initialized和逐条的Loading plugin ...记录。容易踩的坑游戏正常进了主界面不代表插件加载成功有些坏插件会被跳过一切以日志里的插件列表为准。游戏起不来或插件没反应三档自查法按先日志 → 再配置 → 后环境的顺序来每档两分钟内能给出结论。第一档先翻 LogOutput.log快速判断 1日志文件存在但很短、没有Chainloader initialized→ 说明 BepInEx 根本没启动问题出在 Doorstop 这一层直接进第二档。快速判断 2日志有ERROR但游戏能进 → 通常是某个插件与 BepInEx 版本不匹配插件编译时引用的 BepInEx 版本与当前不符会被拒绝加载看报错行指向哪个插件先把它移出 plugins 目录再重启就能确认是不是它。第二档再对一遍 doorstop_config.ini快速判断 1用grep -E enabled|target_assembly doorstop_config.ini扫一眼enabled是false就是总开关没打开。快速判断 2对照target_assembly指向的文件是否存在ls BepInEx/core/BepInEx.Unity.Mono.Preloader.dll。路径一个字符对不上预加载器就静默失败。第三档最后验环境和权限快速判断 1Linux确认libdoorstop.so和游戏主程序都在可执行目录、架构一致脚本会自动检测 x86/x64遇到 32 位游戏会明确报错。快速判断 2用file 游戏主程序看一眼产物类型——显示PE32说明这是 Windows 游戏你装错平台了IL2CPP 游戏还要确认 dotnet 运行时目录coreclr.dll所在位置确实存在。内部地图三个目录看懂 BepInEx 的分工目录职责什么时候要看它BepInEx.Preloader.Core/预加载器核心游戏主逻辑跑起来之前先执行负责接管启动流程、应用运行时修复游戏还没进主画面就退出时BepInEx.Core/框架本体插件链式加载、配置系统、日志系统都在这里插件加载异常、配置不生效时Runtimes/Unity/运行时适配层Mono 版、IL2CPP 版、Doorstop 配置与启动脚本判断游戏类型、改启动参数时其中最有价值的一份源码是 BepInEx.Core/Bootstrap/BaseChainloader.cs所有插件的筛选逻辑GUID 是否合法、版本是否匹配、依赖是否满足都写在这里插件被跳过时日志里的原因基本都能在这份文件里找到出处。IL2CPP 玩家如果想深挖互操作层重点看 Runtimes/Unity/BepInEx.Unity.IL2CPP/ 下的Il2CppInteropManager.cs。写在最后BepInEx 的价值与去向BepInEx 把给闭源游戏加模组这件以前需要逆向全家桶的事收敛成放一个 DLL 进 plugins 目录。它靠 UnityDoorstop 实现启动截断靠链式加载器管理插件生命周期靠运行时适配层抹平 Mono 和 IL2CPP 的差异。对普通玩家它是装 Mod 的入口对开发者它是最成熟的 Unity 插件开发基座。接下来值得关注两个方向一是 IL2CPP 支持从实验版走向稳定README 目前明确只有 Unity Mono 有稳定发布二是随底层 dotnet-runtime 从 6.0.7 向更新版本演进IL2CPP 环境的兼容性会持续改善。想继续深入从 docs/BUILDING.md 了解构建细节从 docs/CONTRIBUTING.md 了解社区协作方式仓库 README 中还列出了 Discord 社区入口。【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考