安装与启动故障排查
如果您在安装 Minecraft 官方版本、模组加载器（Forge/Fabric/NeoForge/Quilt）、模组、模组包、光影，或是启动游戏时遇到任何问题，本指南将一步步协助您定位并解决这些故障。
🌐 1. 下载失败或卡住 (网络连接问题)
故障表现
- 下载 Minecraft 游戏文件、资产资源、库文件或 Forge/Fabric 等加载器时，下载进度一直卡在
0%处。 - 启动器弹出超时或连接相关的错误提示（例如
CONNECTION_TIMED_OUT,NAME_NOT_RESOLVED,HTTP_STATUS 504）。
解决方案
使用下载源镜像
如果 Mojang 官方服务器或 Mod 加载器官方服务器在您的地区网络延迟过高，或者被您的网络服务提供商拦截，您可以切换到国内的公益镜像源：
- 点击左侧边栏底部的 设置 按钮（齿轮图标）。
- 滚动页面到 网络设置 区域。
- 找到 下载源 / 镜像（Download Source / Mirror）选项。
- 将该设置从 默认 修改为 BMCLAPI 或 MCBBS（这两个镜像源每日与官方数据保持高速同步）。
代理服务器设置
如果您的网络访问特定服务受到物理限制，您可以在启动器内直接配置网络代理：
- 前往 设置 -> 网络设置，找到代理服务器配置区域。
- 填写您的 SOCKS5 或 HTTP 代理服务器地址。
- 测试代理连接是否正常。
📦 2. 模组或模组包部分文件下载失败 (CurseForge 第三方下载限制)
故障表现
- 下载模组包（Modpack）或单个模组时，部分文件下载失败并显示带有警告标识。
- 提示“限制第三方启动器下载”（Restricted third-party downloads）。
问题原因
CurseForge 平台上的部分模组作者关闭了第三方 API 的下载权限，强制要求玩家必须访问其官方网页来下载模组以获取广告收益。
解决方案
XMCL 智能集成了手动补全机制，您可以非常方便地补齐这些缺失的文件：
- 在启动器右上角打开任务管理器，查看下载失败的详细任务。
- 点击失败模组旁边的下载链接，这会在您的默认浏览器中打开该模组的 CurseForge 网页。
- 在网页中手动将该
.jar模组文件下载到您的本地电脑。 - 将浏览器下载好的
.jar文件直接 拖拽（Drag-and-Drop） 到 XMCL 启动器窗口中（或手动将其放入当前实例的mods文件夹中）。 - XMCL 会自动检测并匹配该文件，随后自动继续并完成其余的安装流程。
🔍 3. 模组在 CurseForge 网站上有，但在启动器内搜索不到
故障表现
- 在启动器内搜索某个模组时，提示“未找到结果”，但该模组明明能在 CurseForge 官方网站上正常查看。
问题原因
CurseForge 平台允许模组作者禁用第三方 API 访问权限。一旦作者禁用了该功能，CurseForge 的 API（XMCL 搜索和获取模组时所依赖的接口）将无法在搜索结果中返回该模组。
解决方案
- 打开您的网页浏览器，访问 CurseForge 官网模组页面。
- 手动点击 Download，将该模组的
.jar格式文件保存到您的电脑上。 - 打开 XMCL 并选中您当前正在使用的游戏实例（实例卡片）。
- 将浏览器下载好的
.jar模组文件直接拖拽（Drag-and-Drop）到启动器的主窗口上。XMCL 将会自动识别并安装到该实例的mods文件夹内。
📦 4. 导入的模组包“消失”或模组列表为空
故障表现
- 将模组包的
.zip或.mrpack格式文件拖拽进启动器进行导入后，却在当前游戏配置文件中找不到，或者对应的模组列表显示为空。
问题原因
- 新实例创建机制：为了防止混乱，XMCL 不会将导入的模组包内容直接塞进您当前正在运行的旧实例。相反，它会为这个模组包创建一个全新的游戏实例（实例卡片）。
- 后台下载任务进行中：模组包本身的压缩包里为了节省空间，通常不包含实际的
.jar模组文件，只包含模组列表清单（元数据）。导入完成后，XMCL 会在后台默默下载清单上的所有模组。在下载完成前，模组列表看起来可能是一片空白。
解决方案
- 切换游戏实例：点击左侧的边栏菜单或实例切换器查看所有的游戏卡片。找到以该模组包命名的全新卡片并选中它。
- 检查任务管理器：点击启动器右上角的 任务管理器 图标（带有加载圆圈的图标），检查模组包的下载任务是否仍在运行。请耐心等待所有下载完成后再启动游戏。
🔄 5. 文件损坏一直重复下载 (控制校验和不匹配循环)
故障表现
- 启动器一直在重复下载某一个库文件或资源文件，并提示文件损坏。
- 游戏因为文件校验失败而一直无法正常启动。
问题原因
由于之前的某次下载被异常中断，损坏的缓存文件在本地被占用锁死，导致启动器无法用正确的文件覆盖它。
解决方案
- 在启动器的诊断信息或日志中找到受损文件的具体路径（例如
libraries/org/lwjgl/...）。 - 在实例面板中点击右上角的 文件夹 图标，打开当前实例的数据目录。
- 按照错误提示中的路径找到对应受损库文件所在的整个文件夹并将其彻底删除。
- 在启动器中点击 修复（Repair）或重新启动游戏。启动器此时会重新下载一个全新、完整的文件副本。
☕ 6. 游戏启动后瞬间崩溃或闪退 (Java 版本不兼容)
故障表现
- 点击启动后，游戏启动了但瞬间闪退，并返回错误代码
1或-1。 - 游戏日志（Log）中出现
UnsupportedClassVersionError或“未找到 Java”等报错。
问题原因
不同版本的 Minecraft 对 Java（JDK）版本有着严格的要求。使用不匹配的 Java 版本会导致游戏直接崩溃。
解决方案
XMCL 拥有极其智能的自动 Java 管理器，可以替您一键下载并配置兼容的 JDK。
Java 版本兼容对照表
请确保您的实例配置了正确的 Java 版本：
- Minecraft 1.12.2 及更早版本：Java 8
- Minecraft 1.16 - 1.17：Java 16 / 17
- Minecraft 1.18 - 1.20.4：Java 17
- Minecraft 1.20.5 及更高版本：Java 21
如何在 XMCL 中管理和选择 Java：
- 前往实例的设置页面（启动按钮旁边的齿轮图标）。
- 找到 Java 设置区域。
- 点击选择框。XMCL 会列出您系统上检测到的所有 Java 版本，并用绿色的勾号标记出完全兼容的版本。
- 如果您的系统上没有合适的 Java 版本，请点击 安装 Java，启动器将自动下载并配置最适合您当前游戏版本的 JDK。
📑 7. 启动器本身无法打开或出现黑屏
故障表现
- 双击启动器图标后没有任何反应。
- 启动器窗口能打开，但整个界面是一片漆黑。
解决方案
您可以通过查看主日志文件来排查导致崩溃的具体原因：
- 访问您本地的启动器数据文件夹：
- Windows：在运行（Win+R）中输入
%appdata%\xmcl并回车。 - macOS：
~/Library/Application Support/xmcl - Linux：
~/.config/xmcl
- Windows：在运行（Win+R）中输入
- 打开其中的
logs文件夹，并找到最新的main.log文件。
📋 8. 生成诊断报告 (推荐的第一步)
在手动搜寻庞杂的日志文件之前，我们强烈建议您先尝试使用启动器内置的 生成诊断报告 功能。这会把启动器日志、游戏日志以及系统运行环境等所有诊断信息自动打包成一个独立的文件，极大地方便了社区和开发者帮您快速查明原因。
如何生成诊断报告：
点击启动器顶部导航栏的 帮助与反馈（Help & Feedback）菜单。
点击 生成报告（Generate Report）按钮将相关的诊断信息和日志打包。
📑 9. 如何分析启动器与游戏日志
如果您希望手动查找日志排查问题，日志文件能够准确地还原当时发生的情况。以下是各种日志的存放路径及常见崩溃排查指南。
🔍 如何找到日志文件
根据是启动器出错还是游戏本身崩溃，您需要去不同的文件夹查找日志：
A. 启动器主日志 (main.log)
适用于启动器界面崩溃、下载失败、网络连接错误、登录故障等：
- Windows：按下快捷键
Win + R，输入%appdata%\xmcl\logs并回车。 - macOS：定位到
~/Library/Application Support/xmcl/logs目录。 - Linux：定位到
~/.config/xmcl/logs目录。 - 在其中找到最新的
main.log文件。
B. 游戏运行日志 (latest.log 与崩溃报告)
适用于模组冲突、Minecraft 崩溃、卡顿、游戏内部的 Java 报错等：
- 在启动器中打开实例的管理卡片。
- 点击实例页面右上角的 文件夹 图标以打开其游戏根目录。
- 前往
logs文件夹，打开latest.log文件。 - 如果游戏崩溃闪退，请前往
crash-reports文件夹，查找最新的.txt文件（命名格式通常为crash-年-月-日_时.分.秒-client.txt）。
🛠 分析日志并修复常见错误
使用任何文本编辑器（例如记事本）打开上述日志文件，然后使用搜索功能（Ctrl + F）来查找特定的异常代码：
🔴 情况 1：内存溢出错误 (Out of Memory)
- 特征字符：
java.lang.OutOfMemoryError: Java heap space或游戏退出代码-805306369。 - 原因：为游戏分配的运行内存（RAM）不足，无法加载当前实例中的所有模组。
- 解决方法：
- 进入该实例的设置页面（启动按钮旁的齿轮图标）。
- 向下滚动到 Java 设置区域。
- 适当调大 最小内存 和 最大内存 的值（例如将最大内存调整为
4096或6144MB）。
🔴 情况 2：模组冲突或缺失前置库
- 特征字符：
Mixin transformation failed、DependencyResolutionException，或者出现Requires mod 'fabric' (version X or later), but only version Y is installed。 - 原因：某些模组运行所需的关联模组（前置库依赖）没有下载，或者两个模组之间互不兼容。
- 解决方法：仔细阅读那行报错信息，通常它会明确列出缺失的前置模组名称。去官网下载对应的前置模组并放入
mods文件夹中，或移除/更新冲突的模组版本。
🔴 情况 3：Java 运行环境版本冲突
- 特征字符：
java.lang.UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime。 - 原因：当前所用的 Java 版本太低，无法支持新版游戏或模组（例如用 Java 8 启动 Minecraft 1.20）。
- 解决方法：打开实例设置，在 Java 区域下点击 安装 Java 按钮，启动器会自动帮您安装最适合该游戏版本的 Java 环境。
🔴 情况 4: 显卡驱动崩溃 / OpenGL 错误
- 特征字符：
GLFW error 65542: WGL: The driver does not seem to support OpenGL或Pixel format not accelerated。 - 原因：您的电脑显卡驱动程序丢失、版本过旧，或者游戏没有被分配给高性能独立显卡，误用了集成显卡启动。
- 解决方法：前往您的显卡品牌官网（NVIDIA、AMD 或 Intel）下载安装最新的显卡驱动。如果是笔记本电脑，请在系统设置中为 Java 程序强制开启“高性能显卡驱动”模式。
❓ 依然看不懂日志怎么办？
如果您仔细看过了日志但仍不知道崩溃是怎么回事，请别担心！XMCL 社区在多个平台提供了热情的求助板块：
1. 加入我们官方的 Discord 社区
与开发者及众多硬核玩家直接交流，实时获取解答。
加入链接：Discord 官方服务器
提问方式：前往 #feedback-and-idea 频道，直接上传您刚才生成的诊断报告文件或崩溃
.txt日志，切勿在聊天框内复制粘贴上千行日志内容。点击查看我们反馈求助频道的布局说明：
2. 在 Reddit 社区提问
- 您也可以在我们的海外玩家论坛上发帖询问：
- 传送门：r/XMCL Subreddit
3. 在 GitHub 提交 Issue
- 如果您确认所遇问题是启动器本身的程序 Bug，可以提交 Bug 报告。
- 报告地址：XMCL GitHub Issues 反馈板块
- 在 Issue 描述中附上您的诊断报告，以便开发人员进行调试排查。