Game Saves 錯誤處理常見問題集
本文回答有關 Game Saves 如何回報失敗的常見問題：哪些錯誤是暫時性的 (值得重試)、哪些表示您傳入了錯誤的內容 (修正呼叫)，以及系統何時會進入離線模式而不是傳回錯誤。 Game Saves 會依平台以兩種方式之一執行，兩者的錯誤處理略有不同：- 處理程序外：由平台的內建服務執行同步並顯示其自己的系統 UI。在 XBOX 和 Windows 上，Game Saves 一律以此方式執行。
- 處理程序內：在無法使用平台服務的平台上 (例如 Steam Deck)，由 SDK 自行執行雲端同步。您的遊戲透過回呼來驅動 UI。
Game Saves 何時會進入離線狀態而不是傳回錯誤？
離線模式是成功的結果，而不是錯誤。初始同步 (PFGameSaveFilesAddUserWithUiAsync) 只有在玩家於同步失敗提示中明確選擇 Use Offline / Play offline 時 (或當另一部裝置成為作用中裝置時)，才會進入離線模式。在這種情況下，非同步作業會以 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 (進度指示器，以及遇到錯誤時的同步失敗提示)，玩家可以退出其中任一個。當玩家退出時，作業會以 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失敗視為需要修正的錯誤 (引數/設定錯誤)，而不是需要重試的執行階段狀況。 - 處理程序內： 一律在
PFGameSaveFilesAddUserWithUiAsync之前註冊您的 UI 回呼 (至少要有同步失敗回呼)，讓暫時性失敗為玩家提供 Retry/Use-Offline，而不是硬性錯誤。 - 處理程序外： 準備好因應
PFGameSaveFilesAddUserWithUiAsync在任何 UI 出現之前的原始失敗 (服務/設定)。重試暫時性失敗；將設定問題以錯誤形式呈現。 - 依最終結果決定是否允許遊玩：
S_OK+ 已連線 → 線上遊玩；S_OK+ 未連線 → 離線遊玩 (警告玩家存檔不會同步)；取消/失敗且沒有資料夾 → 封鎖遊玩。