BepInEx安装教程：让Unity游戏跑起第一个插件的完整快速上手指南

BepInEx安装教程：让Unity游戏跑起第一个插件的完整快速上手指南

【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx

BepInEx 是一款免费开源的 Unity 游戏插件与模组框架——把插件丢进一个文件夹，游戏启动时就会自动加载，帮你给游戏加功能、改数值。新手最常卡在三个地方：装不进去、插件不生效、报错看不懂。这篇指南把上手过程拆成 5 个可以独立完成的小任务，你做完任意一个就有实际收获，全部做完就能熟练驾驭 BepInEx。

🧭 任务一：把 BepInEx 装进游戏

🎯 为你的游戏选对 BepInEx 版本

BepInEx 支持三种运行环境，先确认你的游戏属于哪一种，再下载对应的发行包（仓库 README.md 里附有完整的平台兼容表）：

注意：版本选错是最常见的"装不上"原因，比如给 IL2CPP 游戏装标准版 Mono 包，游戏会直接闪退或毫无反应。

📂 解压 BepInEx 到正确位置

1. 下载与你系统匹配的 BepInEx 发行包
2. 解压到游戏根目录（就是能看到游戏启动文件game.exe的那一层）
3. 不要多套一层目录，也不要放进 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 安装成功

1. 启动一次游戏，等它正常进界面
2. 回到BepInEx/目录找LogOutput.log
3. 用文本编辑器打开，确认开头出现BepInEx版本号和Chainloader初始化字样

看到 Chainloader（插件链式加载器，负责逐个加载你的插件）成功启动，说明框架已接管游戏。

🧩 任务二：装一个插件并让它跑起来

📥 插件该放在哪个目录

把插件文件（通常是.dll）直接放进BepInEx/plugins/目录即可，不需要注册、不需要重启安装程序——下次启动游戏时 BepInEx 会自动扫描并加载。

注意：Windows 下下载的插件可能带有"来自其他计算机"标记，右键文件 → 属性 → 勾选"解除锁定"，否则加载可能失败。

🔍 插件加载成功长什么样

启动游戏后，打开BepInEx/LogOutput.log，找到与你插件名相关的行，正常情况你会看到类似Loading plugin xxx v1.0.0的条目，并紧跟插件自己的启动信息。每个插件在日志里都有自己的名字块（日志系统的设计见 BepInEx.Core/Logging/），按插件名过滤一下就能只盯自己的。

🔧 插件不生效怎么排查

按顺序试这三步，能覆盖九成问题：

1. 移除plugins/里其他所有插件，只留问题插件，重启游戏——排除互相冲突
2. 在日志中搜你的插件名，看它是否出现在"已加载插件"清单里：没出现说明 BepInEx 根本没扫到它，回到上一步检查目录；出现了但无效果说明插件内部出错，跳到任务四
3. 核对插件要求的 BepInEx 版本与你安装的版本是否匹配

⚙️ 任务三：用配置改变游戏行为

📄 插件的配置文件在哪里

每个插件的独立配置在BepInEx/config/下，文件名规则是作者名.插件名.cfg。比如插件BetterGame由Alice开发，文件就是Alice.BetterGame.cfg。全局设置（日志级别、重定向日志等）则在BepInEx/config/BepInEx.cfg。配置文件由框架自动生成和解析（实现位于 BepInEx.Core/Configuration/），你只管改值。

🛠 正确修改 BepInEx 配置的方法

配置使用 TOML 格式（一种"键 = 值"的简单格式，#开头是注释）：

[General] # 修改下面这一行即可，其他项别动 EnableFeature = true PlayerSpeed = 1.5

1. 修改前把.cfg复制一份备份
2. 只改=右边的值，不要动节名和键名
3. 保存为 UTF-8 编码，重启游戏生效

重要：配置文件会在下次启动时被框架重新加载，改错值顶多退回默认行为；但如果把文件整个删了，插件也会自动生成默认配置，所以改坏不用慌，删掉重来即可。

🚨 任务四：用日志定位报错

📜 LogOutput.log 到底是什么

LogOutput.log是 BepInEx 的磁盘日志监听器（源码 DiskLogListener.cs）每次启动游戏时重新写入的完整记录，从框架接管游戏到关闭，插件加载、配置读取、异常堆栈全在里面。文件打不开或被占用时，框架会自动另存为LogOutput.1.log、LogOutput.2.log……，取最新编号那份看。

日志每行开头带级别标记，含义如下：

🔎 日志里搜什么关键词

遇到"装不上 / 不生效 / 闪退"，直接全文搜索下面几个词：

• Failed to load→ 插件加载失败，后面的异常行就是原因
• Exception→ 任何未捕获异常的入口
• Dependency→ 插件缺依赖库
• 你的插件名 → 圈出该插件的完整日志段，看它自己报了什么错

定位到Error行后，答案通常就在它下面几行（异常消息 + 堆栈），把这段连同插件名一起保存，提问时贴出来别人能直接看懂。

🔬 任务五（进阶）：读懂源码与自行构建

🗺 源码目录对应什么功能

想弄清 BepInEx 内部如何工作，按这个地图看源码：

🏗 从源码构建 BepInEx

想改框架本身或学习构建流程，跟着 docs/BUILDING.md 走：

1. 安装 .NET 6.0 或更高版本的 SDK
2. 克隆仓库：git clone https://gitcode.com/GitHub_Trending/be/BepInEx
3. 进入仓库目录，按平台执行构建脚本

./build.sh --target Compile # Linux / macOS build.cmd --target Compile # Windows 命令行

注意：Compile目标会先自动拉取依赖再编译，产物在bin/下；要打包成可分发的发行包，改用--target MakeDist。

✅ 一份防翻车小清单

🔁 每次动插件或配置之前

1. 确认BepInEx/plugins/里没有嵌套的plugins目录
2. 修改.cfg前先复制一份备份
3. 启动一次游戏，扫一眼LogOutput.log有没有新增Error

📦 游戏大版本更新之后

1. 先备份整个BepInEx/目录
2. 逐个更新插件到兼容新版本
3. 再启动游戏验证日志干净

现在就去挑一个你最想魔改的游戏，解压 BepInEx、放进第一个插件，等LogOutput.log里出现 Chainloader 成功启动的那一刻，你就正式入门了——去跑通你的第一个插件吧！

【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx