BepInEx 6.0 完整指南：给 Unity 游戏装插件的开源框架，3 步跑起来
【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx
BepInEx 是一个免费开源的 Unity 游戏插件（Mod）框架，它能在游戏启动前"插队"加载你自己的 C# 代码，让游戏支持热修改、新功能和 Mod 生态。读完本文，你会知道它适合谁、如何构建部署、内部机制如何运转，以及新手最容易踩的几个坑。
谁适合用 BepInEx
- 给 Unity 游戏做 Mod 的玩家：想给单机游戏加功能、改数值，但游戏本体没有官方 Mod 入口，自己写 DLL 又无从下手。
- 游戏 Mod 作者：需要统一的插件加载、配置读取、日志输出，不想每个游戏都重复造轮子。
- 逆向工程爱好者：想研究 IL2CPP 编译后的游戏如何被动态代码接管，BepInEx 的互操作层就是最好的实战样本。
核心能力速览 ✅
| 特性 | 说明 |
|---|---|
| 三种运行时适配 | 同时支持 Unity Mono、Unity IL2CPP 与 .NET Framework（XNA/FNA/MonoGame），Mono 平台覆盖 Windows、macOS、Linux |
| 插件元数据契约 | 通过 BepInPlugin 特性声明 GUID、名称、版本与依赖，加载器自动校验并跳过非法插件 |
| 统一日志系统 | 控制台、磁盘双通道监听，Harmony 补丁日志也汇入同一体系，方便排查 |
| 程序集元数据缓存 | 用哈希缓存插件类型信息，插件越多启动扫描越快，可在配置中关闭 |
| 跨平台注入层 | 基于 Doorstop 在游戏主入口前接管启动流程，配置一个 ini 即可接入 |
快速上手：3 条命令构建
装好 .NET 6.0 或更高版本的 SDK 后：
git clone https://gitcode.com/GitHub_Trending/be/BepInEx cd BepInEx dotnet build BepInEx.sln -c Release产物统一输出到bin目录。想要发行包而不是裸二进制，可改用构建脚本：./build.sh --target Publish（Windows 用build.cmd），目标说明见 docs/BUILDING.md。部署时把产物拷入游戏目录，游戏启动会经 Doorstop 引导进入 BepInEx 流程。
它如何工作：像酒店门童一样"截胡"启动流程
把游戏进程想象成一位入住客人。Doorstop 是前台门童——客人在抵达房间（游戏主入口）之前先被他拦下，被改道去登记（加载 BepInEx 入口程序集）。登记完成后才放行进房间，此时 BepInEx 已经在游戏内部安插好了"自己的房间"。
进入后的分工是三层流水线，你可以对照源码逐层看：
- 注入层：Doorstop 读取 ini 配置，决定加载哪个入口程序集，见 Runtimes/Unity/Doorstop/ 下的两份配置模板
- 预加载层（Preloader）：修复运行时补丁、初始化日志与控制台、扫描程序集并做加载前修补，入口逻辑在
BepInEx.Unity.Mono.Preloader项目里 - 链式加载层（Chainloader）：把扫描到的插件像链条一样逐个装配，校验 GUID 与依赖关系，任一环节失败只跳过该插件而不拖垮整个游戏，核心实现在 BepInEx.Core/Bootstrap/
IL2CPP 场景多一步"翻译"：C# 已被编译成 C++，框架会在运行时重建类型映射并启动托管运行时，逻辑集中在BepInEx.Unity.IL2CPP项目的互操作管理器中。
实用技巧与避坑 📌
- 优先认准 Unity Mono 的稳定版。官方目前只有 Unity Mono 提供稳定发布，IL2CPP 与 .NET 后端属于持续迭代阶段，生产环境别冒进。
- GUID 一经发布就不要改。GUID 是插件的身份证号，加载器只接受字母、数字、点、下划线、连字符，格式非法的插件会被直接跳过。
- 崩溃先看
preloader_*.log。启动瞬间的静默异常会写进带时间戳的预加载日志，而不是主日志，多数"闪退"都在这里找到答案。 - 插件多就保留元数据缓存。默认开启的缓存通过程序集哈希判断是否失效，几十上百个插件时扫描开销会明显下降。
- 门控开关
ignore_disable_switch保持 false。除非文档明确要求，否则不要启用，它会让 Doorstop 忽略你的关闭指令，调试时极易误伤。
FAQ
BepInEx 6 能用于 IL2CPP 编译的游戏吗
可以，但按预览对待。框架内置了类型互操作与原生函数拦截能力，支持 Windows 与 Linux，macOS 暂不支持 IL2CPP。日常使用建议优先选择 Mono 后端的稳定版本。
插件一个都没加载，从哪开始查
顺序看三处：主日志中"加载了 X 个插件"一行确认扫描是否发生；检查插件目录是否真有文件；再翻preloader_*.log确认没有加载前崩溃。绝大多数情况是插件 DLL 与 BepInEx 版本不匹配，被元数据校验拦截。
Mono 和 IL2CPP 两种后端怎么选
由游戏本身决定，不由你决定。在 Unity Editor 的构建设置里可以看到脚本后端（Scripting Backend）。Mono 游戏直接用稳定版；IL2CPP 游戏则必须用带 CoreCLR 运行时的 IL2CPP 包，两者配置文件与目录结构不同，不能混用。
写在最后
BepInEx 的价值在于把"往游戏里塞代码"这件脏活收敛成了标准流程：门童拦截、预加载修补、链式装配，三层各司其职。对新手，你只需要稳定版加正确配置；对开发者，从 Bootstrap 到 IL2CPP 互操作层的源码都摊开在仓库里，值得逐层读一遍。动手前不妨先看仓库内的 docs/CONTRIBUTING.md 与 docs/BUILDING.md，社区讨论可以在官方 Discord 进行。
【免费下载链接】BepInExUnity / XNA game patcher and plugin framework项目地址: https://gitcode.com/GitHub_Trending/be/BepInEx
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
