BepInEx Unity 插件框架完整安装指南从判定游戏类型到跑通第一个插件【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx上个月帮朋友装 BepInEx 插件文件放好之后游戏启动控制台窗口闪一下就退了。我打开框架留下的LogOutput.log只有一行doorstop_config.ini里的路径指向了不存在的文件。这类坑都可以绕开。BepInEx 是一个开源的 Unity 插件框架它在不动游戏本体文件的前提下把插件注入游戏进程并提供统一的加载、配置与日志环境。下面走完整个安装流程。 为什么要装 BepInEx三种官方不提供的 MOD拿三个典型例子。第一种角色状态面板。很多动作游戏只给一条稀疏的血条玩家想看耐力、技能冷却、减益状态官方不提供。插件在游戏渲染流程里挂一个钩子等游戏自己画完一帧后再往屏幕角落叠一层 HUD数据直接从游戏内存对象里取。第二种Boss 血条。Boss 经常有多段血量官方不显示。插件每帧在场景里找到 Boss 实体读取它的血量字段画在屏幕顶部。第三种地图自动标注。插件把你当前的坐标和一份预置的兴趣点列表做比对把关键点直接标在地图上。这些功能官方代码里没有游戏本体文件又不能动所以需要一套从外面进来的框架这就是 BepInEx 干的事。✅ BepInEx 安装前检查单游戏类型、版本、备份动手之前先勾完下面三项后面所有配置都依赖这里的判断。判定游戏类型。到游戏安装目录看文件名有UnityPlayer.dll→ Unity Mono有GameAssembly.dll→ Unity IL2CPP两者都没有、但游戏跑在 .NET 环境XNA、FNA、MonoGame 等→ .NET 类型。类型决定后面用哪套 doorstop 配置模板。选定版本线。5.x 是稳定老版适合老游戏6.x 是面向新引擎的重构版持续迭代Bleeding Edge 是每日构建的尝鲜版特性最新但变数也最大。拿不准就按插件作者声明的版本走。备份游戏目录。安装前完整复制一份原目录或者至少记下原有文件清单。真出问题时能一步还原。 三步装好 BepInEx获取文件 → 放置配置 → 启动验证第一步获取框架文件普通用户直接下载官方发布页的预编译包解压即用。想从源码自建的开发者需要 .NET 6.0 或更高版本git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx ./build.sh --target Publish构建产物输出在bin/dist目录各平台打包细节见 docs/BUILDING.md。第二步把文件放进游戏根目录并改 doorstop_config.ini把BepInEx目录整体复制到游戏根目录。Windows 包里会附带winhttp.dll和doorstop_config.iniLinux 下的注入库是libdoorstop.so。最终目录长这样游戏根目录/ ├─ BepInEx/ │ ├─ core/ # 框架核心程序集 │ ├─ plugins/ # 插件 DLL 放这里 │ └─ config/ # 首次启动后自动生成 ├─ doorstop_config.ini # 启动配置 ├─ winhttp.dll # 仅 Windows └─ 游戏主程序.exe / .x86_64注入是这样发生的启动时 preload 库先于游戏拿到执行权优先加载target_assembly指定的程序集也就是 BepInEx 的引导程序。进入程序后由 Chainloader 接手它扫描plugins/目录解析每个插件声明的依赖按正确顺序逐个加载每个插件都会拿到独立的日志器和自己的配置文件全部由框架统一收纳出错时日志里能直接定位到是哪个插件。接着打开doorstop_config.ini核对这几项[General] enabled true # 总开关必须是 true target_assembly BepInEx\core\BepInEx.Unity.Mono.Preloader.dll # 指定优先加载哪个引导程序集 [UnityMono] dll_search_path_override BepInEx\core # 部分游戏裁掉了核心库让 Mono 改从该目录找 core 库IL2CPP 游戏用另一套模板doorstop_config_il2cpp.ini里[General]的target_assembly换成BepInEx\core\BepInEx.Unity.IL2CPP.dll并且要在[Il2Cpp]段补上 CoreCLR 运行时路径coreclr_path和管理库目录corlib_dir两项都指向随包携带的dotnet目录。第三步启动游戏核对三个成功信号正常启动游戏对照下面三条启动时弹出控制台窗口滚动打印 BepInEx 的加载日志游戏顺利进入主界面没有闪退回到游戏目录能看到自动生成的BepInEx/plugins/、BepInEx/config/目录和LogOutput.log文件。三条信号齐了说明框架已经跑起来。之后任何插件 DLL 丢进plugins/重启游戏即生效。 BepInEx 排障从 LogOutput.log 切入的五步对照LogOutput.log的每条记录都是时间戳 级别 来源名格式来源名就是插件或框架的名字。出问题时先翻日志再对号入座现象游戏启动后毫无反应像框架根本没在。原因doorstop 没启用或target_assembly路径指向不存在的文件。动作核对enabled true打开程序集路径确认与实际文件一致。现象启动即闪退日志可能只有寥寥几行。原因IL2CPP 游戏套用了 Mono 模板或反过来。动作换成对应的 doorstop 配置模板补齐 CoreCLR 相关项。现象框架正常唯独某个插件没加载出来。原因插件与框架版本不匹配5.x 和 6.x 的 API 互不兼容。动作查插件要求哪个 BepInEx 版本再按该插件的来源名在日志里找它的报错行。现象LogOutput.log持续膨胀挤占磁盘。原因默认只追加、不做轮转。动作在BepInEx.cfg开轮转和大小上限见下文日志控制。现象Linux 下控制台无输出日志也没有新增。原因运行游戏的用户对游戏目录没有写权限。动作用目录所有者身份运行游戏或补上写权限。 进阶三项日志轮转、最小插件、多游戏模板日志控制编辑游戏目录下的BepInEx.cfg[Logging.Disk] MaxLogFileSize 1048576 # 单文件上限此处为 1MB LogRotation true # 超过上限自动轮转 MaxLogs 10 # 历史日志最多保留份数日常游玩把级别从Info提到Warning只留警告和错误日志更小、干扰也更少。写一个最小插件插件的最小形态继承BaseUnityPlugin挂一个BepInPlugin特性唯一 ID、名称、版本号[BepInPlugin(com.example.helloworld, HelloWorld, 0.1.0)] public class HelloWorldPlugin : BaseUnityPlugin { void Awake() Logger.LogInfo(HelloWorld 插件已加载); }编译成 DLL 放进plugins/下次启动就能在控制台看到以该插件来源名打出的那行字。多游戏复用配置模板在一台游戏上调好BepInEx.cfg与 doorstop 配置后把这套文件存档为模板。新装游戏时先复制模板只改target_assembly与dll_search_path_overrideIL2CPP 则改coreclr_path两处其余原样沿用重复劳动基本归零。下一步下次启动游戏后打开一次LogOutput.log看看里面有没有 Warnings。想细读配置从仓库里的两份模板入手doorstop_config_mono.ini 与 doorstop_config_il2cpp.ini。准备好后把上面那个 hello world 插件编译出来放进plugins/跑一次。【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考