BepInEx安装教程让Unity游戏跑起第一个插件的完整快速上手指南【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInExBepInEx 是一款免费开源的 Unity 游戏插件与模组框架——把插件丢进一个文件夹游戏启动时就会自动加载帮你给游戏加功能、改数值。新手最常卡在三个地方装不进去、插件不生效、报错看不懂。这篇指南把上手过程拆成 5 个可以独立完成的小任务你做完任意一个就有实际收获全部做完就能熟练驾驭 BepInEx。 任务一把 BepInEx 装进游戏 为你的游戏选对 BepInEx 版本BepInEx 支持三种运行环境先确认你的游戏属于哪一种再下载对应的发行包仓库 README.md 里附有完整的平台兼容表你的游戏类型对应 BepInEx 运行时支持平台Unity Mono 游戏标准版目前唯一有稳定发布的版本Windows / macOS / LinuxUnity IL2CPP 游戏IL2CPP 版额外依赖 Doorstop 组件Windows / Linux.NET / XNA 游戏含 FNA、MonoGame.NET 版Windows 为主注意版本选错是最常见的装不上原因比如给 IL2CPP 游戏装标准版 Mono 包游戏会直接闪退或毫无反应。 解压 BepInEx 到正确位置下载与你系统匹配的 BepInEx 发行包解压到游戏根目录就是能看到游戏启动文件game.exe的那一层不要多套一层目录也不要放进 Steam 的安装父目录装好后目录应该长这样游戏根目录/ ├── game.exe ├── doorstop_config.ini # 钩子配置指向预加载器 └── BepInEx/ ├── core/ # BepInEx 核心程序集 ├── patchers/ # 补丁类插件 ├── plugins/ # 普通插件放这里 ├── config/ # 所有配置文件 └── LogOutput.log重要门面上的关键是doorstop_config.ini——它在游戏进程启动最早期把控制权交给 BepInEx 的预加载器预加载逻辑在源码 BepInEx.Preloader.Core/ 中它的配置模板可参考仓库里的 doorstop_config_mono.ini里面enabled true和target_assembly两项不能改坏。✅ 验证 BepInEx 安装成功启动一次游戏等它正常进界面回到BepInEx/目录找LogOutput.log用文本编辑器打开确认开头出现BepInEx版本号和Chainloader初始化字样看到 Chainloader插件链式加载器负责逐个加载你的插件成功启动说明框架已接管游戏。 任务二装一个插件并让它跑起来 插件该放在哪个目录把插件文件通常是.dll直接放进BepInEx/plugins/目录即可不需要注册、不需要重启安装程序——下次启动游戏时 BepInEx 会自动扫描并加载。注意Windows 下下载的插件可能带有来自其他计算机标记右键文件 → 属性 → 勾选解除锁定否则加载可能失败。 插件加载成功长什么样启动游戏后打开BepInEx/LogOutput.log找到与你插件名相关的行正常情况你会看到类似Loading plugin xxx v1.0.0的条目并紧跟插件自己的启动信息。每个插件在日志里都有自己的名字块日志系统的设计见 BepInEx.Core/Logging/按插件名过滤一下就能只盯自己的。 插件不生效怎么排查按顺序试这三步能覆盖九成问题移除plugins/里其他所有插件只留问题插件重启游戏——排除互相冲突在日志中搜你的插件名看它是否出现在已加载插件清单里没出现说明 BepInEx 根本没扫到它回到上一步检查目录出现了但无效果说明插件内部出错跳到任务四核对插件要求的 BepInEx 版本与你安装的版本是否匹配⚙️ 任务三用配置改变游戏行为 插件的配置文件在哪里每个插件的独立配置在BepInEx/config/下文件名规则是作者名.插件名.cfg。比如插件BetterGame由Alice开发文件就是Alice.BetterGame.cfg。全局设置日志级别、重定向日志等则在BepInEx/config/BepInEx.cfg。配置文件由框架自动生成和解析实现位于 BepInEx.Core/Configuration/你只管改值。 正确修改 BepInEx 配置的方法配置使用 TOML 格式一种键 值的简单格式#开头是注释[General] # 修改下面这一行即可其他项别动 EnableFeature true PlayerSpeed 1.5修改前把.cfg复制一份备份只改右边的值不要动节名和键名保存为 UTF-8 编码重启游戏生效重要配置文件会在下次启动时被框架重新加载改错值顶多退回默认行为但如果把文件整个删了插件也会自动生成默认配置所以改坏不用慌删掉重来即可。 任务四用日志定位报错 LogOutput.log 到底是什么LogOutput.log是 BepInEx 的磁盘日志监听器源码 DiskLogListener.cs每次启动游戏时重新写入的完整记录从框架接管游戏到关闭插件加载、配置读取、异常堆栈全在里面。文件打不开或被占用时框架会自动另存为LogOutput.1.log、LogOutput.2.log……取最新编号那份看。日志每行开头带级别标记含义如下级别含义你需要做什么Info正常流程记录无需处理Warn有异常但能继续留意是否影响功能Error某处失败了必须处理Debug细节日志排查时用 日志里搜什么关键词遇到装不上 / 不生效 / 闪退直接全文搜索下面几个词Failed to load→ 插件加载失败后面的异常行就是原因Exception→ 任何未捕获异常的入口Dependency→ 插件缺依赖库你的插件名 → 圈出该插件的完整日志段看它自己报了什么错定位到Error行后答案通常就在它下面几行异常消息 堆栈把这段连同插件名一起保存提问时贴出来别人能直接看懂。 任务五进阶读懂源码与自行构建 源码目录对应什么功能想弄清 BepInEx 内部如何工作按这个地图看源码目录职责BepInEx.Core/核心框架配置系统、日志、插件加载契约BepInEx.Core/Bootstrap/Chainloader负责扫描并加载插件BepInEx.Core/Contract/IPlugin.cs插件接口只暴露Info、Logger、Config三样Runtimes/Unity/Unity 适配层Mono / IL2CPP 两套Runtimes/NET/.NET 框架游戏适配层 从源码构建 BepInEx想改框架本身或学习构建流程跟着 docs/BUILDING.md 走安装 .NET 6.0 或更高版本的 SDK克隆仓库git clone https://gitcode.com/GitHub_Trending/be/BepInEx进入仓库目录按平台执行构建脚本./build.sh --target Compile # Linux / macOS build.cmd --target Compile # Windows 命令行注意Compile目标会先自动拉取依赖再编译产物在bin/下要打包成可分发的发行包改用--target MakeDist。✅ 一份防翻车小清单 每次动插件或配置之前确认BepInEx/plugins/里没有嵌套的plugins目录修改.cfg前先复制一份备份启动一次游戏扫一眼LogOutput.log有没有新增Error 游戏大版本更新之后先备份整个BepInEx/目录逐个更新插件到兼容新版本再启动游戏验证日志干净现在就去挑一个你最想魔改的游戏解压 BepInEx、放进第一个插件等LogOutput.log里出现 Chainloader 成功启动的那一刻你就正式入门了——去跑通你的第一个插件吧【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考