BepInEx 入门:从安装到首个插件
详解为 Unity 游戏安装 BepInEx、配置首个插件并查看日志,帮助模组作者快速建立可调试的运行环境。
- 1
确认游戏版本与兼容性
打开游戏目录,查看 Unity 版本及游戏类型,并对照 BepInEx 官方发布说明选择对应分支。Unity Mono、IL2CPP 与存档版本通常使用不同安装包。
- 2
下载匹配的 BepInEx
进入 GitHub Releases,下载与系统和游戏架构匹配的版本。若目标游戏已有 BepInEx,应先备份原文件,避免新旧程序集混用。
- 3
解压安装到游戏目录
把压缩包解压到游戏可执行文件所在目录,使 BepInEx 文件夹、winhttp.dll 等文件与主程序同级;随后启动游戏一次,让其生成配置与插件目录。
- 4
检查日志和插件目录
查看 BepInEx/LogOutput.log 确认初始化成功,并在 BepInEx/plugins 中放置插件 DLL。带依赖的插件应同时放入其要求的依赖程序集。
- 5
创建并加载首个插件
用 .NET SDK 创建类库,引用 BepInEx 核心程序集,继承 BasePlugin,在 Awake 中记录日志,再将生成的 DLL 放入 plugins 目录。
- 6
运行并排查插件
启动游戏,在 LogOutput.log 搜索插件名称或异常信息。若未加载,核对目标框架、程序集位数及依赖版本,并按日志逐项修正。
💡 实用技巧
- 优先使用游戏作者推荐的 BepInEx 分支
- 插件日志比单纯显示效果更易验证
- 修改前备份门锁类启动文件
- 用反编译器检查插件目标框架
⚠️ 常见坑
- IL2CPP 与 Mono 安装包不可混用
- DLL 仍被占用会导致替换失败
常见问题
Q:下载时怎么判断该选哪个安装包?
先查看游戏的 Unity 版本和游戏类型,再对照 BepInEx 官方发布说明选择分支。Unity Mono、IL2CPP 通常使用不同安装包,并需匹配系统与游戏架构,避免下载后无法初始化。
Q:安装包应该解压到哪个位置?
解压到游戏可执行文件所在目录,确保 BepInEx 文件夹、winhttp.dll 等文件与主程序同级。启动游戏一次后,再检查 BepInEx/LogOutput.log 确认初始化是否成功。
Q:插件放进去后没有生效该怎么查?
将插件 DLL 及所需依赖程序集放入 BepInEx/plugins,启动游戏后搜索 LogOutput.log 中的插件名称或异常信息。重点核对目标框架、程序集位数和依赖版本,并注意旧 DLL 被占用会导致替换失败。