> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 登录和沙盒错误故障排除

> 在 PC 上使用 XblPCSandbox、预检清单、错误代码参考和 Partner Center 配置检查来诊断 XBOX Live 登录和沙盒错误。

本文有助于您诊断和修复 PC 开发沙盒中游戏常见的登录和沙盒相关错误。

## 本文内容

* [预检清单](#preflight-checklist)
* [诊断流程图](#diagnostic-flowchart)
* [帐户和沙盒错误](#account-and-sandbox-errors)
* [配置错误](#configuration-errors)
* [游戏特定故障排除](#game-specific-troubleshooting)
* [其他故障排除](#additional-troubleshooting)
* [错误代码快速参考](#error-code-quick-reference)

***

## 预检清单

在调查特定错误之前,请先完成此清单。大多数登录问题都是由以下某项配置错误导致。在继续查看下面的诊断流程图和错误部分之前,请核实**所有**以下项。

<Info>关键是要事先安装 XblPCSandbox.exe 工具。
有关如何获取该工具的更多详细信息,请参阅[沙盒概述](/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox)。</Info>

### 环境检查

这些项影响您是否能够登录 XBOX 服务(包括 XBOX 应用)。请先检查这些项。

***

### ✅ 1. 检查沙盒 ID 没有任何拼写错误

确保沙盒 ID 已正确输入。

**如何检查:**

```cmd theme={null}
XblPCSandbox /get
```

将输出与 Partner Center 中 **Gameplay settings** 页面上显示的沙盒进行比较。
您可以使用 [https://partner.microsoft.com/en-us/xboxconfig?appid=\[productId\],将](https://partner.microsoft.com/en-us/xboxconfig?appid=\[productId],将) \[productId] 参数替换为您各自的 *Product Id*。

**如何修复:**

```cmd theme={null}
XblPCSandbox <your sandbox ID>
```

有关切换沙盒的详细说明,请参阅[沙盒概述](/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox)。

***

### ✅ 2. 您的沙盒正确

您的 PC 必须与已发布您游戏 XBOX 服务配置的开发沙盒相同。

**如何检查:**

```cmd theme={null}
XblPCSandbox /get
```

将输出与 Partner Center 中 **Gameplay settings** 页面上显示的沙盒进行比较。
您可以使用 [https://partner.microsoft.com/en-us/xboxconfig?appid=\[productId\],将](https://partner.microsoft.com/en-us/xboxconfig?appid=\[productId],将) \[productId] 参数替换为您各自的 *Product Id*。

**如何修复:**

```cmd theme={null}
XblPCSandbox <your sandbox ID>
```

有关切换沙盒的详细说明,请参阅[沙盒概述](/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox)。

***

### ✅ 3. 您的测试帐户有效

测试帐户可能因多种原因而失效。请核实以下所有项:

#### 帐户对沙盒的访问权限尚未过期

测试帐户对沙盒的访问有过期日期。对沙盒访问已过期的帐户无法登录该沙盒。

**如何检查:**

1. 转到 [Partner Center](https://partner.microsoft.com/dashboard)。
2. 选择 **Apps and Games**。
3. 选择 **XBOX Test accounts**(或转到[测试帐户管理](https://partner.microsoft.com/dashboard/xbox/testaccounts))。
4. 查找您的测试帐户并检查 **Access Expires** 和 **Status** 列。

**如何修复:**

如果帐户已过期,请创建新的测试帐户或延长现有帐户的过期日期。

#### 该帐户具有访问您沙盒的权限

创建测试帐户时,您必须为其授予对特定沙盒的访问权限。

**如何检查:**

1. 在 Partner Center 中,转到 **XBOX services** > **Test accounts**。
2. 选择您的测试帐户。
3. 验证您的开发沙盒是否在该帐户的沙盒访问列表中。

**如何修复:**

编辑该测试帐户,并将您的开发沙盒添加到其访问列表中。

#### 凭据正确

请确保使用测试帐户的正确电子邮件地址和密码。测试帐户的电子邮件地址通常以 `@xboxtest.com` 结尾。

***

### ✅ 4. XBOX 游戏组件为最新版本

XBOX 服务依赖于您 PC 上的 XBOX 应用和 Gaming Services 组件。二者之一的过时版本都可能导致意外的登录失败。

**如何检查:**

1. 请按照[游戏修复工具](https://support.xbox.com/en-MD/help/games-apps/troubleshooting/gaming-services-repair-tool)提供的信息操作。

***

### ✅ 5. 重新启动您的 PC

有时,登录所需的后台服务(例如 XBOX Live Auth Manager 或 Gaming Services)会进入错误状态。重新启动 PC 可以解决上述步骤无法处理的临时问题。

在此之前,重要的是通过反馈中心 (Feedback Hub) 提交错误,以便对其进行跟踪并在未来版本中解决。

您可以使用以下命令执行此操作:

```cmd theme={null}
XblPCSandbox /feedback
```

或者,如果直接从反馈中心执行,请使用 **Category: Gaming and XBOX** 和 **Area: Developer Tools**。

**何时执行此操作:**

如果您已验证上述所有环境检查但登录仍失败,请重新启动 PC 并重试,然后再继续项目检查。

***

### 项目检查

这些项特别影响从您游戏中的登录。如果您可以登录 XBOX 应用但无法从您的游戏登录,请从此处开始。

***

### ✅ 6. 您的 ID 与 Partner Center 匹配

`MicrosoftGame.config` 中的 ID 必须与 Partner Center 中的值完全匹配。哪怕只有一个值不匹配也会阻止登录。

**如何检查:**

打开您的 `MicrosoftGame.config`,并将这些值与 Partner Center 中的值进行比较:

| MicrosoftGame.config 字段 | 在 Partner Center 中的查找位置                                                               |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `StoreId`               | **Game Setup** > **Identity details** > **Show details** > Store ID                   |
| `Identity/Name`         | **Game Setup** > **Identity details** > **Show details** > Package/Identity/Name      |
| `Identity/Publisher`    | **Game Setup** > **Identity details** > **Show details** > Package/Identity/Publisher |
| `TitleId`               | **XBOX services** > **XBOX Settings** > Title ID(**十六进制**值,而非十进制)                     |
| `MSAAppId`              | **XBOX services** > **XBOX Settings** > MSA App ID(可以是 GUID 或十六进制)                    |

此外,检查 **SCID**(服务配置 ID)。SCID 不在您的 `MicrosoftGame.config` 中,而是作为参数传递给 [XblInitialize](/reference/live/xsapi-c/xbox_live_global_c/functions/xblinitialize) 方法。可在 Partner Center 中 **XBOX services** > **XBOX Settings** 下找到它。

<Tip>使用 [MicrosoftGame.config 编辑器](/build/core-features/common/game-config/MicrosoftGameConfig-Editor)中的 **Store Association Wizard** 自动关联您的游戏,以减少拼写错误的可能性。</Tip>

***

### ✅ 7. XBOX 服务配置已发布到您的沙盒

即使在 Partner Center 中保存了更改,也需要将其发布到您的开发沙盒后**才会**生效。

**如何检查:**

1. 转到 [Partner Center](https://partner.microsoft.com/dashboard)。
2. 选择您的产品。
3. 导航到 **XBOX services** > **Gameplay settings**。
4. 选择您的开发沙盒对应的选项卡。
5. 检查发布状态。

**如何修复:**

如果尚未发布更改,请选择 **Publish**,将更改推送到您的开发沙盒。等待大约 **30 分钟**让更改生效,然后再进行测试。

<Warning>在 XBOX Settings 页面上单击 **Save** **不会**发布更改。您必须从 **Gameplay settings** 页面显式发布。</Warning>

***

### ✅ 8. 已启用 PC 平台

如果您在 PC 上开发,则必须为您的标题启用 **Windows 10 PC**(及更高版本)平台。否则,登录将失败并显示错误 `0x87dd0005 (AM_E_XAST_UNEXPECTED)`。

**如何检查:**

1. 转到 [Partner Center](https://partner.microsoft.com/dashboard)。
2. 选择您的产品。
3. 导航到 **XBOX services** > **XBOX Settings**。
4. 确认 **Windows 10 PC** 复选框已**勾选**。对最新的 Windows 版本也是如此。

**如何修复:**

1. 勾选 **Windows 10 PC** 复选框。
2. 选择 **Save**。
3. 转到 **Gameplay settings** 并将设置**发布**到您的开发沙盒。
4. 等待大约 **30 分钟**后再进行测试。

***

## 诊断流程图

如果预检清单未能解决您的问题,请使用此逐步流程缩小根本原因范围。从第 1 步开始,并沿分支进行。

```
┌─────────────────────────────────────────────────────────┐
│                  仍然无法登录?                          │
│              完成预检清单后从此处开始                    │
│                                                         │
└───────────────────────┬─────────────────────────────────┘
                        │
                        ▼
        ┌───────────────────────────────┐
        │  第 1 步:您能否使用测试帐户  │
        │  登录 Xbox 应用?             │
        │                               │
        └───────┬───────────────┬───────┘
                │               │
            是  ▼           否  ▼
    ┌───────────────┐   ┌──────────────────────────────────────────────┐
    │  沙盒和帐户   │   │  沙盒或帐户问题。请检查:                    │
    │  正常运行。   │   │                                              │
    │  转到第 2 步  │   │  • 沙盒 ID 是否正确?                        │
    │               │   │  • 帐户对沙盒的访问是否过期?                │
    │               │   │  • 帐户是否具有沙盒访问权限?                │
    │               │   │  • 凭据是否正确?                            │
    │               │   │  • Xbox 应用是否为最新版本?                 │
    │               │   │  • Xbox 应用是否已获得授权?                 │
    │               │   │                                              │
    │               │   │  请参阅下方"帐户和沙盒错误"                  │
    └───────┬───────┘   └──────────────────────────────────────────────┘
            │
            ▼
┌───────────────────────────────┐
│  第 2 步:您能否使用您游戏的  │
│  ID 登录示例项目?            │
└───────┬───────────────┬───────┘
        │               │
    是  ▼           否  ▼
┌───────────────┐   ┌──────────────────────────────┐
│  配置正常运行。│   │  配置问题。请检查:          │
│  转到第 3 步   │   │                              │
│               │   │  • MicrosoftGame.config 中的  │
│               │   │    ID 是否正确?              │
│               │   │  • 游戏设置是否已发布到       │
│               │   │    沙盒?                     │
│               │   │  • 是否已启用 PC 平台?       │
│               │   │  • XblInitialize 中的 SCID   │
│               │   │    是否正确?                 │
│               │   │                              │
│               │   │  请参阅下方"配置错误"        │
└───────┬───────┘   └──────────────────────────────┘
        │
        ▼
┌───────────────────────────────┐
│  第 3 步:游戏特定问题        │
│  示例可用但您的游戏不可用。   │
│                               │
│  • 比较 MicrosoftGame         │
│    .config 文件               │
│  • 比较登录代码               │
│  • 查看下方参考表中的错误代码 │
└───────────────────────────────┘
```

***

## 帐户和沙盒错误

如果您**无法**登录 XBOX 应用([诊断流程图](#diagnostic-flowchart)第 1 步),则问题出在您的沙盒切换、测试帐户或 XBOX 应用本身。

### 用户不在此沙盒中 (0x8015DC12)

测试帐户没有访问该沙盒的权限,或者游戏配置与该沙盒不匹配。

**常见原因和修复:**

| 原因                                                | 修复                                                                                                  |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `MicrosoftGame.config` 中的 ID 与 Partner Center 不匹配 | 请参见[清单项 1](#-1-review_the_sandbox_Id_does_not_have_any_typos) 和[清单项 2](#-2-your-sandbox-is-correct) |
| 测试帐户没有沙盒访问权限                                      | 在 Partner Center 中编辑测试帐户并添加您的沙盒                                                                     |
| 测试帐户对沙盒的访问已过期                                     | 在 Partner Center 中检查过期日期;创建新帐户或延长过期时间                                                               |
| 使用了独立沙盒而非共享沙盒                                     | 在 Partner Center 中检查沙盒类型;除非您有特定原因使用独立沙盒,否则切换到共享沙盒。请参阅[独立与共享沙盒](#isolated-vs-shared-sandboxes)。      |

### 沙盒 ID 不正确

常见错误包括:

* 缺少或多余的字符:`XDKS1` 而不是 `XDKS.1`
* 错误的沙盒:切换到了与您游戏配置发布的沙盒不同的沙盒

**如何修复:**

1. 运行 `XblPCSandbox /get` 并将输出与 Partner Center 进行比较。
2. 使用 Partner Center 中的确切值重新运行 `XblPCSandbox <正确的沙盒 ID>`。

### 测试帐户的沙盒错误 (Garrison error)

如果您看到一条错误消息暗示您的帐户应在其他沙盒中工作,或者 XBOX 身份服务在登录期间返回意外错误,则可能是您登录了该测试帐户的错误沙盒。

**如何修复:**

1. 运行 `XblPCSandbox /get` 以确认您的 PC 设置为哪个沙盒。
2. 在 Partner Center 中,转到 **XBOX services** > **Test accounts** 并验证您的测试帐户是否有权访问该沙盒。
3. 如果沙盒不匹配,切换到正确的沙盒:`XblPCSandbox <正确的沙盒 ID>`

### XBOX 应用授权错误 (0x803F8001)

如果您之前未在 RETAIL 中打开过 XBOX 应用,则该应用可能无法启动。

**如何修复:**

1. 切换到 RETAIL:`XblPCSandbox /retail`(或 `XblPCSandbox RETAIL`)
2. 打开 XBOX 应用并让其完全启动。
3. 切换回您的开发沙盒:`XblPCSandbox <您的沙盒 ID>`

### 找不到 XBOX 应用

XBOX 应用可在 Microsoft Store 中获取,**但仅当您处于 RETAIL 沙盒中时**。如果找不到:

1. 切换到 RETAIL:`XblPCSandbox /retail`(或 `XblPCSandbox RETAIL`)
2. 在 Microsoft Store 中搜索 "XBOX" 并安装。
3. 切换回您的沙盒。

***

## 配置错误

如果您**能够**登录 XBOX 应用,但**无法**在您的游戏或示例项目中登录([诊断流程图](#diagnostic-flowchart)第 2 步),则问题出在您游戏的 XBOX 服务配置上。

### PC 平台未启用 (0x87dd0005, AM\_E\_XAST\_UNEXPECTED)

此错误表示未在 Partner Center 中添加 Windows 10 PC 平台。也请检查更高版本。

**如何修复:**

1. 在 Partner Center 中,导航到您的产品 > **XBOX services** > **XBOX Settings**。
2. 勾选 **Windows 10 PC** 复选框。
3. 选择 **Save**。
4. 转到 **Gameplay settings** 并将设置**发布**到您的开发沙盒。
5. 等待 **30 分钟**,然后再次尝试登录。

<Warning>在 XBOX Settings 页面上单击 **Save** **不会**发布更改。要使登录生效,您必须从 **Gameplay settings** 页面显式发布。</Warning>

### XBOX 服务配置未发布

在 Partner Center 中保存的更改在发布到您的开发沙盒之前不会生效。

**如何修复:**

1. 在 Partner Center 中转到 **XBOX services** > **Gameplay settings**。
2. 选择您的开发沙盒选项卡。
3. 选择 **Publish**。
4. 等待大约 **30 分钟**让更改生效。

### MicrosoftGame.config 中的 ID 不正确

登录错误的常见原因是 `MicrosoftGame.config` 中的一个或多个值不匹配。

**如何修复:**

使用 [MicrosoftGame.config 编辑器](/build/core-features/common/game-config/MicrosoftGameConfig-Editor)中的 **Store Association Wizard** 关联您的游戏并自动填充正确的值。或者根据[清单项 1](#-1-your-ids-match-partner-center) 手动根据 Partner Center 验证每个值。

### XblInitialize 中的 SCID 不正确

SCID **不在** `MicrosoftGame.config` 中,而是作为参数传递给 [XblInitialize](/reference/live/xsapi-c/xbox_live_global_c/functions/xblinitialize)。请确保您传递的是来自 Partner Center(**XBOX services** > **XBOX Settings**)的正确 SCID。

### 独立与共享沙盒

除非您有特定原因使用独立沙盒,否则请使用**共享**沙盒。您可以在 Partner Center 中检查您的沙盒类型。独立沙盒具有额外的限制,可能会导致登录失败。

***

## 游戏特定故障排除

如果 XBOX 应用登录成功,**并且**示例项目可与您游戏的 ID 一起使用,但您的游戏仍无法登录([诊断流程图](#diagnostic-flowchart)第 3 步),则问题特定于您游戏的代码或配置。

### 比较 MicrosoftGame.config 文件

将您游戏的 `MicrosoftGame.config` 与可用示例进行差异比较。查找额外或缺失的字段、格式差异或不正确的值。

### 比较登录代码

将您游戏的登录实现与示例代码进行比较。查找 `XUserAddAsync` 的调用方式差异(选项、回调、错误处理)。

### 无默认用户 (0x89245106, E\_GAMEUSER\_NO\_DEFAULT\_USER)

此错误表示当前没有默认用户登录。

**原因:** 您使用 `AddDefaultUserSilently` 选项调用了 `XUserAddAsync`,但当前没有用户登录。

**如何修复:**

有关更多信息,请参阅 [`XUserAddAsync`](/reference/system/xuser/functions/xuseraddasync) 和 [AdvancedUserModel](/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-advancedusermodel)。

***

## 其他故障排除

### XBOX 服务正在遭遇中断

如果您已尝试所有其他选项,请检查 XBOX 服务是否正在中断:

* [XBOX 状态页面](https://support.xbox.com/xbox-live-status)

> \[!IMPORTANT]
> **已知限制 (GDK 26.04):** 通过 SSH 会话运行时,`XblPCSandbox` 无法切换
> 沙盒。请从本地会话运行 `XblPCSandbox`。

***

## 错误代码快速参考

| 错误代码         | 名称                           | 可能原因                                                | 修复                                                                                                                                                                                                         |
| ------------ | ---------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0x8015DC12` | 用户不在沙盒中                      | ID 不匹配、无沙盒访问权限、测试帐户对沙盒的访问已过期或使用了独立沙盒                | 请参阅[清单](#preflight-checklist);验证 ID、帐户访问权限和沙盒类型                                                                                                                                                            |
| `0x87dd0005` | `AM_E_XAST_UNEXPECTED`       | Partner Center 中未启用 PC 平台                           | 在 XBOX Settings 中启用 **Windows 10(及更高版本)PC**,**发布**到沙盒,等待 30 分钟                                                                                                                                             |
| `0x89245106` | `E_GAMEUSER_NO_DEFAULT_USER` | 无默认用户登录;调用了 `XUserAddAsync(AddDefaultUserSilently)` | 有关如何解决此问题的更多信息,请参阅 [`XUserAddAsync`](/reference/system/xuser/functions/xuseraddasync) 和 [AdvancedUserModel](/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-advancedusermodel)。 |
| `0x803F8001` | 授权错误                         | 之前未在 RETAIL 中启动过 XBOX 应用                            | 切换到 RETAIL、启动 XBOX 应用、切换回开发沙盒                                                                                                                                                                              |
| `0x80004005` | 一般登录失败                       | 沙盒或帐户配置错误;也可能表示服务端问题                                | 完成[预检清单](#preflight-checklist);验证沙盒 ID、测试帐户访问权限和帐户过期时间。如果问题仍然存在,请尝试重新启动 PC 并重新切换沙盒。                                                                                                                        |

<Note>
  如果您看到此处未列出的错误代码,请通过反馈中心提交问题。

  使用 xblPcSandbox /feedback 提交错误

  或者,如果直接从反馈中心提交,请使用 **Category: Gaming and XBOX** 和 **Area: Developer Tools**
</Note>

***

## 另请参见

* [沙盒概述](/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox)
* [高级沙盒概念概述](/services/xbox-services/fundamentals/sandboxes/live-advanced-sandboxes)
* [测试帐户](/services/xbox-services/develop/test-accounts/live-test-accounts)
* [XBOX 服务配置概述](/services/xbox-services/fundamentals/portal-config/live-portal-config-overview)
* [MicrosoftGame.config 概述](/build/core-features/common/game-config/MicrosoftGameConfig-Overview)
* [XblPCSandbox.exe 参考](/tools/tools-services/live-pc-sandbox-switcher)


## Related topics

- [故障排除](/zh-CN/services/xbox-services/develop/troubleshooting/index.md)
- [PC 沙盒切换器 (XblPCSandbox.exe)](/zh-CN/tools/tools-services/live-pc-sandbox-switcher.md)
- [XBOX 服务登录故障排除](/zh-CN/services/xbox-services/fundamentals/identity/auth/live-troubleshooting-sign-in.md)
- [XBOX 服务沙盒概述](/zh-CN/services/xbox-services/fundamentals/sandboxes/live-setup-sandbox.md)
- [多人游戏常见问题和故障排除](/zh-CN/services/xbox-services/multiplayer/mpsd/concepts/live-multiplayer-2015-faq.md)