Mod 管理
VoxVer Launcher 内置了强大的 Mod 管理功能，接入 Modrinth Mod 仓库，支持搜索、下载、启用/禁用、配置编辑和更新检测等一站式操作。
计划接入 CurseForge
CurseForge 源目前处于 计划接入 阶段（API Key 申请中），当前版本暂以 Modrinth 为主。
自 v0.6.2 起，下载 页面采用多分类视图，左侧标签栏可在「原版游戏」「Mod」「整合包」「数据包」「资源包」「光影包」「社区资源」之间切换，方便快速定位所需内容。本章将详细介绍 Mod 管理的各个方面。
搜索与下载
VoxVer Launcher 支持从 Modrinth 搜索和下载 Mod，覆盖绝大多数主流 Mod。CurseForge 源计划接入中。
搜索步骤
- 进入 下载 页面，点击顶部「Mod」分类标签
- 在搜索框中输入 Mod 名称或关键词
- 可以通过分类标签筛选（如「工具」、「优化」、「装饰」、「冒险」等）
- 也可以按热度、下载量、更新时间等排序
- 找到目标 Mod 后，点击进入详情页
下载步骤
- 在 Mod 详情页中，确认 Mod 支持的游戏版本和 ModLoader 类型
- 点击 「下载」 按钮
- 选择要安装到的目标实例（如果存在多个实例）
- 等待下载完成
提示
下载进度可以在右下角的全局下载弹窗中实时查看，支持暂停和取消操作。
本地 Mod 管理
进入 实例详情 页面，可以查看和管理该实例中已安装的所有 Mod。
管理功能
| 操作 | 说明 | 详细描述 |
|---|---|---|
| 启用 / 禁用 | 切换 Mod 的加载状态 | 点击 Mod 旁的开关即可切换，无需删除文件。禁用的 Mod 不会被游戏加载，但文件仍保留在 mods/ 目录中（文件名会被添加 .disabled 后缀） |
| 配置编辑 | 编辑 Mod 的配置文件 | 支持 .toml、.json、.cfg、.conf、.ini 等多种格式的配置文件。点击「编辑」按钮打开内置编辑器，修改后保存即可生效 |
| 删除 | 从实例中移除 Mod | 点击「删除」按钮会将 Mod 文件从 mods/ 目录中永久移除。删除前会弹出确认对话框 |
| 从文件安装 | 从本地文件导入 Mod | 点击「从文件安装」按钮选择本地的 .jar 文件，支持多选批量导入，自动复制到实例的 mods/ 目录 |
| 依赖检测 | 检查 Mod 的前置依赖 | 基于 Modrinth API 自动检测已安装 Mod 的依赖关系（required / optional / incompatible / embedded），缺失依赖时会显示红色角标提示 |
| 安装依赖 | 一键安装缺失的依赖 | 检测到缺失依赖后，点击「安装依赖」按钮自动从 Modrinth 下载并安装所需的前置 Mod |
| 更新检测 | 检查 Mod 是否有新版本 | 基于 Modrinth 的 SHA1 哈希值比对，自动检测已安装 Mod 是否有可用更新。有更新时会显示橙色角标提示 |
Mod 元数据解析
VoxVer Launcher 使用 @xmcl/mod-parser 自动解析 Mod 的 jar 文件中的元数据，支持以下格式：
| 格式 | 对应 ModLoader | 解析内容 |
|---|---|---|
fabric.mod.json | Fabric | 名称、版本、作者、描述、主页链接、依赖项、图标 |
quilt.mod.json | Quilt | 名称、版本、贡献者、描述、主页链接、依赖项、图标 |
mods.toml | Forge / NeoForge | 显示名称、版本、作者、描述、主页链接、依赖项、LOGO |
mcmod.info | Forge（旧版） | 名称、版本、作者、描述、主页链接、LOGO |
MANIFEST.MF | 通用 | 名称、版本、描述、作者 |
Mod 图标会自动从 jar 中提取并缓存到本地，在列表中显示。对于无法解析的 Mod，会自动从文件名推断名称和版本。
Mod 详情弹窗
在「实例详情」页面的 Mod 列表中，点击 Mod 行或点击「详情」按钮，可弹出详情窗口，展示以下完整信息：
- 名称与版本 -- Mod 的名称和当前版本号
- 作者 -- Mod 的作者/开发团队
- 描述 -- Mod 的功能描述
- 前置依赖 -- Mod 所需的依赖项列表
- 主页链接 -- Mod 的官方网站或 Modrinth/CurseForge 项目页面
- 文件路径 -- Mod 文件在本地磁盘上的完整路径
ModLoader 支持
VoxVer Launcher 支持以下 ModLoader，不同 ModLoader 对应不同的 Mod 生态：
| ModLoader | Mod 生态 | 仓库来源 | 说明 |
|---|---|---|---|
| Fabric | Fabric 专属 Mod | Modrinth（CurseForge 计划中） | 轻量级，Mod 数量多，加载速度快 |
| Forge | Forge 专属 Mod | Modrinth（CurseForge 计划中） | 老牌生态，大型 Mod 丰富 |
| NeoForge | NeoForge 专属 Mod | Modrinth（CurseForge 计划中） | 新版本生态，兼容 Forge Mod |
| Quilt | Quilt / Fabric Mod | Modrinth | 兼容大部分 Fabric Mod |
注意
- 下载 Mod 前，请确认 Mod 支持的游戏版本和 ModLoader 与你的实例配置一致。
- 不同 ModLoader 的 Mod 不能混用。例如，Fabric Mod 不能在 Forge 环境中加载。
- 部分大型 Mod 可能有前置依赖（前置 Mod），请确保所有依赖都已安装。
常见问题
Mod 安装后不生效？
请按以下步骤排查：
- 确认 ModLoader 已正确安装 -- 进入版本页面，检查目标版本是否已安装对应的 ModLoader
- 确认版本兼容性 -- 检查 Mod 支持的游戏版本是否与你安装的版本一致
- 确认 ModLoader 类型匹配 -- Fabric Mod 只能在 Fabric 环境中加载，Forge Mod 只能在 Forge 环境中加载
- 检查 Mod 是否被禁用 -- 在实例详情中确认 Mod 的启用开关处于开启状态
- 检查前置依赖 -- 部分 Mod 需要安装前置 Mod 才能正常工作，请查看 Mod 的描述页面
Mod 下载失败？
可能的原因和解决方案：
| 原因 | 解决方案 |
|---|---|
| 网络连接异常 | 检查网络连接，或尝试切换下载源 |
| 下载源不可用 | 进入「设置」切换到其他下载源 |
| 磁盘空间不足 | 清理磁盘空间后重试 |
| 目标实例不存在 | 确认目标实例未被删除 |
如何查看 Mod 的详细信息和更新日志？
在「下载」页面点击 Mod 名称进入详情页，可以查看 Mod 的描述、截图、支持版本、更新日志和依赖关系等完整信息。
Mod 配置文件在哪里？
Mod 配置文件通常位于实例目录下的 config/ 文件夹中。你也可以通过 VoxVer Launcher 的内置配置编辑器直接编辑，无需手动查找文件。
Mod 自动更新
VoxVer Launcher 内置 Mod 自动更新检测 功能，基于 Modrinth 的 SHA1 哈希 批量比对已安装的 Mod 与上游版本，自动发现有可用更新的 Mod。
检测原理
扫描本地 Mod 文件
|
v
计算 SHA1 哈希值
|
v
调用 Modrinth API 批量查询
|
v
哈希匹配 → 发现新版本
|
v
在 Mod 列表中标记「有更新」使用步骤
- 进入 实例详情 页面
- 点击 「检查更新」 按钮
- 启动器会自动扫描本地所有 Mod 文件并计算 SHA1 哈希
- 与 Modrinth 上的版本进行比对
- 列表中可更新的 Mod 会显示更新提示
- 选择要更新的 Mod，点击 「一键更新」
- 启动器会流式下载新版本并替换旧文件
更新策略
| 策略 | 说明 |
|---|---|
| 仅显示主版本更新 | 仅在主版本号变化时提示更新（如 1.0.0 → 2.0.0） |
| 显示所有更新 | 包括补丁版本（推荐） |
| 手动选择 | 由用户自行决定是否更新每个 Mod |
提示
- 自动更新功能仅适用于从 Modrinth 下载的 Mod。
- 部分 Mod 可能有版本兼容性要求，更新前请确认新版本与你的游戏版本匹配。
- 更新过程中游戏需要关闭，更新完成后重新启动游戏即可生效。
依赖管理
VoxVer Launcher 内置 Mod 依赖检测 功能，能够自动分析每个 Mod 的前置依赖关系，帮助避免因缺少依赖导致 Mod 无法正常运行的常见问题。
依赖类型
依赖关系分为以下几种类型：
| 类型 | 英文标识 | 说明 |
|---|---|---|
| 必需依赖 | required | 必须安装，否则 Mod 无法运行 |
| 可选依赖 | optional | 可选安装，提供额外功能但非必需 |
| 不兼容 | incompatible | 与该 Mod 存在冲突，不能同时安装 |
| 内嵌依赖 | embedded | 依赖已被包含在 Mod 中，无需单独安装 |
使用步骤
- 进入 实例详情 页面
- 点击工具栏中的 「检查依赖」 按钮
- 启动器会逐一对每个 Mod 计算 SHA1 哈希，通过 Modrinth API 查询其依赖关系
- 检测完成后，存在缺失依赖的 Mod 会在列表中显示红色
⚠ 缺 N 个依赖角标 - 选中存在缺失依赖的 Mod，点击底部操作栏的 「安装 N 个依赖」 按钮
- 启动器会从 Modrinth 自动下载并安装所需的全部必需依赖
- 安装完成后会重新刷新 Mod 列表和依赖检测状态
提示
- 依赖检测同样基于 Modrinth API，仅对能从 Modrinth 识别的 Mod 生效。
- 系统只会自动安装标记为
required（必需）的依赖项，可选依赖可以手动搜索安装。 - 安装依赖时会自动匹配当前的游戏版本和 ModLoader 类型，确保兼容性。