> ## 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 何時會進入離線狀態而不是傳回錯誤？ 離線模式是**成功**的結果，而不是錯誤。初始同步 (`PFGameSaveFilesAddUserWithUiAsync`) 只有在玩家於同步失敗提示中明確選擇 **Use Offline / Play offline** 時 (或當另一部裝置成為作用中裝置時)，才會進入離線模式。在這種情況下，非同步作業會以 `S_OK` 完成，且 `PFGameSaveFilesIsConnectedToCloud()` 會傳回 `false`。您仍會取得可用的本機存檔資料夾。 如果玩家刻意選擇 **Cancel**，則會以 `E_PF_GAMESAVE_USER_CANCELLED` 完成，且**不會**提供存檔資料夾。請將此視為「不允許遊玩」。如果您的遊戲自行使用 `XAsyncCancel` 取消非同步作業，則會改以 `E_ABORT` 完成，同樣沒有存檔資料夾；請將 `E_ABORT` 視為您自己的取消。 如需完整的決策表和錯誤碼參考，請參閱 [Game Saves 離線模式](/zh-TW/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-TW/services/playfab/player-progression/game-saves/ui-callbacks)。 ## 是否有在任何 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`)。 上傳仍可能以工作階段**離線**結束。當工作階段原本就處於離線狀態、雲端有來自另一部裝置的較新存檔，或玩家在先前部分失敗的上傳之後出現的重新鎖定提示中選擇 **Use Offline** 時，上傳會以 `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD` 完成，之後 `PFGameSaveFilesIsConnectedToCloud()` 會傳回 `false`。請參閱[上傳何時會使工作階段離線](/zh-TW/services/playfab/player-progression/game-saves/offline#when-an-upload-takes-the-session-offline)。 請將 `E_PF_GAMESAVE_USER_CANCELLED` 與其他失敗分開處理，以便區分「玩家已取消」和「上傳發生錯誤」。這與初始同步使用的取消碼相同，因此單一檢查即可涵蓋這兩種作業。 ## 哪些錯誤表示「您傳入了錯誤的內容」，哪些表示暫時性問題？ | 結果 | 意義 | 可重試？ | | - | - | - | | `E_INVALIDARG` | 引數錯誤 (null 指標、無效/缺少存檔資料夾、選項互相衝突)。 | 否——請修正呼叫。 | | `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-TW/services/playfab/player-progression/game-saves/offline#game-saves-error-codes)中的完整 HRESULT 參考。 ## 建議 * 將 `PFGameSaveFilesInitialize` 失敗視為**需要修正的錯誤** (引數/設定錯誤)，而不是需要重試的執行階段狀況。 * **處理程序內：** 一律在 `PFGameSaveFilesAddUserWithUiAsync` 之前註冊您的 UI 回呼 (至少要有同步失敗回呼)，讓暫時性失敗為玩家提供 Retry/Use-Offline，而不是硬性錯誤。 * **處理程序外：** 準備好因應 `PFGameSaveFilesAddUserWithUiAsync` 在任何 UI 出現之前的原始失敗 (服務/設定)。重試暫時性失敗；將設定問題以錯誤形式呈現。 * 依最終結果決定是否允許遊玩：`S_OK` + 已連線 → 線上遊玩；`S_OK` + 未連線 → 離線遊玩 (警告玩家存檔不會同步)；取消/失敗且沒有資料夾 → 封鎖遊玩。 ## 相關內容 * [Game Saves 離線模式](/zh-TW/services/playfab/player-progression/game-saves/offline) * [Game Saves UI 回呼](/zh-TW/services/playfab/player-progression/game-saves/ui-callbacks) * [Game Saves 衝突](/zh-TW/services/playfab/player-progression/game-saves/conflicts) * [Game Saves 作用中裝置變更](/zh-TW/services/playfab/player-progression/game-saves/activedevicechanges) ## Related topics - [GameInput 常見問題集](/zh-TW/build/core-features/common/input/overviews/input-faq.md) - [PC 開發人員常見問題集](/zh-TW/build/gdk-and-engines/guides/pc-faq.md) - [Economy 第 2 版 (V2) 常見問題集](/zh-TW/services/playfab/economy-monetization/economy-v2/faq.md) - [XBOX Game Publisher Insights 常見問題集](/zh-TW/publishing/game-publishing/concepts/game-publisher-insights/game-publisher-insights-faq.md) - [XBOX 測試人員計畫測試版發行常見問題集](/zh-TW/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-xbox-flighting-faq.md)