> ## 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.

# Game Saves 错误处理常见问题

> Game Saves 错误处理常见问题，涵盖暂时性故障、无效输入，以及系统何时进入离线模式而不是返回错误。

# Game Saves 错误处理常见问题

本文解答有关 Game Saves 如何报告故障的常见问题：哪些错误是**暂时性的**（值得重试），哪些错误表示**你传入了错误的内容**（需要修正调用），以及系统何时会进入**离线模式**而不是返回错误。

根据平台的不同，Game Saves 以以下两种方式之一运行，两者的错误处理略有不同：

* **进程外**：由平台的内置服务执行同步并显示其自己的系统 UI。在 XBOX 和 Windows 上，Game Saves 始终以这种方式运行。
* **进程内**：在平台服务不可用的平台上（例如 Steam Deck），由 SDK 自行执行云同步。你的游戏通过回调驱动 UI。

## Game Saves 何时会进入离线模式而不是返回错误？

离线模式是一种**成功**结果，而不是错误。只有当玩家在同步失败提示中明确选择 **Use Offline / Play offline** 时（或当另一台设备成为活动设备时），初次同步（`PFGameSaveFilesAddUserWithUiAsync`）才会进入离线模式。在这种情况下，异步操作以 `S_OK` 完成，并且 `PFGameSaveFilesIsConnectedToCloud()` 返回 `false`。你仍然会获得一个可用的本地存档文件夹。

如果玩家主动选择 **Cancel**，则操作会以 `E_PF_GAMESAVE_USER_CANCELLED` 完成，并且**不**提供存档文件夹——请将其视为“不允许游玩”。如果你的游戏自行使用 `XAsyncCancel` 取消异步操作，则操作会改为以 `E_ABORT` 完成，同样不提供存档文件夹；请将 `E_ABORT` 视为你自己发起的取消。

