Unity 游戏插件框架 BepInEx 安装教程从下载到跑通第一个插件的完整步骤【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx你往 plugins 文件夹里丢了一个插件 dll重启游戏什么反应都没有。八成不是插件的问题而是插件框架根本没被游戏加载——插件只是放在那里没人读它。BepInEx 是面向 Unity Mono、IL2CPP 和 .NET 游戏XNA、FNA、MonoGame 等的插件框架。它在游戏启动的瞬间把自己注入进程然后扫描并加载你放进 plugins 文件夹里的所有 dll负责依赖检查、加载排序和日志。目前只有 Unity Mono 版本有稳定发布IL2CPP 和 .NET 版本仍在推进其中 IL2CPP 不支持 macOS。先把几件事放明白它适合谁想给游戏装第三方模组的玩家以及要在上面写插件的开发者。装在哪游戏根目录和游戏可执行文件同一层不是游戏安装目录之外。一切问题的答案在哪BepInEx/LogOutput.log排障永远从这里开始。它不止是个插件加载器MelonLoader 等一堆加载器本身就是跑在 BepInEx 底层的。运行时WindowsLinuxmacOS当前状态Unity Mono✔✔✔有稳定版本文主线Unity IL2CPP✔✔✖仍在推进.NET / XNA✔MonoMono仍在推进先确认你的游戏是 Unity Mono游戏目录下有游戏名_Data文件夹且里面含Managed。再确认游戏是 32 位还是 64 位必须和你选的 BepInEx 包一致错配直接闪退。两种拿包方式新手走第一条新手路线到项目仓库的 Releases 发布页按操作系统和位数选对应的 zip。Windows x64 的 Unity Mono 游戏就选 win64 的 Mono 包。进阶路线从源码构建需要先装好 .NET 6.0 或更高版本git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx # Windows 命令提示符 build.cmd --target Compile # Windows PowerShell ./build.ps1 --target Compile # Linux ./build.sh --target CompileCompile只拉依赖并编译二进制要产出可分发的压缩包用Publish成品在bin/dist里。完整说明见 构建指南。解压到游戏根目录先看结构再启动把包解压到游戏根目录——和游戏可执行文件所在的同一层。解压完应该是这样游戏根目录/ ├── BepInEx/ │ ├── core/ # 框架核心 dll不要动 │ ├── plugins/ # 插件放这里 │ ├── patchers/ # 需要修改游戏代码的补丁类插件 │ └── config/ # 配置目录首次运行自动生成 ├── doorstop_config.ini └── 游戏主程序九成的人栽在这一步把压缩包里那层BepInEx文件夹整个又套进游戏目录里变成两层 BepInEx。BepInEx必须和游戏主程序平级多套一层启动时就读不到 core 里的核心 dll直接闪退或无日志。首次启动后用两个文件确认它真的注入了Windows 直接双击游戏可执行文件doorstop 钩子会自动接管启动。Linux 用发布包里的脚本把游戏可执行文件作为第一个参数传入./BepInEx/run_bepinex_mono.sh 游戏可执行文件相对路径脚本会自己校验游戏可执行文件是 32 位还是 64 位。如果你传进来的其实是 Windows 的 .exePE32它会直接拒绝启动并提示要走 Proton/Wine而不是静默失败——看到这个提示就说明包选错了。启动进游戏后再验证两条都满足才算装上BepInEx/LogOutput.log存在开头是这样一行[Info : Chainloader] BepInEx 5.x.x - 你的游戏名BepInEx/config/BepInEx.cfg被自动创建。两者都齐框架就算装上了。首次启动会慢一点它在扫描和注册插件属正常现象。插件装进 plugins重启看日志里多了什么装插件没有安装步骤也不需要注册就三步把插件的.dll放进BepInEx/plugins/。重启游戏。打开BepInEx/LogOutput.log确认出现这条记录[Info : Chainloader] 1 plugins to load [Info : Chainloader] Loading [插件名 1.0.0]N plugins to load的 N 就是你放进去的插件数量它比 0 大就说明扫描成功Loading [...]出现且后面不跟 Error这个插件就真正跑起来了。全局配置在 BepInEx.cfg大概率只用改两行全局配置是BepInEx/config/BepInEx.cfgTOML 格式磁盘日志相关的全在[Logging.Disk]段[Logging.Disk] # 默认是 Fatal,Error,Warning,Message,Info # 改成 Warning 后磁盘日志只剩警告及以上 LogLevels Warning # 默认就是 false每次启动覆盖旧日志而不是追加 AppendLog false说明一下默认值AppendLog默认已经是false每次启动都是干净的新日志这个基本不用动。真正值得改的是LogLevels——日常嫌日志长就收窄到Warning排查问题想全量留痕就保持默认。改完重启游戏生效判据就是新日志里不再或重新出现对应级别的行。 装完不生效对着日志逐条排除任何问题的第一步都是打开BepInEx/LogOutput.log。按看到什么 → 多半是什么 → 做什么处理日志里是0 plugins to load。多半是插件没进BepInEx/plugins/或者你又在套一层目录了。回上一层确认插件文件真实路径是游戏根目录/BepInEx/plugins/xxx.dll而不是游戏根目录/BepInEx/BepInEx/plugins/。游戏直接闪退甚至没生成LogOutput.log。多半是 BepInEx 包的位数和游戏不匹配或目录多套了一层导致注入前就崩。先用file核对游戏可执行文件是 32 位还是 64 位再核对目录结构不行就删掉重装对应版本。日志里有Skipping [xxx] because it has a dependency that was not loaded。多半是这个插件依赖的另一个插件没加载成功。往日志前面找那个依赖插件自己的 Error 行把链条上第一个报错的插件修好。日志里有Could not load [xxx] because it has missing dependencies: ...。行尾会列出缺的 GUID 和版本号按名字去装对应插件重启。日志里有Plugin [xxx] targets a wrong version of BepInEx (...) and might not work until you update。插件针对的 BepInEx 版本比你装的新升级 BepInEx 到 Releases 最新版。日志里完全没有Chainloader字样游戏却正常启动了。说明 doorstop 钩子没接管启动检查doorstop_config.ini里enabled是不是true、target_assembly指的路径是否真实存在然后重启。走得更远的两块IL2CPP 核对接管路径源码构建走完整流程如果你的游戏是 IL2CPP 编译的要核对doorstop_config.ini里的target_assembly指向正确的核心 dll。仓库 Runtimes/Unity/Doorstop 里有两个模板可以对照Mono 版指向BepInEx\core\BepInEx.Unity.Mono.Preloader.dllIL2CPP 版指向BepInEx\core\BepInEx.Unity.IL2CPP.dll后者还多了coreclr_path和corlib_dir两段 CoreCLR 路径配置见 doorstop_config_il2cpp.ini。写插件的话核心契约都在 BepInEx.Core/Contract 里一个最小插件就一个类[BepInPlugin(作者.GUID, 插件名, 1.0.0)] public class MyPlugin : BaseUnityPlugin { private void Awake() { Logger.LogInfo(插件已加载); } }装完在日志里看到自己插件的Loading [...]行就是闭环了。几条每次照做的规矩装任何新插件前先备份存档这是唯一出错后很难回滚的东西。版本只认 Releases 稳定版尝鲜版别用在主力存档上。每次装插件、改配置之后先打开BepInEx/LogOutput.log看一眼多数问题的答案就在里面。Linux 下启动报not compiled for x86 or x64说明包和游戏位数不匹配换对应位数的包别硬试。【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考