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

如何用 BepInEx 6 给 Unity 游戏装模组新手完整指南【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInExBepInEx 是面向 Unity 与 .NET 游戏的插件框架让不给修改入口的游戏装起 Mod 就像放一个 DLL 那么简单同时覆盖 Mono、IL2CPP 与 .NET 三种运行环境。这篇文章带你看懂原理、从零跑通一次构建安装出问题也知道先查哪里。项目名片给谁用想给自己的 Unity / .NET 游戏装 Mod 的玩家以及想给游戏写插件的开发者。一句话原理在游戏正式启动前用 UnityDoorstop 截住启动流程然后扫描并逐个加载你放进BepInEx/plugins目录里的插件 DLL。值得用的原因Unity 模组圈事实上的标准框架放一个 DLL 进 plugins 目录就生效这套玩法就是它定下来的——Mono、IL2CPP、.NETXNA/FNA/MonoGame 等三种环境都有对应支持。诚实边界目前只有 Unity Mono 有稳定发布版IL2CPP 属于实验性质且不支持 macOS。装机前先看你的游戏是哪种运行时下文教你判断。用一个比喻看懂原理酒店的前台与管家先打一个比方。游戏就是一家酒店官方没留任何加开房间的口子。BepInEx 干的事是门口保安UnityDoorstop在前台之前先拦住你塞给你一张访客证BepInEx 预加载器然后管家链式加载器拿着访客证核对来宾名单插件——证件号GUID格式对不对、房型编译时对应的 BepInEx 版本匹不匹配、他带的同伴依赖插件在不在名单上都合格了才发钥匙。要是酒店原来的来宾登记簿丢了IL2CPP 的情况管家会先请个修复师Cpp2IL从旧材料把登记簿复原出来再谈入住。实际流程是这三步门口拦截靠 UnityDoorstopv4.5.0通过LD_PRELOAD这类环境变量预注入libdoorstop在游戏主逻辑跑起来之前先执行 BepInEx 的预加载程序集BepInEx.Unity.Mono.Preloader.dll启动流程在这一刻被截住。重建名单Mono 下游戏程序集就是 C# IL 字节码插件直接查表就能找到要改的方法IL2CPP 把 C# 编译成了 C 原生代码就用 Cpp2ILv2022.1.0先逆向还原出 C# 名单再由 Il2CppInteropv1.5.3在运行时重建类型引用插件的调用这才有了落点。逐个入住链式加载器扫描BepInEx/plugins目录校验每个插件的 GUID、BepInEx 版本、依赖声明按拓扑排序排好加载顺序再逐个构造插件实例——这就是发钥匙。从零跑通源码构建到插件生效第 1 步备好 .NET SDK拉下源码目标把构建工具链备齐源码拿到手。操作# 确认两样工具是否就位 git --version # 应输出 git 版本号 dotnet --info # 看输出里 SDK 一栏的版本号要求 6.0 # 拉源码并进入目录 git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx验收信号dotnet --info的SDK段版本号 ≥ 6.0本地出现带BepInEx.sln的BepInEx目录。避坑警示⚠️只装 .NET运行时不算数构建需要完整SDK另外别被 IL2CPP 依赖的dotnet-runtime 6.0.7绕晕——那是以后要打包进游戏目录的运行时跟你构建机的 SDK 是两回事。第 2 步一条命令构建出生成分发包目标一次跑完拉依赖 → 编译 → 生成发行包。操作# Linux / macOS 用 bash 脚本 ./build.sh --target MakeDist # Windows 命令行 build.cmd --target MakeDist # Windows PowerShell先启用脚本执行策略否则会被拦截 ./build.ps1 --target MakeDist用--target MakeDist而不是Compile的原因它直接在bin/dist里生成可分发的包省掉你手动打包的环节。验收信号bin/dist目录里出现带版本号的分发包zip。避坑警示⚠️PowerShell 报无法加载脚本是执行策略拦的先去设置里放开三个 targetCompile/MakeDist/Publish的差别都写在 docs/BUILDING.md 里。第 3 步把框架铺进游戏目录目标让游戏根目录长出一套符合启动要求的结构。操作把发行包内容解压到游戏根目录结构应该是这样游戏根目录/ ├── 游戏主程序 # Windows 是 .exeLinux 是同名可执行文件 ├── doorstop_config.ini # UnityDoorstop 的开关面板 ├── libdoorstop.so # 启动拦截库Windows 是 .dllmacOS 是 .dylib └── BepInEx/ ├── core/ # 框架核心 DLLPreloader、Core 等 ├── plugins/ # 你的插件 DLL 放这里 └── LogOutput.log # 首跑后由框架写出验收信号BepInEx/core里能看到BepInEx.Unity.Mono.Preloader.dll等核心文件游戏根目录多了doorstop_config.ini。避坑警示⚠️路径里带中文或特殊字符时部分游戏加载程序集会直接失败——游戏目录尽量用纯英文路径。第 4 步核对 doorstop_config.ini 的三个关键项目标确认 Doorstop 的开关都拧对预加载器能被正确指到。操作仓库里的默认配置在 Runtimes/Unity/Doorstop/Mono 版关键项长这样[General] enabled true # 总开关false 时整个框架静默不工作 target_assembly BepInEx\core\BepInEx.Unity.Mono.Preloader.dll # 启动时第一个执行的程序集 [UnityMono] dll_search_path_override BepInEx\core # 让 Mono 优先从 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只有原生库、没有 Managed 的多半是 IL2CPP。IL2CPP 版还不支持 macOS。第 5 步首跑游戏确认插件真的加载了目标用日志而不是游戏能进主界面证明插件加载成功。操作# Linux/macOS 可用发行包里的启动脚本它会替你处理 LD_PRELOAD 等环境细节 ./run_bepinex_mono.sh脚本本体见 Runtimes/Unity/Doorstop/run_bepinex_mono.shWindows 用户直接双击游戏主程序即可。验收信号游戏里弹出 BepInEx 控制台窗口且BepInEx/LogOutput.log里出现Chainloader initialized和逐条的Loading [插件名]记录。避坑警示⚠️能正常进主界面 ≠ 插件加载成功——坏插件会被跳过一切以日志里的插件列表为准。出问题时的症状自查症状一启动后没有控制台窗口日志很短症状表现游戏开着或根本没开起来LogOutput.log很短没有Chainloader initialized也看不到 BepInEx 控制台窗口。最可能原因BepInEx 压根没启动问题出在 Doorstop 这一层——总开关关着或target_assembly指向了一个不存在的路径。验证操作# 扫一眼配置里两个最关键的项 grep -E enabled|target_assembly doorstop_config.ini # 再确认指向的文件真的存在 ls BepInEx/core/BepInEx.Unity.Mono.Preloader.dll修复办法enabled是false就改成true路径与文件差一个字符都对不上改成真实路径目录建议纯英文后重启。症状二游戏正常进主界面但插件没反应症状表现日志里有Could not load或Skipping字样游戏也能进但对应插件的效果在里面试不出来。最可能原因那个插件编译时引用的 BepInEx 版本和当前装的不匹配或者它声明的依赖插件缺失 / 版本不满足要求。验证操作# 找出报错行指向的是哪个插件 grep -E Could not load|Skipping BepInEx/LogOutput.log修复办法把报错指向的插件 DLL 移出plugins目录重启一次确认锅是不是它确认后再装齐缺失的依赖或把插件更新到匹配当前 BepInEx 大版本的构建。症状三Linux 上一启动就报错退掉症状表现跑启动脚本或直接执行可执行文件时立刻报错提示可执行文件类型不对。最可能原因架构不匹配32 位游戏装到 64 位环境或者这是个 Windows 二进制PE32你给它装了 *nix 版的 BepInEx。验证操作# 看一眼产物的真实类型 file 游戏主程序修复办法输出含PE32说明是 Windows 游戏应换 Windows 版 BepInEx经 Wine/Proton 跑32 位游戏则确认libdoorstop.so选的是 x86 版本。整体自查顺序一句话先翻日志框架到底启动没有→ 再核配置开关和路径对不对→ 最后验环境架构与产物类型。核心文件导航模块 / 文件职责什么时候看它BepInEx.Preloader.Core/预加载器核心在游戏主逻辑之前执行接管启动流程、应用运行时修复游戏还没进主画面就退出时BepInEx.Core/Bootstrap/框架本体插件发现、筛选、排序与加载全在这插件被跳过、加载顺序异常时BepInEx.Core/Configuration/配置系统TOML 解析、类型转换、取值校验配置项不生效、默认值不符合预期时Runtimes/Unity/运行时适配层Mono 版、IL2CPP 版、Doorstop 默认配置与启动脚本判断游戏类型、改启动参数时Il2CppInteropManager.csIL2CPP 互操作层负责在运行时重建类型引用想深挖 IL2CPP 支持链路时最值得一读的是 BepInEx.Core/Bootstrap/BaseChainloader.cs所有插件的筛选逻辑都写在这里——GUID 是否合法、目标 BepInEx 版本是否匹配、依赖是否满足、加载顺序怎么排每条被跳过时的日志文案都紧挨着对应的continue。插件被跳过时日志里的原因基本都能在这份文件里找到出处。写在最后BepInEx 把给闭源游戏加模组这件以前需要逆向全家桶的事收敛成了往plugins目录放一个 DLL——门口拦截、逐个入住、运行时适配各司其职。接下来值得关注两个方向一是 IL2CPP 支持从实验性质走向稳定README 目前明确只有 Unity Mono 有稳定发布二是随底层dotnet-runtime当前 v6.0.7向新版本演进IL2CPP 环境的兼容性会持续改善。想继续深入从 docs/BUILDING.md 了解三种构建 target 的细节从 docs/CONTRIBUTING.md 了解社区协作方式仓库 README 里还列有官方 Discord 社区入口。【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考