XHMCL Launcher 使用手册

软件名称： XHMCL Launcher（小慧MC启动器） 适用版本： 0.7.0 支持平台： Windows、Linux、macOS 项目页面： https://pan.hui.itxiaohui.top/s/dvCN

XHMCL 是独立开发的 Minecraft Java Edition 启动与管理工具，不隶属于 Mojang Studios 或 Microsoft。

1. 软件简介

XHMCL Launcher 是一款面向 Minecraft Java Edition 玩家的桌面启动器和游戏管理平台。它将游戏版本、Java 环境、模组与资源、整合包、本地服务器和下载任务集中在一个界面中管理。

主要能力：

• 独立游戏实例管理，支持创建、复制、编辑和恢复性删除。
• Minecraft 原版、Forge、Fabric、Quilt、NeoForge 安装。
• Modrinth 模组、光影、材质包、整合包和 Paper 插件搜索与安装。
• Java 8、17、21、25 扫描、下载和按游戏版本自动选择。
• Microsoft 正版账号与离线账号。
• Vanilla、Paper、Fabric 和自定义核心的本地开服管理。
• 下载队列、多线程分段下载、多下载源和失败重试。
• 简体中文、繁体中文和英文，可在运行时切换。
• 深色、浅色、跟随系统主题和自定义壁纸。

2. 安装与首次启动

2.1 Windows

1. 下载 XHMCL-Launcher-0.7.0-Setup.exe。
2. 双击安装包并选择安装目录。
3. 安装完成后，从桌面或开始菜单启动 XHMCL Launcher。
4. XHMCL 默认采用当前用户安装方式，启动器本身不要求管理员权限。
5. 当前安装包未使用商业代码签名证书；Windows SmartScreen 如显示“未知发布者”，请核对下载来源和文件哈希后再决定是否运行。

2.2 Linux 与 macOS

项目支持对应平台的打包配置。请从项目发布页面获取适合系统的软件包，并允许应用访问所选择的游戏目录。macOS 首次打开第三方应用时可能需要在“隐私与安全性”中确认。

2.3 数据目录

XHMCL 将设置与实例数据保存在安装目录之外：

• Windows：%APPDATA%\xhmcl
• Linux：$XDG_DATA_HOME/xhmcl，未设置时为 ~/.local/share/xhmcl
• macOS：~/Library/Application Support/xhmcl

更换或卸载程序不会自动删除这些数据。重要世界、截图和配置仍建议单独备份。

3. 首页与启动游戏

首页包含当前账号、当前游戏实例、Java 环境状态和“启动游戏”按钮。

标准启动流程：

1. 在“下载中心”选择 Minecraft 版本并创建实例。
2. 根据需要选择原版或 Forge、Fabric、Quilt、NeoForge 加载器。
3. 等待下载列表中的任务全部完成。
4. 在首页选择账号和游戏实例。
5. 点击“启动游戏”。

首次安装或启动时，如缺少兼容 Java，XHMCL 可自动下载并配置。启动日志保存在对应实例目录的 logs 文件夹中。

4. 账号管理

4.1 Microsoft 正版账号

1. 首页点击“当前账号”。
2. 选择“添加账号”。
3. 保持“Microsoft 账号”标签选中。
4. 点击“使用 Microsoft 登录”。
5. 系统默认浏览器会打开 Microsoft 登录页面。
6. 在 Microsoft 官方页面完成密码、验证码或安全密钥验证。
7. 浏览器提示完成后返回 XHMCL。

XHMCL 使用 OAuth 2.0 Authorization Code + PKCE 和 http://localhost 回调。密码与验证码只提交给 Microsoft，启动器不接触这些凭据。XHMCL 会依次验证 Xbox 身份、Minecraft Java Edition 所有权和玩家档案。

登录令牌只保存在本机。Windows 使用 DPAPI 加密；Linux 与 macOS 使用权限受限的本机密钥和 AES-GCM 加密。启动游戏前，过期令牌会自动刷新。

如提示“应用尚未获得 Minecraft Services 访问权限”，表示 XHMCL 的 Microsoft Application ID 仍在等待 Mojang/Microsoft 审核，并不代表玩家账号或密码错误。

4.2 离线账号

1. 进入“添加账号”。
2. 选择“离线账号”。
3. 输入 3 至 16 位玩家名称，只能包含英文字母、数字和下划线。
4. 点击“添加”。

离线账号不验证游戏所有权，只适用于离线游戏或关闭正版验证的服务器。不要使用离线账号冒充他人。

4.3 移除账号

进入“设置 - 玩家资料与皮肤”，选择当前账号后点击“移除账号”。此操作只删除本机保存的账号信息和登录令牌，不会删除 Microsoft 账号。

5. 下载中心与游戏实例

5.1 下载 Minecraft

