BepInEx 完整实战手册快速为 Unity 游戏构建插件 MOD 框架避开所有常见坑【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInExBepInEx 是一个面向 UnityMono/IL2CPP与 .NETXNA、FNA、MonoGame游戏的插件/MOD 框架。本文用大白话讲清它的安装流程、启动机制、关键配置与高频踩坑帮你快速给游戏加上 MOD 加载能力并绕开 IL2CPP 环境下的兼容性陷阱。一个真实需求让普通游戏长出 MOD 入口假设你想给一款 Unity 游戏加个自定义 HUD或者改写它的游戏规则。麻烦在于游戏在你电脑里只是一个 exemacOS 上是 .app它没有任何加载第三方代码的入口——你往目录里扔再多 DLL 也没用。BepInEx 解决的就是这个问题它在游戏进程启动的最早期劫持执行流先把自己装进游戏然后建好一整套基础设施——插件扫描、依赖解析、配置管理、日志系统。从此你只需要把编译好的插件 DLL 丢进BepInEx/plugins目录游戏启动时就会自动加载它们。✅注意官方目前只有 Unity Mono 线有稳定发布IL2CPP 线偏实验性质README 中明确标注。选错运行时是新手最常问的问题进阶与选型一节会细讲。快速上手从零到跑通的四步第 1 步获取源码并构建git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx dotnet build BepInEx.sln -c Release 更省事的方式是用仓库自带的构建脚本见docs/BUILDING.mdLinux/macOS 下执行./build.sh --target CompileWindows 下执行build.cmd --target Compile它会拉取依赖并输出到bin/dist。第 2 步把构建产物部署到游戏根目录部署后的目录结构长这样后面讲配置时会反复用到游戏根目录/ ├── BepInEx/ │ ├── core/ # BepInEx 核心 DLL │ ├── plugins/ # 你的插件 DLL 放这里 │ ├── config/ # BepInEx.cfg 各插件的配置文件 │ └── cache/ └── doorstop_config.ini第 3 步配置注入入口在游戏 exe 同级目录放置doorstop_config.ini核心只有两项参考Runtimes/Unity/Doorstop/doorstop_config_mono.ini[General] enabled true target_assembly BepInEx\core\BepInEx.Unity.Mono.Preloader.dlltarget_assembly指定的是游戏第一件执行的事——BepInEx 的预加载器Preloader。第 4 步启动游戏验证一切正常的表现是弹出一个控制台窗口打印 BepInEx 版本号和加载到的插件列表BepInEx/config下生成BepInEx.cfg日志写入LogOutput.log。三条都满足就代表框架跑通了。核心机制游戏启动后 BepInEx 做了什么用一张流程图串起来文字版游戏 exe 启动 │ 进程最早期被 Doorstop 拦截 ▼ Preloader预加载器 │ 运行时修复IL2CPP 下生成托管类型桩 ▼ Chainloader链式加载器 │ 静态解析 plugins/ 里每个 DLL → 校验属性/GUID → 解析依赖 → 真正加载 ▼ 逐个调用插件入口Load → Awake → Update 生命周期每一层用类比拆开看Doorstop门口的保安。Unity 游戏本质是原生程序外部代码无法直接注入。Doorstop 在进程的第一条指令之前就接管了执行流把启动顺序改成先跑 BepInEx。它是最底层、和平台/位数最相关的一环。Preloader开工前的杂务。它先做运行时修复——比如把控制台输出重定向到可见位置见BepInEx.Unity.Mono.Preloader/RuntimeFixes/。在 IL2CPP 环境下它还承担最重的一块类型互操作。IL2CPP 互操作现场翻译。这是 IL2CPP 难点的核心。IL2CPP 游戏在编译期已把 C# 代码转成了 C 原生代码运行时根本不存在托管类型插件引用的 API 全是空气。BepInEx 内置的 Il2CppInteropUnhollower会读取游戏的global-metadata.dat元数据在运行时动态生成 C# 类型桩相当于把已被翻译成 C 的原文现场翻回 C# 给插件用。⚠️ 这一步失败就是 IL2CPP 崩溃和类型找不到的头号原因。Chainloader前台接待员。源码在BepInEx.Core/Bootstrap/BaseChainloader.cs。它不会一上来就加载 DLL而是先用 Cecil 做静态解析不执行任何游戏代码逐个校验有没有BepInPlugin属性、GUID 是否合法、目标 BepInEx 版本是否匹配再解析插件间依赖最后才真正加载并调用入口。配置与日志两个基础设施。ConfigFileBepInEx.Core/Configuration/ConfigFile.cs以线程安全的方式管理 TOML 配置文件Logger是一个发布-订阅中枢插件通过 Log Source 发消息控制台、文件、Unity 日志等 Listener 各自订阅见BepInEx.Core/Logging/Logger.cs。关键配置详解80% 场景只需要动这几项BepInEx 有两个主配置文件BepInEx/config/BepInEx.cfg框架行为和 exe 同级的doorstop_config.ini注入行为。BepInEx.cfg 常用项配置项默认值作用Logging.Console.Enabledtrue是否弹出独立控制台窗口Logging.Console.LevelInfo控制台输出最低日志级别Logging.File.Enabledtrue是否写入LogOutput.logLogging.File.LevelInfo文件记录的日志级别排障时可设 TraceLogging.File.InstantFlushfalse每条日志立即落盘调试用开着会拖慢游戏Unity.Logging.LevelInfo是否把 Unity 自己的Debug.Log转发进 BepInEx 日志doorstop_config.ini 常用项配置项作用enabled注入总开关排障第一步就是确认它为 truetarget_assembly注入后第一个执行的程序集必须存在且入口格式正确redirect_output_log把 Unity 的output_log.txt重定向到当前目录IL2CPP 专属[Il2Cpp]节下的coreclr_path和corlib_dir指向 CoreCLR 运行时与核心类库位置参考Runtimes/Unity/Doorstop/doorstop_config_il2cpp.ini路径指错直接起不来。高频踩坑现象 → 原因 → 解法坑 1游戏表现如常没有控制台、没有 LogOutput.log现象启动和没装 BepInEx 时一模一样目录里什么都没生成。原因Doorstop 根本没注入。最常见是两个原因——doorstop DLL 的位数x86/x64与游戏进程不匹配或target_assembly路径写错。解法先确认游戏是 32 位还是 64 位并选用对应位数的 doorstop再检查enabled true和程序集路径是否真实存在。坑 2控制台弹出了但加载的插件数为 0现象框架起来了日志里列出的插件数量是 0。原因Chainloader 有硬性校验见BaseChainloader.ToPluginInfoGUID 只允许字母、数字、.、_、-程序集必须引用 BepInEx.Core目标 BepInEx 版本不能比当前更新。任何一条不满足插件会被静默跳过但日志会打 Warning 说明原因。解法打开LogOutput.log搜 Warning日志会写明Skipping type [...] because its GUID [...] is of an illegal format这类具体理由按提示改属性即可。⚠️ 别跳过这一步去猜。坑 3IL2CPP 游戏启动崩溃或找不到类型现象Mono 游戏没事IL2CPP 游戏一启动就崩或日志报托管类型缺失。原因IL2CPP 运行时没有托管类型全靠 Il2CppInterop 从global-metadata.dat现场生成类型桩元数据路径或 Cpp2IL dump 输出路径配错生成就会失败。解法核对BepInEx.cfg中 IL2CPP 节的GlobalMetadataPath、UnityBaseLibrariesSource是否指向真实文件确认 dump 目录完整后重试。坑 4日志乱码或窗口一闪而过现象控制台文字全是乱码或游戏退出时控制台瞬间消失来不及看报错。原因Windows 控制台默认编码与日志内容不匹配日语游戏尤甚控制台窗口默认随进程关闭。解法在 BepInEx.cfg 中开启Console.Encoding.ShiftJis对应代码在BepInEx.Core/Console/ConsoleManager.cs排障期建议同时保持Logging.File.Enabled true文件日志不会闪没。坑 5改了插件配置配置文件却始终不生成现象代码里 Bind 了一堆配置项config目录里却没有对应文件。原因ConfigFile创建时并不落盘只有某个值被修改或手动调用Save()才写入SaveOnConfigSet默认为 true。解法调试期直接调一次Config.Save()或先修改任意值触发写入再观察文件内容。进阶与选型先选对运行时再谈调优运行时怎么选运行时成熟度适用场景Unity Mono稳定绝大多数 Unity 游戏首选Unity IL2CPP实验性大型单机/网游IL2CPP 后端需配 .NET 6 CoreCLR.NETXNA/FNA/MonoGame可用非 Unity 的 .NET 游戏经验法则Mono 能跑就别碰 IL2CPPIL2CPP 项目请预留额外排障时间。性能调优三个开关Logging.File.InstantFlush排障结束记得关掉——每条日志都同步刷盘高频日志场景下开销明显。程序集解析缓存BepInEx.Core/Bootstrap/TypeLoader.cs里有缓存开关大型插件集受益明显。IL2CPP 的原生函数挂钩有两种实现Dobby / Funchook见BepInEx.Unity.IL2CPP/Hook/INativeDetour.cs可通过配置切换遇到某种实现不稳定时换个试试。进阶方向BepInEx.Preloader.Core/Patching/提供了 Patcher 插件机制允许在程序集加载前对游戏 DLL 打补丁常用于修复被剥离的程序集或做深度运行时改造插件作者进阶的下一站。写在最后BepInEx 的本质是把一个普通游戏 exe变成一个带插件入口的框架Doorstop 负责进门Chainloader 负责接待Config 与 Logger 负责留痕。下一步建议先在 Unity Mono 线上跑通本文四步流程写一个最小插件实现BepInEx.Core/Contract/IPlugin.cs中的IPlugin验证加载 → 配置 → 日志闭环之后再挑战 IL2CPP 互操作。【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 BepInEx 完整实战手册：快速为 Unity 游戏构建插件 MOD 框架，避开所有常见坑
BepInEx 完整实战手册快速为 Unity 游戏构建插件 MOD 框架避开所有常见坑【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInExBepInEx 是一个面向 UnityMono/IL2CPP与 .NETXNA、FNA、MonoGame游戏的插件/MOD 框架。本文用大白话讲清它的安装流程、启动机制、关键配置与高频踩坑帮你快速给游戏加上 MOD 加载能力并绕开 IL2CPP 环境下的兼容性陷阱。一个真实需求让普通游戏长出 MOD 入口假设你想给一款 Unity 游戏加个自定义 HUD或者改写它的游戏规则。麻烦在于游戏在你电脑里只是一个 exemacOS 上是 .app它没有任何加载第三方代码的入口——你往目录里扔再多 DLL 也没用。BepInEx 解决的就是这个问题它在游戏进程启动的最早期劫持执行流先把自己装进游戏然后建好一整套基础设施——插件扫描、依赖解析、配置管理、日志系统。从此你只需要把编译好的插件 DLL 丢进BepInEx/plugins目录游戏启动时就会自动加载它们。✅注意官方目前只有 Unity Mono 线有稳定发布IL2CPP 线偏实验性质README 中明确标注。选错运行时是新手最常问的问题进阶与选型一节会细讲。快速上手从零到跑通的四步第 1 步获取源码并构建git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx dotnet build BepInEx.sln -c Release 更省事的方式是用仓库自带的构建脚本见docs/BUILDING.mdLinux/macOS 下执行./build.sh --target CompileWindows 下执行build.cmd --target Compile它会拉取依赖并输出到bin/dist。第 2 步把构建产物部署到游戏根目录部署后的目录结构长这样后面讲配置时会反复用到游戏根目录/ ├── BepInEx/ │ ├── core/ # BepInEx 核心 DLL │ ├── plugins/ # 你的插件 DLL 放这里 │ ├── config/ # BepInEx.cfg 各插件的配置文件 │ └── cache/ └── doorstop_config.ini第 3 步配置注入入口在游戏 exe 同级目录放置doorstop_config.ini核心只有两项参考Runtimes/Unity/Doorstop/doorstop_config_mono.ini[General] enabled true target_assembly BepInEx\core\BepInEx.Unity.Mono.Preloader.dlltarget_assembly指定的是游戏第一件执行的事——BepInEx 的预加载器Preloader。第 4 步启动游戏验证一切正常的表现是弹出一个控制台窗口打印 BepInEx 版本号和加载到的插件列表BepInEx/config下生成BepInEx.cfg日志写入LogOutput.log。三条都满足就代表框架跑通了。核心机制游戏启动后 BepInEx 做了什么用一张流程图串起来文字版游戏 exe 启动 │ 进程最早期被 Doorstop 拦截 ▼ Preloader预加载器 │ 运行时修复IL2CPP 下生成托管类型桩 ▼ Chainloader链式加载器 │ 静态解析 plugins/ 里每个 DLL → 校验属性/GUID → 解析依赖 → 真正加载 ▼ 逐个调用插件入口Load → Awake → Update 生命周期每一层用类比拆开看Doorstop门口的保安。Unity 游戏本质是原生程序外部代码无法直接注入。Doorstop 在进程的第一条指令之前就接管了执行流把启动顺序改成先跑 BepInEx。它是最底层、和平台/位数最相关的一环。Preloader开工前的杂务。它先做运行时修复——比如把控制台输出重定向到可见位置见BepInEx.Unity.Mono.Preloader/RuntimeFixes/。在 IL2CPP 环境下它还承担最重的一块类型互操作。IL2CPP 互操作现场翻译。这是 IL2CPP 难点的核心。IL2CPP 游戏在编译期已把 C# 代码转成了 C 原生代码运行时根本不存在托管类型插件引用的 API 全是空气。BepInEx 内置的 Il2CppInteropUnhollower会读取游戏的global-metadata.dat元数据在运行时动态生成 C# 类型桩相当于把已被翻译成 C 的原文现场翻回 C# 给插件用。⚠️ 这一步失败就是 IL2CPP 崩溃和类型找不到的头号原因。Chainloader前台接待员。源码在BepInEx.Core/Bootstrap/BaseChainloader.cs。它不会一上来就加载 DLL而是先用 Cecil 做静态解析不执行任何游戏代码逐个校验有没有BepInPlugin属性、GUID 是否合法、目标 BepInEx 版本是否匹配再解析插件间依赖最后才真正加载并调用入口。配置与日志两个基础设施。ConfigFileBepInEx.Core/Configuration/ConfigFile.cs以线程安全的方式管理 TOML 配置文件Logger是一个发布-订阅中枢插件通过 Log Source 发消息控制台、文件、Unity 日志等 Listener 各自订阅见BepInEx.Core/Logging/Logger.cs。关键配置详解80% 场景只需要动这几项BepInEx 有两个主配置文件BepInEx/config/BepInEx.cfg框架行为和 exe 同级的doorstop_config.ini注入行为。BepInEx.cfg 常用项配置项默认值作用Logging.Console.Enabledtrue是否弹出独立控制台窗口Logging.Console.LevelInfo控制台输出最低日志级别Logging.File.Enabledtrue是否写入LogOutput.logLogging.File.LevelInfo文件记录的日志级别排障时可设 TraceLogging.File.InstantFlushfalse每条日志立即落盘调试用开着会拖慢游戏Unity.Logging.LevelInfo是否把 Unity 自己的Debug.Log转发进 BepInEx 日志doorstop_config.ini 常用项配置项作用enabled注入总开关排障第一步就是确认它为 truetarget_assembly注入后第一个执行的程序集必须存在且入口格式正确redirect_output_log把 Unity 的output_log.txt重定向到当前目录IL2CPP 专属[Il2Cpp]节下的coreclr_path和corlib_dir指向 CoreCLR 运行时与核心类库位置参考Runtimes/Unity/Doorstop/doorstop_config_il2cpp.ini路径指错直接起不来。高频踩坑现象 → 原因 → 解法坑 1游戏表现如常没有控制台、没有 LogOutput.log现象启动和没装 BepInEx 时一模一样目录里什么都没生成。原因Doorstop 根本没注入。最常见是两个原因——doorstop DLL 的位数x86/x64与游戏进程不匹配或target_assembly路径写错。解法先确认游戏是 32 位还是 64 位并选用对应位数的 doorstop再检查enabled true和程序集路径是否真实存在。坑 2控制台弹出了但加载的插件数为 0现象框架起来了日志里列出的插件数量是 0。原因Chainloader 有硬性校验见BaseChainloader.ToPluginInfoGUID 只允许字母、数字、.、_、-程序集必须引用 BepInEx.Core目标 BepInEx 版本不能比当前更新。任何一条不满足插件会被静默跳过但日志会打 Warning 说明原因。解法打开LogOutput.log搜 Warning日志会写明Skipping type [...] because its GUID [...] is of an illegal format这类具体理由按提示改属性即可。⚠️ 别跳过这一步去猜。坑 3IL2CPP 游戏启动崩溃或找不到类型现象Mono 游戏没事IL2CPP 游戏一启动就崩或日志报托管类型缺失。原因IL2CPP 运行时没有托管类型全靠 Il2CppInterop 从global-metadata.dat现场生成类型桩元数据路径或 Cpp2IL dump 输出路径配错生成就会失败。解法核对BepInEx.cfg中 IL2CPP 节的GlobalMetadataPath、UnityBaseLibrariesSource是否指向真实文件确认 dump 目录完整后重试。坑 4日志乱码或窗口一闪而过现象控制台文字全是乱码或游戏退出时控制台瞬间消失来不及看报错。原因Windows 控制台默认编码与日志内容不匹配日语游戏尤甚控制台窗口默认随进程关闭。解法在 BepInEx.cfg 中开启Console.Encoding.ShiftJis对应代码在BepInEx.Core/Console/ConsoleManager.cs排障期建议同时保持Logging.File.Enabled true文件日志不会闪没。坑 5改了插件配置配置文件却始终不生成现象代码里 Bind 了一堆配置项config目录里却没有对应文件。原因ConfigFile创建时并不落盘只有某个值被修改或手动调用Save()才写入SaveOnConfigSet默认为 true。解法调试期直接调一次Config.Save()或先修改任意值触发写入再观察文件内容。进阶与选型先选对运行时再谈调优运行时怎么选运行时成熟度适用场景Unity Mono稳定绝大多数 Unity 游戏首选Unity IL2CPP实验性大型单机/网游IL2CPP 后端需配 .NET 6 CoreCLR.NETXNA/FNA/MonoGame可用非 Unity 的 .NET 游戏经验法则Mono 能跑就别碰 IL2CPPIL2CPP 项目请预留额外排障时间。性能调优三个开关Logging.File.InstantFlush排障结束记得关掉——每条日志都同步刷盘高频日志场景下开销明显。程序集解析缓存BepInEx.Core/Bootstrap/TypeLoader.cs里有缓存开关大型插件集受益明显。IL2CPP 的原生函数挂钩有两种实现Dobby / Funchook见BepInEx.Unity.IL2CPP/Hook/INativeDetour.cs可通过配置切换遇到某种实现不稳定时换个试试。进阶方向BepInEx.Preloader.Core/Patching/提供了 Patcher 插件机制允许在程序集加载前对游戏 DLL 打补丁常用于修复被剥离的程序集或做深度运行时改造插件作者进阶的下一站。写在最后BepInEx 的本质是把一个普通游戏 exe变成一个带插件入口的框架Doorstop 负责进门Chainloader 负责接待Config 与 Logger 负责留痕。下一步建议先在 Unity Mono 线上跑通本文四步流程写一个最小插件实现BepInEx.Core/Contract/IPlugin.cs中的IPlugin验证加载 → 配置 → 日志闭环之后再挑战 IL2CPP 互操作。【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考