有关完整的决策表和错误代码参考，请参阅 [Game Saves 离线模式](/zh-CN/services/playfab/player-progression/game-saves/offline#when-game-saves-enters-offline-mode-or-returns-an-error)。

## `PFGameSaveFilesInitialize` 会出现暂时性故障吗？

**不会。** `PFGameSaveFilesInitialize` 仅验证其参数并设置状态——它不会访问网络。它返回的每种故障都是确定性的：

* `E_INVALIDARG`：缺少必需的参数或参数无效。在进程内模式下，这包括缺少或无效的 `saveFolder`（在这些平台上必须提供有效的文件夹；在 XBOX/GDK 上，位置是固定的，该参数会被忽略）。
* `E_PF_GAMESAVE_ALREADY_INITIALIZED`：你调用了两次，且中间没有调用 `PFGameSaveFilesUninitializeAsync`。

如果 `Initialize` 失败，重试无济于事——请修正输入。如果对于给定配置它成功过一次，之后它不会自行开始失败。

## `PFGameSaveFilesAddUserWithUiAsync` 会出现暂时性故障吗？

**会**——这是执行网络同步的调用，因此可能会遇到暂时性故障（网络中断、服务错误、令牌刷新、磁盘空间不足）。HTTP 调用会根据游戏的 HTTP 重试设置（`PFHttpRetrySettings`）进行重试，但无法保证暂时性故障会在你的游戏感知到之前得到解决。

如果这些重试未能解决暂时性故障，该故障会通过**同步失败 UI** 呈现，由玩家选择 **Retry**、**Use Offline** 或 **Cancel**——或者，在进程内模式下如果未注册同步失败回调，它将作为原始 HRESULT 返回。因此，暂时性故障通常会最终变为在线、离线或取消，而不是原始错误——**但两种路径之间有一个重要区别**（请参阅下一个问题）。

`PFGameSaveFilesAddUserWithUiAsync` 也可能返回非暂时性且不可重试的**确定性**错误：

* `E_INVALIDARG`：句柄/异步块为 null，或选项相互冲突。
* `E_PF_GAMESAVE_NOT_INITIALIZED`：在 `Initialize` 之前调用。
* `E_PF_GAMESAVE_USER_ALREADY_ADDED`：该用户已添加（且仍处于连接状态）。

## 我是否需要注册 UI 回调才能获得离线选项？

这是两种路径之间的关键区别：

* **进程内：需要。** 只有在调用 `PFGameSaveFilesAddUserWithUiAsync` 之前（通过 `PFGameSaveFilesSetUiCallbacks`）注册了同步失败回调，暂时性同步故障才会回退到离线模式。**如果未注册回调，暂时性故障会以原始错误 HRESULT 完成操作——既没有 Retry，也没有 Use Offline。** 在没有内置 Game Saves UI 的平台上，必须注册这些回调。
* **进程外：对于一般同步故障不需要。** 平台的内置系统 UI 会自动提供 **Try again** / **Play offline** 选项，因此同步期间的一般网络故障无需任何游戏回调即可为玩家提供离线选项。你仍然可以注册回调来提供自己的 UI。

有关回调和内置系统 UI 的详细信息，请参阅 [Game Saves UI 回调](/zh-CN/services/playfab/player-progression/game-saves/ui-callbacks)。

## 是否存在在任何 UI 出现*之前*发生的故障？

**仅限进程外。** 在同步 UI 出现之前，`PFGameSaveFilesAddUserWithUiAsync` 会收集服务配置并（可选）让用户登录。早期设置故障——例如平台服务暂时不可用，或游戏未针对 Game Saves 进行配置——可能会在显示任何对话框之前以原始 HRESULT 完成调用。其中一些是暂时性的（稍后重试整个 `PFGameSaveFilesAddUserWithUiAsync`）；另一些则表示配置问题（确定性）。登录/令牌故障会得到妥善处理，其本身不会导致调用失败。

在进程内模式下，`AddUserWithUiAsync` 没有这类早期设置故障——故障发生在同步期间，并通过同步失败 UI 呈现（受上述回调要求的约束）。

## 上传可以取消吗？

**可以。** `PFGameSaveFilesUploadWithUiAsync` 会显示 UI（进度指示器，以及在遇到错误时显示的同步失败提示），玩家可以从其中任一 UI 中退出。在这种情况下，操作会以 `E_PF_GAMESAVE_USER_CANCELLED`（`0x800704C7`）完成，并且存档**不会**被上传。

与初次同步不同，上传没有 **Use Offline** 成功结果。其最终结果为：

* **成功**（`S_OK`）：已保存到云端。
* **已取消**（`E_PF_GAMESAVE_USER_CANCELLED`）：玩家主动退出。
* **被你的游戏取消**（`E_ABORT`）：你的游戏对上传调用了 `XAsyncCancel`。
* **失败**：其他所有情况（例如 `E_PF_GAMESAVE_NETWORK_FAILURE` 或 `E_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE`）。

上传结束时会话仍可能处于**离线**状态。当会话已经处于离线状态、云端有来自另一台设备的较新存档，或玩家在之前部分失败的上传之后出现的重新锁定提示中选择 **Use Offline** 时，上传会以 `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD` 完成，并且之后 `PFGameSaveFilesIsConnectedToCloud()` 返回 `false`。请参阅[上传何时使会话进入离线状态](/zh-CN/services/playfab/player-progression/game-saves/offline#when-an-upload-takes-the-session-offline)。

请将 `E_PF_GAMESAVE_USER_CANCELLED` 与其他失败区分处理，以便区分“玩家已取消”和“上传出错”。这与初次同步使用的取消代码相同，因此一次检查即可涵盖这两种操作。

## 哪些错误表示“你传入了错误的内容”，哪些表示暂时性问题？

| 结果 | 含义 | 是否可重试？ |
| - | - | - |
| `E_INVALIDARG` | 参数错误（空指针、无效/缺少存档文件夹、选项相互冲突）。 | 否——请修正调用。 |
| `E_PF_GAMESAVE_NOT_INITIALIZED` / `E_PF_GAMESAVE_ALREADY_INITIALIZED` | 调用顺序错误。 | 否——请修正调用顺序。 |
| `E_PF_GAMESAVE_USER_ALREADY_ADDED` / `E_PF_GAMESAVE_USER_NOT_ADDED` | 此调用的状态不正确。 | 否——请修正调用顺序。 |
| 在 `AddUserWithUiAsync` 期间触发同步失败 UI | 暂时性网络/服务故障。 | 是——Retry 或 Use Offline。 |
| `E_PF_GAMESAVE_NETWORK_FAILURE`（来自 `PFGameSaveFilesUploadWithUiAsync`） | 暂时性上传故障；仍处于连接状态。 | 是——请稍后重试。 |
| `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD` | 你处于离线模式。 | 否——你选择了离线（或失去了活动设备状态）。 |
| `E_PF_GAMESAVE_DISK_FULL` | 本地磁盘空间不足。 | 在玩家释放空间之后。 |
| `E_PF_GAMESAVE_OPERATION_IN_PROGRESS` | 此用户已有冲突的操作正在运行：另一个上传或云端重置（针对上传和添加用户），或者任何上传、下载或重置（针对 `PFGameSaveFilesResetCloudAsync`）。 | 是——在正在进行的操作完成之后。 |
| `E_PF_GAMESAVE_LOCAL_FILE_UNAVAILABLE`（来自 `PFGameSaveFilesUploadWithUiAsync`） | 无法读取本地存档文件（例如该文件仍以写入方式打开）。 | 是——在游戏停止写入该文件之后。 |
| `E_PF_GAMESAVE_USER_CANCELLED` | 玩家在 UI 提示中选择了取消。 | 否。 |
| `E_ABORT` | 你的游戏使用 `XAsyncCancel` 取消了异步操作。 | 仅当你的游戏再次启动该操作时。 |

请参阅 [Game Saves 离线模式](/zh-CN/services/playfab/player-progression/game-saves/offline#game-saves-error-codes)中的完整 HRESULT 参考。

## 建议

* 将 `PFGameSaveFilesInitialize` 故障视为**需要修复的 bug**（参数/配置错误），而不是需要重试的运行时情况。
* **进程内：** 始终在 `PFGameSaveFilesAddUserWithUiAsync` 之前注册 UI 回调（至少注册同步失败回调），以便暂时性故障为玩家提供 Retry/Use Offline，而不是硬错误。
* **进程外：** 做好准备，`PFGameSaveFilesAddUserWithUiAsync` 可能在任何 UI 出现之前就返回原始故障（服务/配置）。对暂时性故障进行重试；将配置问题作为错误呈现。
* 根据最终结果控制游玩：`S_OK` + 已连接 → 在线游玩；`S_OK` + 未连接 → 离线游玩（警告玩家存档不会同步）；取消/失败且无文件夹 → 阻止游玩。

## 相关内容

* [Game Saves 离线模式](/zh-CN/services/playfab/player-progression/game-saves/offline)
* [Game Saves UI 回调](/zh-CN/services/playfab/player-progression/game-saves/ui-callbacks)
* [Game Saves 冲突](/zh-CN/services/playfab/player-progression/game-saves/conflicts)
* [Game Saves 活动设备变更](/zh-CN/services/playfab/player-progression/game-saves/activedevicechanges)


## Related topics

- [处理常见错误情形](/zh-CN/services/playfab/multiplayer/matchmaking/error-cases.md)
- [GameInput 常见问题](/zh-CN/build/core-features/common/input/overviews/input-faq.md)
- [XBOX Insider 计划 Flighting 常见问题](/zh-CN/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-xbox-flighting-faq.md)
- [PC 开发者常见问题](/zh-CN/build/gdk-and-engines/guides/pc-faq.md)
- [Economy 版本 2 (V2) 常见问题解答](/zh-CN/services/playfab/economy-monetization/economy-v2/faq.md)