path: root/packages/docs/content/zh/troubleshooting.mdx

---
title: 故障排除
description: DropOut 启动器常见问题和解决方案
---

# 故障排除

本指南涵盖常见问题及其解决方案。如果在这里找不到你的问题，请在 GitHub 上[提交 issue](https://github.com/HydroRoll-Team/DropOut/issues)。

## 安装问题

### Linux：缺少依赖

**问题：** 安装时提示缺少库

**解决方案：**
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0

# Fedora
sudo dnf install webkit2gtk4.1 gtk3

# Arch
sudo pacman -S webkit2gtk gtk3
```

### macOS："应用程序已损坏"

**问题：** macOS 提示 DropOut 已损坏无法打开

**解决方案：**
1. 打开终端
2. 运行：`xattr -cr /Applications/DropOut.app`
3. 再次尝试打开
4. 或者：系统偏好设置 → 安全性 → 仍要打开

### Windows：SmartScreen 警告

**问题：** Windows SmartScreen 阻止安装程序

**解决方案：**
1. 点击"更多信息"
2. 点击"仍要运行"
3. 这对于没有扩展验证证书的新应用是正常的

## 身份验证问题

### Microsoft 登录失败

**问题：** 无法完成 Microsoft 登录

**可能原因和解决方案：**

**1. 设备代码过期：**
- 代码在 15 分钟后过期
- 重新开始登录过程
- 更快地完成授权

**2. 网络问题：**
- 检查互联网连接
- 暂时禁用 VPN
- 检查防火墙设置
- 尝试不同的网络

**3. Microsoft 账户问题：**
- 验证账户拥有 Minecraft Java 版
- 在 https://www.minecraft.net/profile 检查
- 确保账户未被封禁

**4. 浏览器问题：**
- 尝试不同的浏览器
- 清除浏览器缓存
- 禁用广告拦截器
- 使用无痕/隐私模式

### 令牌刷新失败

**问题：** 令牌刷新失败，必须频繁重新登录

**解决方案：**
1. 完全退出登录
2. 从应用数据目录删除 `accounts.json`
3. 重新登录
4. 如果持续存在，检查 Microsoft 账户状态

### 离线登录不工作

**问题：** 无法创建离线账户

**解决方案：**
- 用户名必须是 3-16 个字符
- 仅使用字母、数字、下划线
- 不使用特殊字符
- 不使用空格

## 游戏启动问题

### 找不到 Java

**问题：** "未找到 Java 安装"

**解决方案：**

**1. 自动检测现有 Java：**
- 设置 → Java → 检测安装
- 如果找到，选择它
- 如果未找到，进行步骤 2

**2. 通过 DropOut 下载 Java：**
- 设置 → Java → 下载 Java
- 选择适当的版本：
  - Java 8 用于 Minecraft 1.12.2 及更早版本
  - Java 17 用于 Minecraft 1.18-1.20.4
  - Java 21 用于 Minecraft 1.20.5+

**3. 手动安装 Java：**
- 从 [Adoptium](https://adoptium.net/) 下载
- 安装到系统
- 重启 DropOut
- 再次检测

### Java 版本错误

**问题：** 游戏崩溃并提示"不支持的类文件版本"

**解决方案：**
将 Java 版本与 Minecraft 版本匹配：

| Minecraft 版本 | Java 版本 |
|-------------------|--------------|
| 1.7.10 及更早  | Java 8       |
| 1.8 - 1.12.2      | Java 8       |
| 1.13 - 1.16.5     | Java 8 或 11 |
| 1.17 - 1.17.1     | Java 16      |
| 1.18 - 1.20.4     | Java 17      |
| 1.20.5+           | Java 21      |

### 内存不足错误

**问题：** 游戏崩溃并显示 `java.lang.OutOfMemoryError`

**解决方案：**

**1. 增加内存分配：**
- 设置 → 内存
- 增加最大内存：
  - 原版：最少 4GB
  - 轻度模组：6GB
  - 重度整合包：8-12GB
- 不要超过系统 RAM 的 80%

**2. 使用 64 位 Java：**
- 检查当前 Java 架构
- 如需要下载 64 位 Java
- 32 位 Java 限制在约 2GB

**3. 降低渲染距离：**
- 游戏内视频设置
- 将渲染距离降低到 8-12 区块

**4. 优化 JVM 参数：**
```bash
-Xms4G -Xmx8G -XX:+UseG1GC -XX:+UnlockExperimentalVMOptions
```

### 游戏无法启动

**问题：** 游戏不启动，没有错误消息

**检查：**

**1. 日志输出：**
- 检查 DropOut 中的游戏控制台
- 查找错误消息
- 常见问题：
  - 文件缺失
  - 下载损坏
  - 模组冲突

**2. 验证文件：**
- 删除版本文件夹
- 重新下载版本
- 在模组版本之前先尝试原版

**3. 检查权限：**
- 确保 DropOut 可以写入游戏目录
- 检查文件夹权限
- 在 Linux 上：`chmod -R 700 ~/.local/share/com.dropout.launcher`（仅当前用户可访问）

## 下载问题

### 下载失败

**问题：** 资源或库下载失败

**解决方案：**

**1. 网络问题：**
- 检查互联网连接
- 禁用 VPN
- 尝试不同的网络
- 检查防火墙/杀毒软件

**2. 恢复下载：**
- DropOut 自动恢复中断的下载
- 关闭并重新打开 DropOut
- 下载应该继续

**3. 清除下载缓存：**
- 删除 libraries/assets 中的 `.part` 文件
- 重新开始下载

**4. 手动下载：**
- 检查日志中失败的 URL
- 手动下载文件
- 放置在正确位置

### 下载缓慢

**问题：** 下载非常慢

**解决方案：**

**1. 调整线程数：**
- 设置 → 下载
- 尝试不同的线程数：
  - 太低：整体较慢
  - 太高：连接限流
  - 推荐：5-10 个线程

**2. 网络优化：**
- 关闭占用大量带宽的应用
- 如可能使用有线连接
- 检查 ISP 限速

**3. 备用 CDN：**
- Mojang 镜像可能很慢
- 尝试在一天中的不同时间

## 模组加载器问题

### Fabric 安装失败

**问题：** 无法安装 Fabric 加载器

**解决方案：**

**1. 检查 Minecraft 版本：**
- Fabric 支持 1.14+
- 不支持更早版本
- 尝试更新的 Minecraft 版本

**2. 网络问题：**
- 检查互联网连接
- Fabric Meta API 可能宕机
- 稍后再试

**3. 手动安装：**
- 从 [fabricmc.net](https://fabricmc.net/) 下载 Fabric
- 使用官方安装器
- 将配置文件导入 DropOut

### Forge 安装失败

**问题：** Forge 安装器失败或挂起

**解决方案：**

**1. Java 版本：**
- 确保 Java 版本正确
- Forge 1.17+ 需要 Java 16+
- 更早的 Forge 可能需要 Java 8

**2. 安装器超时：**
- Forge 安装器可能很慢
- 等待最多 10 分钟
- 检查日志查看进度

**3. 磁盘空间：**
- 确保有足够的可用空间
- Forge 临时需要约 1GB
- 检查 Linux 上的 `/tmp`

**4. 手动安装：**
- 从 [minecraftforge.net](https://files.minecraftforge.net/) 下载 Forge 安装器
- 手动运行安装器
- 选择安装客户端
- 导入配置文件

### 模组崩溃

**问题：** 安装模组后游戏崩溃

**解决方案：**

**1. 检查兼容性：**
- 验证模组适用于正确的 Minecraft 版本
- 检查模组加载器版本要求
- 阅读模组说明了解依赖项

**2. 安装依赖项：**
- Fabric 模组通常需要 Fabric API
- 一些模组需要库
- 检查崩溃日志中的"缺失"错误

**3. 移除冲突的模组：**
- 逐一禁用模组
- 识别有问题的模组
- 检查已知冲突
- 更新或替换模组

**4. 更新模组：**
- 使用最新的模组版本
- 检查模组更新说明
- 一些更新修复崩溃

## 性能问题

### 低 FPS

**问题：** 游戏运行缓慢或卡顿

**解决方案：**

**1. 分配更多内存：**
- 将最大内存增加到 6-8GB
- 不要过度分配（导致 GC 暂停）

**2. 安装性能模组：**
- **Fabric**: Sodium、Lithium、Phosphor
- **Forge**: OptiFine、Magnesium、Rubidium

**3. 优化设置：**
- 降低渲染距离
- 禁用精美图形
- 关闭粒子
- 如果 fps < 60 禁用垂直同步

**4. 更新显卡驱动：**
- 从制造商下载最新版本
- NVIDIA: GeForce Experience
- AMD: Adrenalin
- Intel: Graphics Command Center

**5. 关闭后台应用：**
- 释放系统资源
- 禁用覆盖层（Discord 等）
- 检查任务管理器中的 CPU/RAM 占用

### 启动器启动缓慢

**问题：** DropOut 启动时间很长

**解决方案：**

**1. 检查系统资源：**
- 关闭不必要的程序
- 确保有足够的 RAM 可用
- 检查 CPU 使用率

**2. 杀毒软件干扰：**
- 将 DropOut 添加到例外
- 暂时禁用以测试
- 一些杀毒软件会显著减慢速度

**3. 损坏的数据：**
- 删除应用数据中的 `cache` 文件夹
- 重启 DropOut
- 将重建缓存

## UI 问题

### 窗口不打开

**问题：** DropOut 窗口不出现

**解决方案：**

**1. 检查是否在运行：**
```bash
# Linux/macOS
ps aux | grep dropout

# Windows
tasklist | findstr dropout
```

**2. 终止并重启：**
```bash
# Linux/macOS
pkill dropout

# Windows
taskkill /F /IM dropout.exe
```

**3. 重置窗口位置：**
- 删除窗口状态配置
- 重启 DropOut

### 图形故障

**问题：** UI 看起来不对或有视觉伪影

**解决方案：**

**1. 更新显卡驱动：**
- 安装最新驱动
- 重启系统

**2. 禁用硬件加速：**
- 检查设置中是否存在选项
- 可能会降低性能但修复故障

**3. 尝试不同的显示器：**
- 多显示器设置可能导致问题
- 在不同显示器上尝试

## 文件系统问题

### 无法访问游戏目录

**问题：** 访问游戏文件时出错

**解决方案：**

**1. 检查权限：**
```bash
# Linux
chmod -R 700 ~/.local/share/com.dropout.launcher

# macOS
chmod -R 700 ~/Library/Application\ Support/com.dropout.launcher
```

**2. 检查磁盘空间：**
- 确保有足够的可用空间
- Minecraft 需要 2-10GB，取决于模组
- 清理旧版本

**3. 杀毒软件阻止：**
- 将游戏目录添加到例外
- 一些杀毒软件会阻止文件访问

### 文件损坏

**问题：** 文件似乎损坏或无效

**解决方案：**

**1. 验证校验和：**
- DropOut 验证 SHA1/SHA256
- 验证失败会触发重新下载

**2. 重新下载：**
- 删除损坏的文件
- 再次启动版本
- DropOut 将重新下载

**3. 清除缓存：**
- 完全删除版本文件夹
- 从头重新安装

## 获取更多帮助

### 收集调试信息

报告问题时，包括：

**1. 系统信息：**
- 操作系统和版本
- DropOut 版本
- Java 版本

**2. 日志：**
- 控制台的启动器日志
- 如适用的游戏日志
- 错误消息（完整文本）

**3. 重现步骤：**
- 你做了什么
- 你期望什么
- 实际发生了什么

**4. 截图：**
- 错误消息
- UI 问题
- 设置屏幕

### 报告问题

1. 搜索[现有 issues](https://github.com/HydroRoll-Team/DropOut/issues)
2. 如果未找到，[创建新 issue](https://github.com/HydroRoll-Team/DropOut/issues/new)
3. 使用 issue 模板
4. 提供所有要求的信息
5. 保持耐心和响应

### 社区支持

- **GitHub 讨论**：提问
- **Discord**：实时帮助（如果可用）
- **文档**：查看所有指南

## 已知问题

### 目前正在处理

- 多账户切换（进行中）
- 自定义游戏目录选择（计划中）
- 启动器自动更新（计划中）

### 可用的变通方法

**问题**：无法轻松切换账户
**变通方法**：退出登录并使用不同账户登录

**问题**：没有内置模组管理器
**变通方法**：在实例文件夹中手动管理模组

**问题**：无法从其他启动器导入
**变通方法**：手动复制实例文件