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 离线模式。
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 出现之前发生的故障？
仅限进程外。 在同步 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）。
E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD 完成，并且之后 PFGameSaveFilesIsConnectedToCloud() 返回 false。请参阅上传何时使会话进入离线状态。
请将 E_PF_GAMESAVE_USER_CANCELLED 与其他失败区分处理，以便区分“玩家已取消”和“上传出错”。这与初次同步使用的取消代码相同，因此一次检查即可涵盖这两种操作。
哪些错误表示“你传入了错误的内容”，哪些表示暂时性问题？
请参阅 Game Saves 离线模式中的完整 HRESULT 参考。
建议
- 将
PFGameSaveFilesInitialize故障视为需要修复的 bug（参数/配置错误），而不是需要重试的运行时情况。 - 进程内： 始终在
PFGameSaveFilesAddUserWithUiAsync之前注册 UI 回调（至少注册同步失败回调），以便暂时性故障为玩家提供 Retry/Use Offline，而不是硬错误。 - 进程外： 做好准备，
PFGameSaveFilesAddUserWithUiAsync可能在任何 UI 出现之前就返回原始故障（服务/配置）。对暂时性故障进行重试；将配置问题作为错误呈现。 - 根据最终结果控制游玩：
S_OK+ 已连接 → 在线游玩；S_OK+ 未连接 → 离线游玩（警告玩家存档不会同步）；取消/失败且无文件夹 → 阻止游玩。