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>
---
 packages/docs/content/zh/manual/features/java.mdx | 286 ++++++++++++++++++++++
 1 file changed, 286 insertions(+)
 create mode 100644 packages/docs/content/zh/manual/features/java.mdx

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

diff --git a/packages/docs/content/zh/manual/features/java.mdx b/packages/docs/content/zh/manual/features/java.mdx
new file mode 100644
index 0000000..6894ec1
--- /dev/null
+++ b/packages/docs/content/zh/manual/features/java.mdx
@@ -0,0 +1,286 @@
+---
+title: Java 管理
+description: 自动 Java 检测、下载和安装
+---
+
+# Java 管理
+
+DropOut 提供全面的 Java 管理，自动检测已安装的版本并根据需要下载新版本。
+
+## 自动检测
+
+### 系统扫描
+
+DropOut 扫描多个位置查找 Java 安装：
+
+**Linux:**
+- `/usr/lib/jvm/`
+- `/usr/java/`
+- `$JAVA_HOME`
+- `PATH` 环境变量
+
+**macOS:**
+- `/Library/Java/JavaVirtualMachines/`
+- `/System/Library/Java/JavaVirtualMachines/`
+- `$JAVA_HOME`
+- `PATH` 环境变量
+
+**Windows:**
+- `C:\Program Files\Java\`
+- `C:\Program Files (x86)\Java\`
+- `%JAVA_HOME%`
+- `PATH` 环境变量
+- Windows 注册表
+
+### 版本检测
+
+对于找到的每个 Java 安装，DropOut 会：
+1. 运行 `java -version` 获取版本信息
+2. 解析主要版本（8、11、17、21 等）
+3. 检测架构（x64、ARM64）
+4. 识别供应商（Oracle、Adoptium 等）
+
+### 结果
+
+所有检测到的 Java 安装都显示在设置 → Java 中：
+- 版本号
+- 安装路径
+- 架构
+- 当前选择状态
+
+## Java 下载
+
+### Adoptium 集成
+
+DropOut 集成了 Eclipse Adoptium API 以下载高质量的免费 JDK/JRE 构建版本。
+
+**支持的版本：**
+- Java 8（LTS）
+- Java 11（LTS）
+- Java 17（LTS）
+- Java 21（LTS）
+- Java 23+（最新版）
+
+**功能：**
+- 自动平台检测
+- 特定架构的构建版本
+- JDK 或 JRE 选择
+- 校验和验证
+
+### 下载过程
+
+1. 导航到设置 → Java
+2. 点击"下载 Java"
+3. 选择版本（例如 Java 17）
+4. 选择 JDK 或 JRE
+5. 点击下载
+6. 等待下载和解压
+
+**进度跟踪：**
+- 实时下载速度
+- ETA 计算
+- 解压进度
+- 安装确认
+
+### 目录管理
+
+DropOut 会缓存可用的 Java 版本列表，以加快加载速度，并自动处理不同步时的刷新工作。
+
+**刷新：**
+- 24 小时后自动刷新
+- 设置中手动刷新
+- 下载失败时强制刷新
+
+## 安装
+
+### 下载目录
+
+下载的 Java 运行时安装到：
+
+```
+~/.local/share/com.dropout.launcher/java/  (Linux)
+~/Library/Application Support/com.dropout.launcher/java/  (macOS)
+%APPDATA%/com.dropout.launcher/java/  (Windows)
+```
+
+### 目录结构
+
+```
+java/
+├── jdk-17.0.9+9/
+│   ├── bin/
+│   │   └── java (或 java.exe)
+│   └── lib/
+├── jdk-21.0.1+12/
+│   ├── bin/
+│   └── lib/
+└── download_queue.json
+```
+
+### 解压
+
+1. 下载到 `.part` 文件
+2. 验证校验和
+3. 解压存档：
+   - Linux/macOS 上的 `.tar.gz`
+   - Windows 上的 `.zip`
+4. 移动到 `java/<version>/` 目录
+5. 设置可执行权限（Unix）
+
+## 配置
+
+### 内存分配
+
+在设置中配置 JVM 内存：
+
+**最小内存：**
+- 默认：1024 MB
+- 推荐：原版 2048 MB
+- 推荐：模组 4096+ MB
+
+**最大内存：**
+- 默认：4096 MB
+- 根据系统 RAM 调整
+- 为操作系统和其他应用留出 4GB
+
+**格式：**
+```bash
+-Xms1024M -Xmx4096M
+```
+
+### 自定义 JVM 参数
+
+为高级配置添加自定义 JVM 参数。DropOut 为您提供了经过优化的默认配置，通常无需手动更改。
+
+**参数说明：**
+- **垃圾回收 (GC)**: 默认使用 G1GC，能够大幅减少大规模模组环境下的游戏卡顿。
+- **实验性选项**: 部分性能优化参数需要开启此开关才能生效。
+- **内存分块**: 优化大内存环境下的数据读写效率。
+
+关于每个参数的具体作用、推荐数值以及技术实现，请参考 [实现细节：JVM 参数优化](../development/implementation.mdx#参数优化与-jvm-配置)。
+
+### Java 路径选择
+
+**自动选择：**
+- DropOut 为每个 Minecraft 版本推荐最佳 Java 版本
+- Java 8 用于 Minecraft 1.12.2 及更早版本
+- Java 17 用于 Minecraft 1.18-1.20.4
+- Java 21 用于 Minecraft 1.20.5+
+
+**手动选择：**
+1. 前往设置 → Java
+2. 从检测到的安装中选择
+3. 或指定自定义路径
+
+## 版本推荐
+
+### Minecraft 版本 → Java 版本
+
+| Minecraft 版本 | 推荐 Java | 最低 Java |
+|-------------------|------------------|--------------|
+| 1.7.10 及更早  | Java 8           | Java 8       |
+| 1.8 - 1.12.2      | Java 8           | Java 8       |
+| 1.13 - 1.16.5     | Java 8 或 11     | Java 8       |
+| 1.17 - 1.17.1     | Java 16          | Java 16      |
+| 1.18 - 1.20.4     | Java 17          | Java 17      |
+| 1.20.5+           | Java 21          | Java 21      |
+
+### 模组 Minecraft
+
+**Fabric:**
+- 通常与原版要求匹配
+- 一些模组可能需要更新的 Java
+
+**Forge:**
+- 可能需要特定的 Java 版本
+- 检查模组加载器文档
+- 通常需要完全匹配版本
+
+## 故障排除
+
+### 未检测到 Java
+
+**问题：** 已安装的 Java 未显示
+
+**解决方案：**
+1. 验证 Java 在标准位置
+2. 检查 `JAVA_HOME` 环境变量
+3. 将 Java `bin` 目录添加到 `PATH`
+4. 重启 DropOut
+5. 手动选择路径
+
+### 下载失败
+
+**问题：** Java 下载未完成
+
+**解决方案：**
+1. 检查互联网连接
+2. 验证磁盘空间
+3. 尝试不同版本
+4. 清除下载队列
+5. 从 Adoptium 手动下载
+
+### Java 版本错误
+
+**问题：** 由于 Java 版本导致游戏崩溃
+
+**解决方案：**
+1. 检查 Minecraft 版本要求
+2. 下载正确的 Java 版本
+3. 在设置中选择适当的 Java
+4. 验证 Java 路径正确
+
+### 内存不足错误
+
+**问题：** 游戏因内存错误崩溃
+
+**解决方案：**
+1. 增加最大内存分配
+2. 关闭其他应用程序
+3. 升级系统 RAM
+4. 使用 64 位 Java
+5. 优化 JVM 参数
+
+### 性能问题
+
+**问题：** 低 FPS 或卡顿
+
+**解决方案：**
+1. 调整内存分配（不要太高！）
+2. 启用 G1GC 垃圾收集器
+3. 添加性能 JVM 参数
+4. 如兼容使用更新的 Java 版本
+5. 为整合包分配 4-8GB
+
+## 最佳实践
+
+### 对于玩家
+
+1. **使用 Adoptium 构建版本** - 免费、高质量、维护良好
+2. **Java 与 Minecraft 版本匹配** - 检查版本要求
+3. **不要过度分配内存** - 为操作系统留出 RAM
+4. **保持 Java 更新** - 安全性和性能
+5. **使用 64 位 Java** - 大内存所需
+
+## 高级主题
+
+### 自定义 Java 安装
+
+使用自定义 Java 安装：
+
+1. 手动安装 Java
+2. 记录安装路径
+3. 在 DropOut 设置 → Java 中
+4. 点击"自定义路径"
+5. 浏览到 Java 可执行文件
+6. 验证版本正确
+
+### GraalVM
+
+GraalVM 支持高级用户：
+
+1. 从 graalvm.org 下载 GraalVM
+2. 手动安装
+3. 作为自定义 Java 添加到 DropOut
+4. 可能提高性能
+5. 使用前彻底测试
-- 
cgit v1.2.3-70-g09d2

