MelonLoader 快速上手教程：5 分钟为 Unity 游戏装好 Mod 加载器
【免费下载链接】MelonLoaderThe World's First Universal Mod Loader for Unity Games compatible with both Il2Cpp and Mono项目地址: https://gitcode.com/gh_mirrors/me/MelonLoader
MelonLoader 是一款通用的 Unity 游戏 Mod 加载器，也是市面上少有的同时支持 Il2Cpp 和 Mono 两种 Unity 运行时架构的开源方案。你不需要再为不同游戏维护不同的注入工具，一个加载器就能覆盖新旧两代 Unity 项目。它通过一个"代理 DLL"在游戏启动时抢先加载自身，随后把插件（Plugins）和模组（Mods）注入到游戏进程中运行。
本文面向想给自己的 Unity 游戏加装 Mod 的玩家和想写 Mod 的开发者，从安装到日常排错一次讲清楚。
先分清你的游戏属于哪种架构
装之前花 30 秒确认游戏用的是哪种运行时，这直接决定你的准备事项：
| 运行时 | 典型特征 | MelonLoader 的额外要求 |
|---|---|---|
| Mono（Unity 传统脚本运行时） | 游戏目录下有Managed文件夹 | 无额外依赖 |
| Il2Cpp（C# 编译为原生 C++） | 有Game.il2cpp、Game_Data内无托管 DLL | 需要 .NET 6.0 Desktop Runtime（Windows 下由 MelonLoader 自动安装） |
简单判断方法：看游戏安装目录里是否存在Game_Data/Managed文件夹，有就是 Mono。Il2Cpp 游戏在首次启动时，MelonLoader 会在后台用 Cpp2IL 等工具把原生代码转回 C# 程序集并缓存到MelonLoader/Il2CppAssemblies目录，所以第一次启动会比平时慢一些，属于正常现象。
MelonLoader 安装步骤：三条路径任选
路径一：官方安装器（推荐）。从发布页下载对应平台的安装器（Windows 的MelonLoader.Installer.exe、Linux 的MelonLoader.Installer.Linux、macOS 的MelonLoader.Installer.MacOS.dmg），运行后选择游戏目录即可。Linux 用户需要先赋予执行权限：
chmod +x MelonLoader.Installer.Linux ./MelonLoader.Installer.Linux路径二：手动安装。适合想完全掌控每一步的用户，只需三步：
- 关闭游戏，下载发布页的 MelonLoader 压缩包
- 把压缩包中的
MelonLoader文件夹解压到游戏安装目录 - 把压缩包里的
version.dll和dobby.dll放到游戏安装目录根下
路径三：源码编译。想改加载器本身可以克隆仓库后编译，仓库内置了compile.sh脚本，核心就是带平台参数跑dotnet build：
git clone https://gitcode.com/gh_mirrors/me/MelonLoader cd MelonLoader bash compile.sh 0.7.3 win x64 Release卸载时把version.dll和MelonLoader文件夹删掉即可；若想彻底清干净，可再删Plugins、Mods、UserData三个目录。
装完之后游戏目录长这样
启动一次游戏后，MelonLoader 会自动创建以下结构，这也是你日常放 Mod 的位置：
游戏根目录/ ├── version.dll # 代理 DLL，游戏启动时加载它的"钩子" ├── MelonLoader/ # 加载器本体与缓存 │ ├── Logs/ # 运行日志，排错主要看这里 │ └── Il2CppAssemblies/ # Il2Cpp 游戏的程序集缓存 ├── Plugins/ # 插件目录（面向框架类扩展） ├── Mods/ # 模组目录，每个 Mod 一个文件夹 │ └── MyMod/ │ ├── manifest.json # Mod 元信息清单 │ └── MyMod.dll # Mod 主程序集 └── UserData/ └── Loader.cfg # 加载器主配置（TOML 格式）关于"插件"和"模组"的区分：Plugins 更偏向功能框架和底层扩展，Mods 是面向玩家的具体内容，两者可以共存且加载顺序上插件先于模组。
两个容易忽略的小机制值得知道（实现见 MelonLoader/Melons/MelonFolderHandler.cs）：
- 子文件夹也会被扫描，但子文件夹内必须包含
manifest.json才会被识别，方便大型 Mod 包分目录管理 - 重命名即禁用：把 Mod 文件夹改名为
Broken、Retired、Disabled或加~、.前缀，加载器就会跳过它，不用来回删文件
核心配置：Loader.cfg 与启动参数
配置文件在UserData/Loader.cfg，首次运行后自动生成。你 90% 的调参需求集中在前两个分区：
[loader] disable = false # 置 true 等于不加载任何 Mod debug_mode = true # 调试模式，开发时打开 capture_player_logs = true # 连 Unity 被禁用的日志也一并捕获 theme = "Normal" # 控制台主题，可选 "Lemon" [console] hide_console = false # 隐藏控制台窗口 console_on_top = false # 控制台始终置顶不想改文件的话，几乎所有配置项都对应一个启动参数，效果等价：
| 启动参数 | 作用 |
|---|---|
--no-mods | 本次启动不加载任何插件和模组 |
--melonloader.debug | 开启调试模式 |
--melonloader.hideconsole | 隐藏控制台 |
--melonloader.consolemode=4 | 切换 Lemon 主题（0 为 Normal） |
--quitfix | 修复部分游戏退出时进程挂起的问题 |
--melonloader.harmonyloglevel=Info | 调整 Harmony（热补丁框架）日志详细程度 |
Il2Cpp 玩家还可能用到--melonloader.agfoffline（离线生成程序集，不访问远程 API）和--melonloader.agfregenerate（强制重新生成程序集缓存）。完整参数列表见 MelonLoader.Bootstrap 下的启动参数解析逻辑。
进阶玩法：让加载器更贴合你的场景
换代理 DLL 名称。version.dll不是唯一的入口名——部分游戏因为反作弊或加载顺序问题不吃它，你可以把它重命名为winhttp.dll、winmm.dll、dinput8.dll、d3d11.dll等十几种兼容名称之一再放进游戏目录，功能完全相同。默认名不好使时优先试winhttp.dll。
多 Mod 冲突排查。给启动参数加--no-mods对比一次有 Mod 和一次无 Mod 的启动行为，是最快的二分法。Mod 数量多时，逐个把嫌疑 Mod 文件夹改名为Disabled来隔离，比删文件安全。
清理 Il2Cpp 缓存。游戏大版本更新后，旧的Il2CppAssemblies缓存可能导致类型缺失或加载失败，直接删掉该目录让 MelonLoader 重建即可（首次启动会变慢）。
写自己的 Mod。Mod 入口是一个继承MelonMod的类，类上用[MelonInfo]特性声明名称、版本和作者（定义见 MelonLoader/Melons/Melon.cs），程序集里再挂上[MelonGame]指明目标游戏 ID。加载器在扫描目录时会用 Cecil 预先读取每个 DLL 的特性，没有[MelonInfo]的程序集会被直接跳过，所以特性写错是最常见的"Mod 不生效"原因之一。
MelonLoader 报错速查表
遇到异常别慌，先打开MelonLoader/Logs/latest.log，然后对照这张表：
| 症状 | 最可能原因 | 处理方式 |
|---|---|---|
| 游戏启动后闪退，控制台无输出 | 代理 DLL 未生效 | 确认version.dll在游戏根目录；换用winhttp.dll试试 |
| Il2Cpp 游戏卡在某处不动 | 程序集正在生成 | 看assembly_generation.log，首次启动等待即可 |
| Il2Cpp 游戏报类型找不到 | 缓存过期 | 删除MelonLoader/Il2CppAssemblies重建 |
| 游戏退出后进程不消失 | 已知兼容问题 | 加--quitfix启动参数 |
| 控制台刷屏但看不到重点 | 玩家日志太多 | 配置里设capture_player_logs = false或调低 Harmony 日志级别 |
| Mod 在日志中出现但功能无效 | 特性缺失或版本不匹配 | 核对[MelonInfo]特性；用--melonloader.debug拿详细日志 |
一个通用排查顺序：--no-mods能正常启动→ 问题在 Mod 本身；--no-mods也起不来→ 问题在加载器或环境，先看日志再看缓存。
下一步
挑一个你正在玩的游戏，把 MelonLoader 放进去跑一次--no-mods，确认加载器干净启动——剩下的就只是往Mods文件夹里放东西了。装好第一个 Mod 的那一下，你会明白为什么它叫 Melon（甜瓜）：注入成功的那一刻，是甜的。
【免费下载链接】MelonLoaderThe World's First Universal Mod Loader for Unity Games compatible with both Il2Cpp and Mono项目地址: https://gitcode.com/gh_mirrors/me/MelonLoader
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