进入“下载中心”，按正式版、快照版等类型筛选版本。选择版本后创建实例，再选择加载器类型。XHMCL 会下载并校验客户端、依赖库、资源索引、资源文件和本地库。

5.2 加载器

• 原版： 不安装第三方加载器。
• Forge： 适用于大量传统和大型模组。
• Fabric： 轻量、更新速度快，常用于性能和客户端模组。
• Quilt： 基于 Fabric 生态发展的加载器。
• NeoForge： Forge 生态的新分支，常用于较新的游戏版本。

模组必须同时兼容 Minecraft 版本和加载器。不要将 Fabric 模组安装到 Forge 实例，反之亦然。

5.3 实例管理

“游戏管理”中的每个实例相互隔离。可以复制实例用于测试不同模组组合；删除实例时会先移动到恢复目录。更改实例前建议备份 saves、screenshots 和重要配置。

6. 下载列表和下载源

所有游戏、Java、服务器核心和资源下载都会显示在左侧“下载列表”。

• 默认并发任务数为 6，可在设置中调整为 1 至 32。
• 大文件支持 HTTP Range 多线程分段下载。
• 服务器不支持分段时会自动回退为单流下载。
• 下载失败或取消后可以点击“重试下载”。
• 自动下载源模式会在镜像和官方源之间进行回退。
• 支持官方源、BMCLAPI 和用户自定义的 BMCLAPI 兼容镜像池。

使用 Clash 时，XHMCL 会读取 JVM/环境代理设置，并在 Windows 上尝试读取系统代理。代理不可用时请检查 Clash 是否正在运行、系统代理是否打开以及规则是否允许访问 Microsoft、Mojang、Modrinth、Fabric、Forge 等服务。

7. Java 环境

进入“设置 - Java 运行环境”可以扫描现有 Java，或下载 Java 8、17、21、25。

常见对应关系：

• 较旧 Minecraft 版本通常使用 Java 8。
• Minecraft 1.18 至部分 1.20.x 版本通常使用 Java 17。
• Minecraft 1.20.5 及更新版本通常使用 Java 21。
• 极新版本是否需要 Java 25，以游戏版本元数据和实际要求为准。

建议保持“自动补全 Java”开启。XHMCL 会按游戏或服务器版本选择兼容的主版本，不会要求用户手动设置系统全局 JAVA_HOME。

8. 资源中心

资源中心支持本地管理和 Modrinth 在线搜索。

8.1 模组、光影和材质包

1. 先在首页选择目标游戏实例。
2. 进入“资源中心”，选择模组、光影或材质包。
3. 搜索项目并查看项目图片与兼容信息。
4. 点击安装，确认目标实例、Minecraft 版本和加载器。
5. XHMCL 会选择兼容版本、下载文件并安装必要依赖。

已安装内容可以启用、禁用、删除和检查更新。资源项目页可跳转 Modrinth，并支持在 MC 百科搜索同名项目。

光影文件安装后仍需要 Iris、OptiFine 或其他兼容的光影加载方案，具体取决于游戏版本和加载器。

8.2 整合包

XHMCL 支持 Modrinth .mrpack 整合包。导入时会解析索引、下载客户端文件、校验哈希并应用覆盖目录。导入前请确认磁盘空间充足，且不要关闭启动器。

8.3 Paper 插件

先在“开服中心”创建并选择 Paper 服务器，再进入资源中心的插件分类。插件只应安装到兼容的 Bukkit/Paper 服务器，不能放入客户端 mods 目录。

9. 开服中心

开服中心用于管理运行在本机的 Minecraft Java Edition 服务器。

9.1 创建服务器

1. 点击“创建服务器”。
2. 输入服务器名称和 Minecraft 版本。
3. 选择 Vanilla、Paper、Fabric 或自定义核心。
4. 设置最小/最大内存、端口、最大玩家数和 MOTD。
5. 选择 Java 自动匹配或指定已发现的 Java。
6. 阅读并接受 Minecraft EULA 后才能创建和安装。

自定义核心必须来自可信来源。不要运行来源不明的 JAR。

9.2 控制台与进程控制

• 启动： 启动服务器进程并显示实时控制台输出。
• 安全停止： 向服务器发送 stop，等待世界数据保存后退出。
• 重启： 安全停止完成后重新启动。
• 强制停止： 立即结束服务器及子进程，可能导致未保存世界数据丢失，只能在安全停止无响应时使用。
• 发送命令： 可发送 list、say、whitelist 等控制台命令，不需要输入 /。

9.3 图形化配置

服务器配置编辑器按常规、世界、玩法、性能、网络和高级分类编辑 server.properties。高级文本模式会直接替换配置文件，保存前会进行校验并创建备份。大多数配置在重启服务器后生效。

如需让公网玩家连接，还需要正确配置路由器端口映射、防火墙规则或可信的内网穿透服务。XHMCL 不会自动开放公网端口。

