---
title: 身份验证
description: DropOut 中的 Microsoft OAuth 和离线身份验证
---

# 身份验证

DropOut 支持两种身份验证方法：Microsoft 账户（用于官方 Minecraft）和离线模式（用于测试和离线游玩）。

## Microsoft 身份验证

### 概述

DropOut 使用 **Device Code Flow** 进行 Microsoft 身份验证，具有以下特点：
- 无需重定向 URL（无需浏览器集成）
- 适用于任何拥有浏览器的设备
- 提供简单的基于代码的身份验证
- 完全符合 Microsoft OAuth 2.0 标准

### 身份验证流程

身份验证链包含多个步骤。DropOut 自动处理这些复杂的交换过程，包括与 Microsoft、Xbox Live 和 Minecraft 服务的交互。如果您对详细的 API 实现感兴趣，请参阅[内部实现](/docs/development/implementation#1-身份验证系统-authentication)。

### 令牌管理

**访问令牌：**
- 短期有效（通常为 1 小时）
- 用于游戏身份验证
- 过期时自动刷新

**刷新令牌：**
- 长期有效（通常为 90 天）
- 安全存储在 `accounts.json` 中
- 用于获取新的访问令牌

**自动刷新：**
令牌过期时，DropOut 会在您启动游戏时尝试使用刷新令牌自动更新您的登录状态，确保您可以无缝开始游玩。

### 安全考虑

- 令牌存储在平台特定的应用数据目录中
- 所有 API 调用仅使用 HTTPS
- 不存储凭据（仅存储令牌）
- 需要 User-Agent 标头（绕过 MS WAF）

### Microsoft 登录故障排除

**"Device code expired"（设备代码已过期）**
- 代码在 15 分钟后过期
- 重新开始登录流程

**"Authorization pending"（授权待处理）**
- 在等待阶段很正常
- 在浏览器中完成授权

**"Invalid token"（无效令牌）**
- 令牌可能已过期
- 登出后重新登录

**"You don't own Minecraft"（您不拥有 Minecraft）**
- 验证您的 Microsoft 账户拥有 Minecraft Java Edition
- 在 https://www.minecraft.net/profile 检查

## 离线身份验证

### 概述

离线模式创建一个不需要互联网连接或 Microsoft 账户的本地账户。这对以下情况很有用：
- 测试和开发
- 无网络游玩
- LAN 多人游戏
- Mod 开发

### 创建离线账户

1. 在登录屏幕单击"离线模式"
2. 输入用户名（3-16 个字符）
3. 单击"创建账户"

### 工作原理

**UUID 生成：**
离线模式使用基于用户名的确定性 UUID 生成算法（UUID v3）。这意味着在同一个启动器实例中，相同的用户名始终会获得相同的 UUID，从而保持单人游戏存档的一致性。

- 确定性：相同的用户名 = 相同的 UUID
- 无需网络请求

**身份验证：**
- 返回 `"null"` 作为访问令牌
- Minecraft 在离线模式下接受空令牌
- 用户名和 UUID 本地存储

### 限制

- 无法加入在线服务器
- 不支持皮肤
- 不支持披风
- 无法使用 Microsoft 账户功能

## 账户管理

### 切换账户

目前 DropOut 一次只支持一个活跃账户。多账户支持正在规划中。

**切换账户的步骤：**
1. 登出当前账户
2. 使用新账户登录

### 账户存储

账户数据存储在应用文件夹的 `accounts.json` 中。该文件包含已登录账户的加密令牌、过期时间和基本的个人资料信息。

### 删除账户

删除账户的步骤：
1. 打开设置
2. 导航到账户
3. 单击"登出"
4. 或手动删除 `accounts.json`

## API 参考

关于身份验证的底层实现、OAuth 2.0 流程细节以及相关的 Tauri 命令接口，请参考开发文档：[实现细节：身份验证](../development/implementation.mdx#1-身份验证系统-authentication)。

## 最佳实践

1. **对官方服务器使用 Microsoft 账户**：为了能够加入官方服务器并使用正版皮肤，请务必使用 Microsoft 账户。
2. **保护令牌安全**：不要向他人分享 `accounts.json` 文件或其内容，因为其中包含您的登录凭据。
3. **定期刷新令牌**：长时间未使用的离线账户或过期的 Microsoft 令牌可以通过重新登录或启动游戏来刷新。
4. **仅在测试时使用离线模式**：离线模式不支持皮肤和部分多人游戏功能。