From 81a62402ef6f8900ff092366121a9b7a4263ba52 Mon Sep 17 00:00:00 2001
From: Natsuu <natsukawa247@outlook.com>
Date: Fri, 27 Feb 2026 17:18:25 +0800
Subject: Restructure docs into manual/development and add implementation docs
 (#94)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary by Sourcery

Restructure documentation into separate manual and development sections,
introduce detailed internal implementation docs for auth/Java/mod
loaders, and update site navigation, landing page links, and MDX tooling
(Mermaid, card styling) to match the new structure and tech stack.

Enhancements:
- Enable Mermaid rendering support in the docs app and add a reusable
Mermaid React component.
- Refine Docs page rendering by customizing Card styling and removing
redundant in-page titles/descriptions rendered by the layout.
- Align docs source configuration and routing comments with the new
manual-based default paths.

Documentation:
- Split user-facing docs under a new manual section and move contributor
content into a dedicated development section for both English and
Chinese.
- Add comprehensive internal implementation documentation covering
authentication, Java management, mod loader/version merging, event bus,
and architecture patterns in both English and Chinese.
- Update existing feature docs (mod loaders, Java, authentication) and
getting-started/troubleshooting pages to be more conceptual, pointing to
implementation docs for technical details.
- Refresh architecture docs to reflect the React/Zustand frontend stack
and add Mermaid-based architecture diagrams.
- Adjust navigation labels, home-page CTAs, and doc links to target the
new manual/development structure and routes.

---------

Co-authored-by: 简律纯 <i@jyunko.cn>
---
 .../docs/content/zh/manual/troubleshooting.mdx     | 523 +++++++++++++++++++++
 1 file changed, 523 insertions(+)
 create mode 100644 packages/docs/content/zh/manual/troubleshooting.mdx

(limited to 'packages/docs/content/zh/manual/troubleshooting.mdx')

diff --git a/packages/docs/content/zh/manual/troubleshooting.mdx b/packages/docs/content/zh/manual/troubleshooting.mdx
new file mode 100644
index 0000000..ba0ec66
--- /dev/null
+++ b/packages/docs/content/zh/manual/troubleshooting.mdx
@@ -0,0 +1,523 @@
+---
+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**：实时帮助（如果可用）
+- **文档**：查看所有指南
+
+## 已知问题
+
+### 目前正在处理
+
+- 多账户切换（进行中）
+- 选择自定义游戏目录（计划中）
+- 启动器自动更新（计划中）
+
+### 解决方案
+
+**问题**：无法轻松切换账户
+**解决方案**：退出登录并使用不同账户登录
+
+**问题**：没有内置模组管理器
+**解决方案**：在实例文件夹中手动管理模组
+
+**问题**：无法从其他启动器导入
+**解决方案**：手动复制实例文件
-- 
cgit v1.2.3-70-g09d2