10. 百宝箱

10.1 多线程下载器

输入 HTTP/HTTPS 直链、保存目录和分段数，即可将任务加入下载列表。建议保持默认 6 线程；线程越多不一定越快，部分站点还会限制并发请求。

10.2 内存优化

启动器平时不要求管理员权限。只有执行 Windows 内存优化时才会显示 UAC 提示。该工具尝试压缩普通应用的非活动工作集，不会删除文件，并排除 Minecraft、Java、XHMCL 和关键系统进程。优化后首次切回应用可能出现短暂卡顿。

10.3 清理游戏垃圾

垃圾清理会先扫描并显示文件数量和占用空间，只处理已知范围：

• XHMCL 和游戏启动日志。
• Minecraft 游戏日志。
• Minecraft 崩溃报告。
• XHMCL 临时下载文件。

世界、模组、光影、材质包、配置、截图和服务器数据不在扫描范围内。确认清理后文件会永久删除，请先核对列表。

11. 外观、语言与路径

在设置中可以：

• 切换简体中文、繁体中文和 English。
• 选择深色、浅色或跟随系统主题。
• 导入 PNG/JPG/JPEG 自定义壁纸并调整可见度。
• 修改游戏下载和实例目录。
• 打开 LittleSkin 或自定义皮肤站。
• 为当前账号导入 64x64 或 64x32 PNG 皮肤。

切换游戏路径不会移动或删除旧目录。新路径必须可写，旧实例需要用户自行迁移或切回原路径。

12. 常见问题

版本列表一直加载

检查 Clash、系统代理和下载源。切换为“自动回退”后重试。网络失败时，如果存在缓存，XHMCL 会显示最近一次成功获取的版本列表。

下载失败后怎么办

进入“下载列表”，找到失败或取消的任务并点击重试。持续失败时切换下载源，检查代理和剩余磁盘空间。

Microsoft 登录成功但无法获取 Minecraft 账号

如果显示 Invalid app registration 或“应用尚未获得 Minecraft Services 访问权限”，说明 XHMCL 的客户端 ID 尚未完成 Mojang/Microsoft 审核。账号密码和浏览器登录本身没有问题，审核通过后使用同一版本重试即可。

提示没有 Minecraft 所有权

确认浏览器登录的是购买 Minecraft Java Edition 的同一个 Microsoft 账号。Xbox Game Pass 权益必须处于有效状态，并确保该账号已创建 Minecraft Java 玩家档案。

游戏无法启动

依次检查：实例是否安装完成、加载器是否完成、Java 主版本是否兼容、最大内存是否小于系统可用内存。随后查看实例 logs 下最新的启动日志。

模组安装后崩溃

确认 Minecraft 版本、加载器和模组版本一致，并检查依赖模组。复制实例后逐批禁用模组，可以更安全地定位冲突。

服务器卡住无法关闭

先使用“安全停止”并等待世界保存。如果控制台长时间无响应，再使用“强制停止”。重新启动前备份世界目录并检查服务端日志。

13. 隐私与安全

• XHMCL 不要求用户在启动器界面输入 Microsoft 密码或验证码。
• Microsoft 登录在系统浏览器和 Microsoft 官方页面完成。
• 登录令牌只用于登录 Xbox/Minecraft、验证游戏权益、读取玩家档案和启动游戏。
• 令牌保存在本机并加密；移除账号会删除对应的本机令牌。
• XHMCL 不提供破解正版验证、账号共享或绕过游戏所有权的功能。
• 下载第三方模组、插件、光影、材质包和服务端核心前，应核对作者、许可证和文件来源。

14. 法律与第三方服务

使用 XHMCL 和 Minecraft 前，请阅读并遵守：

• Minecraft EULA：https://www.minecraft.net/eula
• Minecraft Usage Guidelines：https://www.minecraft.net/usage-guidelines
• Microsoft Services Agreement：https://www.microsoft.com/servicesagreement
• Microsoft Privacy Statement：https://privacy.microsoft.com/privacystatement
• Modrinth Terms of Use：https://modrinth.com/legal/terms

Minecraft 名称、游戏内容及相关商标归其权利人所有。XHMCL Launcher（小慧MC启动器）是独立社区项目，不是官方 Minecraft 产品，也不代表 Mojang Studios 或 Microsoft 的认可、赞助或合作。

15. 获取软件与反馈

项目下载与公开资料：

https://pan.hui.itxiaohui.top/s/dvCN

反馈问题时，请提供 XHMCL 版本、操作系统、Minecraft 版本、加载器类型、操作步骤和经过隐私检查的错误日志。不要公开 Microsoft 密码、验证码、访问令牌、刷新令牌或服务器管理密码。

文档版本：1.0 对应 XHMCL Launcher：0.7.0 更新日期：2026-08-23