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

# 2025 年 10 月 Microsoft Game Development Kit (GDK) 版本資訊

> 說明 2025 年 10 月 Microsoft Game Development Kit (GDK) 的重大變更、通知、錯誤修正和已知問題。

## 簡介

歡迎使用 2025 年 10 月 Microsoft Game Development Kit 版本。您可以使用 GDK 開發可通過認證並獲准在 Windows 11 電腦和 Windows 10 電腦上發行的遊戲。

### 關於本文件

本文件分為下列各節。

* [新功能](#whats-new-in-the-october-2025-microsoft-game-development-kit)
* **版本資訊：**
  * [2025 年 10 月 GDK Update 5](#october-2025-gdk-update-5)
  * [2025 年 10 月 GDK Update 4](#october-2025-gdk-update-4)
  * [2025 年 10 月 GDK Update 3](#october-2025-gdk-update-3)
  * [2025 年 10 月 GDK Update 2](#october-2025-gdk-update-2)
  * [2025 年 10 月 GDK Update 1](#october-2025-gdk-update-1)
  * [2025 年 10 月 GDK](#october-2025-gdk)
* [已知問題](#known-issues)
* [文件](#documentation)

### 2025 年 10 月 Microsoft Game Development Kit 的新功能

> * GDK 的發行分為兩種類型：主要版本 (著重於功能，每年兩次) 和更新 (著重於修正，視需求隨時發行)。
> * 若要檢視完整的新功能章節，請參閱線上版的[新功能](https://docs.xbox.com/zh-TW/announcements/gdk/whats-new.md)。

## 2025 年 10 月 GDK Update 5

### 問題修正

#### XBOX 服務

> 修正在沒有網路連線的情況下於 Steam Deck 上啟動的遊戲，永遠偵測不到網路變為可用，導致登入和其他 HTTP 要求在重新啟動遊戲之前都會失敗的問題。\[64171298]

#### Social Manager

> 修正 Social Manager 在載入大型社交圖表時，因為處理期間多次複製 People Hub 回應，而可能使用過多尖峰記憶體的問題。\[64354447]

#### PlayFab Game Saves

> 修正使用同處理序 PlayFab Game Saves 時，如果存檔檔案在上傳期間遭到其他寫入者鎖定或被移除，`PFGameSaveFilesUploadWithUiAsync` 會以 `E_INVALIDARG` 等一般錯誤失敗，而且可能略過已鎖定的新檔案卻仍回報成功的問題。這些上傳現在會以新的 `E_PF_GAMESAVE_LOCAL_FILE_UNAVAILABLE` 錯誤失敗，此錯誤為暫時性錯誤：請在遊戲完成檔案寫入後再次呼叫上傳。\[64280746]

> 修正使用同處理序 PlayFab Game Saves 時，使用 `PFGameSaveFilesAddUserWithUiAsync` 搭配 `RollbackToLastKnownGood` 或 `RollbackToLastConflict` 進行復原，雖然會在本機還原較舊的存檔，卻未將其認可至雲端，導致玩家復原前的存檔在下次同步或在其他裝置上重新出現的問題。現在復原會在遊戲下次上傳時認可至雲端。\[64280747]

> 修正使用同處理序 PlayFab Game Saves 時，來自 `PFGameSaveFilesUiProgressGetProgress` 的上傳進度在大部分傳輸期間都停留在 64 KiB，且其總計會在中途從存檔大小切換為壓縮後大小，導致遊戲無法顯示流暢進度的問題。上傳和下載進度現在會在整個傳輸期間根據穩定的總計持續更新。\[64039954]

> 修正使用同處理序 PlayFab Game Saves 時，重試或重疊的上傳可能因為另一個上傳嘗試的清除作業刪除了其暫存檔案而失敗的問題。\[64040433]

> 修正使用同處理序 PlayFab Game Saves 時，如果上傳在壓縮存檔檔案期間失敗 (例如因為無法開啟存檔檔案)，可能發生的當機。\[64040433]

> 修正在 `PFGameSaveFilesUninitializeAsync` 之後 (例如在暫停時) 呼叫 `PFGameSaveFilesUploadWithUiResult` 等 PlayFab Game Saves 結果函式時，會傳回 `E_PF_GAMESAVE_NOT_INITIALIZED`，而不是已完成作業之結果的問題。\[64040433]

## 2025 年 10 月 GDK Update 4

### 問題修正

#### PlayFab Game Saves

> 修正套用雲端資料夾刪除時，可能刪除從未同步之本機檔案的問題，並提高上傳進度回報的精細度，讓遊戲可以在壓縮期間以動畫顯示確定進度列。\[63666969]

> 修正失敗的雲端儲存體傳輸被回報為成功的問題。這可能導致以遺失的資料完成存檔，並永久阻止該玩家的存檔在每部裝置上同步。\[63475452]

> 修正可能導致同步期間遺失存檔資料、遊戲存檔共用 GDK 內容時發生記憶體損毀，以及驗證失敗的資訊清單處理不正確的問題。\[63647898]

> 修正遊戲存檔同步進度回呼回報總大小為零，導致遊戲無法顯示確定進度列的問題。\[63529869]

## 2025 年 10 月 GDK Update 3

### 通知

#### 註冊檔案類型關聯

> 電腦遊戲現在可以在 MicrosoftGame.Config 中註冊檔案類型關聯。當使用者開啟具有已註冊副檔名的檔案時，遊戲會啟動或移至前景。此行為是透過 `XGameActivation*` API (例如 `XGameActivationRegisterForEvent()`) 啟用的。

#### 輸入

> 使用簡單處理序間通訊 (SIPC) 的動作感應控制器現在共用電腦感應器融合管線。加速度計和陀螺儀縮放、啟動時的陀螺儀偏差擷取，以及以靜止狀態為基礎的漂移修正，都已與電腦達到同等水準。因此，`IGameInputReading::GetMotionState` 會傳回相對於重力且漂移有限的方向。

#### PlayFab Game Saves

> 在 Steam Deck 上選擇 Keep Local 或 Keep Cloud 時，保留並復原至已捨棄遊戲存檔的功能已停用，以符合 XBOX/Gaming Runtime Services (GRTS) 的行為。

### 問題修正

#### 網路

> 修正程式庫在偵錯工具中暫停時失去 WebSocket 連線後，可能會當機的問題。

#### XBOX 服務

> 修正以 WinHTTP 為基礎的 HTTP 呼叫可能因 `libHttpClient` 中的釋放後使用狀況而變得不穩定的問題。

#### 輸入

> 修正在 XBOX 上的 `NuGet` 版 `GameInput` 中呼叫 `GameInputCreate` 時，可能發生記憶體不足錯誤的問題。

> 修正繼續執行已暫停的遊戲後，輸入可能遺失的問題。

#### 媒體

> 修正在未提交輸入影片樣本的情況下建立並終結解碼器時，導致 H.264 解碼器 Media Foundation Transform (MFT) 在終結期間停止回應的問題。

#### PlayFab Game Saves

> 修正 `PFGameSaves` 未正確處理遺失的登錄機碼，導致初始化錯誤的問題。

> 修正 Steam Deck 上的輕微遙測回報問題，這些問題會導致某些診斷欄位在存檔作業期間填入不正確的值。

## 2025 年 10 月 GDK Update 2

### 通知

#### Microsoft Azure PlayFab Party v2.2.7 更新

> * 已變更 `PartyNetwork::CreateEndpoint` `PartyStatusChangeResult` 行為，對於權杖到期前發生的暫時性錯誤會傳回 `PartyServiceError`，只有在權杖實際到期時才會傳回 `UserNotAuthorized`。
> * 新增對無 XUser 或同處理序 Gaming Runtime Services (GRTS) 環境的音訊裝置選取支援。
> * 修正多網路轉換案例期間可能發生的當機。

#### PlayFab Party v1.10.16 更新

> * `PartyNetwork::CreateEndpoint` `PartyStatusChangeResult` 行為已變更，對於權杖到期前發生的暫時性錯誤會傳回 `PartyServiceError`，只有在權杖實際到期時才會傳回 `UserNotAuthorized`。
> * 已新增對無 XUser 或同處理序 Gaming Runtime Services (GRTS) 環境的音訊裝置選取支援。
> * 已修正多網路轉換案例期間可能發生的當機。

#### XBOX 服務

> 新增在同處理序 `xgamingruntime` 中啟用偵錯工具追蹤輸出的支援，與現有的 Gaming Runtime Services (GRTS) 功能一致。
>
> 若要在 Visual Studio 輸出視窗中啟用 HTTP/WebSocket 追蹤訊息，請將 `HKEY_LOCAL_MACHINE\Software\Microsoft\GamingServices\Auth\TraceToDebugger` (`REG_DWORD`) 登錄機碼設定為 `1`。此設定適用於偵錯網路問題、Proxy 設定和驗證問題。此功能需選擇加入，停用時不會造成任何影響。

#### 網路

> `XCurl` 已更新，允許在呼叫 `curl_global_cleanup()` 之間多次呼叫 `xcurl_global_init_mem()` 或 `curl_global_init_mem()`。此新行為與 `LibCurl` 對 `curl_global_init_mem()` 的行為一致，讓 `XCurl` API 與 `LibCurl` 的預期保持同步。此外，`curl_global_init()`、`curl_global_init_mem()`、`xcurl_global_init_mem()` 和 `curl_global_cleanup()` 已成為執行緒安全。

#### packageutil compare Intelligent Delivery 標籤模擬修正

> `packageutil compare` 中的邏輯錯誤導致每次執行任何以標籤為基礎的模擬時，Intelligent Delivery 模擬都會排除必要的非 OnDemand 標籤。這會為使用 OnDemand 或以 Feature 為基礎之封裝的遊戲產生不準確的大小和更新預測。
>
> 此修正可確保：
>
> * 對於非 Feature 套件，**模擬中一律會包含非 OnDemand 標籤**。
> * **完整支援以 Feature 為基礎的套件**，包括分段標籤，以及完整功能和單一功能模擬。
>
> 此修正可還原準確的大小回報，讓合作夥伴能夠正確評估 ID 設定。
>
> 受影響的二進位檔：`PackageUtil.exe`

### 問題修正

#### GDK 工具

> 修正 GDK Tools 安裝程式中包含的 GDK 命令提示字元未正確包含工具所在之 GDK `bin` 目錄的問題。

> 修正導致 `XblTestAccountGui` 工具無法登入並出現下列錯誤訊息的問題。
>
> Live auth error: Login Error: The remote server returned an error: (400) Bad Request.

> 修正使用 `/features` 命令列參數以無訊息方式安裝 GDK 時，略過安裝舊版配置元件的問題。

#### Microsoft Azure PlayFab Game Saves

> 修正遊戲使用 PlayFab Game Saves 時，繼續執行時發生 `FAIL_FAST` 的問題。

> 修正使用同處理序 PlayFab Game Saves 時，在沒有實際裝置衝突的情況下，可能錯誤叫用裝置爭用回呼的問題。先前，PlayFab SDK 會將沒有暫止資訊清單視為另一部裝置已接手的證明。不過，這種情況也可能在正常案例中發生 (例如，沒有進行中的同步，或本機裝置已完成自己的上傳)。SDK 現在會在觸發爭用回呼之前，正確驗證已完成的資訊清單是否確實由其他裝置建立，以防止向遊戲發出誤判通知。

> 修正如果指定的存檔資料夾目錄尚不存在，或提供的路徑缺少結尾反斜線，PlayFab Game Saves 在 Gaming Runtime Services (GRTS) 上初始化失敗的問題。PlayFab SDK 現在會在需要時自動建立目錄，並在初始化之前確保路徑格式正確。

> 修正同處理序版 PlayFab Game Saves 在已完成的雲端資訊清單版本已超過過時的暫止資訊清單之後，仍可能錯誤地重複使用該暫止資訊清單的同步問題。現在只有在暫止資訊清單同時屬於目前裝置*且*版本大於已完成的雲端版本時，才會重複使用。此變更可防止多裝置同步案例期間可能發生的資料不一致。

> 修正使用不同儲存體提供者 (同處理序與 Gaming Runtime Services (GRTS)) 在裝置之間同步遊戲存檔時，檔案修改時間戳記不正確的問題。現在建立壓縮封存時，會正確保留檔案時間戳記並轉換為 UTC，確保所有平台上的時間戳記行為一致。

> 修正 Game Save 描述在 Steam Deck 上傳回格式錯誤/損毀資料的問題。現在從資訊清單擷取存檔描述時，會正確進行 Base64 解碼，確保您取得最初設定的正確可讀描述文字。

> 修正使用同處理序 PlayFab Game Saves 時，從進度對話方塊取消同步作業可能導致判斷提示失敗和不穩定行為的問題。取消機制已重新設計為使用執行緒安全的不可部分完成旗標方法。
>
> 此變更可讓使用者從進度 UI 安全地取消進行中的上傳或下載作業，而不會觸發競爭情形或判斷提示失敗。SDK 現在會在同步作業的關鍵階段正確檢查取消要求，並以使用者已取消的錯誤碼乾淨地終止。

> 修正使用同處理序 PlayFab Game Saves 時，下載大量小型檔案 (例如 1,000 個以上的小型文字檔) 會失敗的問題。進度追蹤錯誤地使用未壓縮的檔案大小來回報傳輸進度，導致處理許多已壓縮的小型檔案時發生不相符。進度回報現在會正確追蹤壓縮後的位元組大小，以準確反映實際的網路傳輸進度。

> 修正使用同處理序 PlayFab Game Saves 時，在與雲端中斷連線的情況下呼叫 `PFGameSaveFilesSetSaveDescriptionAsync` API 所發生的當機。此 API 現在會傳回適當的錯誤碼，而不會當機。

> 修正 `PFUninitializeAsync()` 在使用同處理序 `PFGameSaveFiles` 時，如果關機期間有同步失敗回呼正在等待回應，就會停止回應的問題。SDK 現在會在解除初始化時自動取消暫止的 UI 回呼，即使遊戲未回應 `syncFailedCallback`，也能確保乾淨地關機。

> 修正使用 PlayFab Game Saves 變更作用中裝置時，遊戲可能當機的問題。

> 修正使用同處理序 PlayFab Game Saves 時，衝突回呼顯示不正確時間戳記的問題。

> 修正在 Steam Deck 上離線呼叫 `PFGameSaveFilesSetSaveDescriptionAsync` 時，傳回 `E_FAIL` 且後續呼叫停止回應的問題。

> 修正在 Steam Deck 上取消失敗的上傳後，所有後續上傳都永久失敗並出現 `E_PF_GAME_SAVE_MANIFEST_UPDATES_NOT_ALLOWED` 的問題。

> 修正如果先前的上傳在服務錯誤期間遭到取消，`PFGameSaveFilesUploadWithUiAsync` 可能無限期停止回應的問題。現在重試時會正確顯示同步失敗 UI 回呼，讓使用者可以取消或重試作業。

#### 網路

> 修正在第一次嘗試大廳或配對的 24 小時後，如果尚未清除程式庫，可能無法建立後續大廳、加入後續大廳、訂閱大廳邀請或建立後續配對票證的問題。

#### XBOX 服務

> 修正在下列兩種特定情況下，Steam Deck 上未觸發遊戲邀請回呼的問題。
>
> * 邀請未提供 Multiplayer Activity Connection String 時
> * 遊戲在已新增 `XUser` 之後才新增邀請處理常式時

> 修正同處理序遊戲執行階段未使用 WinHTTP Proxy 設定，導致透過 `netsh winhttp set proxy` 設定 Proxy (例如 Fiddler) 時發生 `E_XAL_NETWORK` 錯誤的問題。

## 2025 年 10 月 GDK Update 1

### 通知

#### 跨平台功能

> 已新增 `XUserSignOutAsync` 和 `XUserSignOutResult`，以支援在 Steam Deck 上登出玩家。`XUserIsSignOutPresent` 可用來判斷目前裝置是否支援透過 API 登出。

#### XBOX 服務

> 已新增三個新的 API—`XGameInviteRegisterForPendingEvent`、`XGameInviteUnregisterForPendingEvent` 和 `XGameInviteAcceptPendingInvite`—以恢復 `XGameInvite` 回呼的一致性，這些回呼先前在同處理序和跨處理序案例中的行為不一致。新的暫止邀請處理常式只會在同處理序流程中呼叫。遊戲處理邀請接受之後，會呼叫 `XGameInviteAcceptPendingInvite`。這會觸發邀請已接受回呼。
>
> 在 Windows 和 XBOX 主機上 (可使用 Gaming Runtime Services (GRTS) 的平台)，由殼層 UI 負責邀請接受流程。遊戲只會在邀請被接受時收到通知。在同處理序案例 (例如 Steam Deck) 中，由遊戲處理邀請接受。收到邀請時會觸發 `XGameInvite` 回呼，讓遊戲可以管理接受流程。

#### Microsoft Azure PlayFab Game Saves

> 上傳進度追蹤現在會回報壓縮後的位元組計數。此變更可讓進度回呼和遙測與實際串流的資料保持一致，並防止大型存檔壓縮效果不佳時過早顯示「已完成」百分比。

> 先前處於休眠狀態的 `PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood` 和 `RollbackToLastConflict` 旗標已啟用。它們現在會在 `PFGameSaveFilesAddUserWithUiAsync` 期間接受復原要求。遊戲會取得預期的選擇，而不是一律同步至最新的存檔。

> 初始化現在會在 `E_INVALIDARG` 失敗 (例如缺少 Steam Deck 存檔路徑) 後正確清除。此變更可確保後續呼叫不再回報「已初始化」。

> 已新增記錄功能，以改善在處理序外執行時的診斷。

### 問題修正

#### Microsoft Azure PlayFab Party

> 修正沒有已登入的 `XUser` 時無法建立 PlayFab Party 語音聊天的問題，包括在 Windows 上沒有 XBOX 網路使用者遊玩的 Steam 遊戲，以及在 Steam Deck 上。

#### XBOX 服務

> 修正遊戲在 Steam Deck 上從 `XGameInvite` 回呼收到的 URI 與在 Windows 上收到的 URI 不符的問題。Steam Deck URI 只包含連接字串，但缺少傳送者資訊和受邀使用者的 XUID。

## 2025 年 10 月 GDK

### 通知

#### GDK 配置淘汰

> 2025 年 10 月和 2026 年 4 月的 GDK 版本同時包含簡化配置和舊版配置。從 2026 年 10 月的 GDK 開始，安裝程式預設只會安裝簡化配置。舊版配置仍可選取為選擇性安裝，但已淘汰，且不再是建議的開發路徑。
>
> 從 2027 年 4 月的 GDK 版本開始，將不再支援舊版配置，並會從安裝程式中移除。

#### GDK 工具

> MakePkg 已新增 `/updatesubval` 旗標，用於檢查是否有較新版本的 SubmissionValidator.dll。如果使用此旗標且有較新版本的 SubmissionValidator.dll 可用，MakePkg 會下載該 .dll 檔案並放在 MakePkg 的路徑中。

> Touch Adaptation Kit Command Line Tool (TAK CLI) (tak.exe) 已從 GDK 安裝程式中移除。如需如何下載此工具的指示，請前往 [GitHub 上的 TAK CLI](https://aka.ms/get-takcli)。

## 已知問題

### XUserResolveIssueWithUiAsync 流程

> **問題：**\
> `XUserResolveIssueWithUiAsync` API 的用途是解決使用者帳戶問題 (例如權杖或同意問題)，而不是變更已登入的身分識別。不過，最初以帳戶 A 登入的使用者有可能完成此流程並以帳戶 B 登入，導致 XUID 不同。
>
> **影響：**\
> 當帳戶在此流程期間變更時，API 會偵測到不相符並自動使作業失敗。
>
> **適用於：**
>
> * 2025 年 10 月 GDK
> * 2025 年 10 月 GDK Update 1
> * 2025 年 10 月 GDK Update 2
>
> **指引：**\
> 如果作業因帳戶變更而失敗，請移除使用者並重新新增使用者，以確保正確登入。

#### 已解決：下載壓縮的存檔資料

> **問題：**\
> 下載壓縮後大小大於未壓縮大小的存檔資料時，PlayFab Game Saves 可能會遇到問題。這最常發生在遊戲除了 PlayFab Game Saves 之外還使用自己的檔案壓縮時。
>
> **適用於：**
>
> * 2025 年 10 月 GDK
> * 2025 年 10 月 GDK Update 1
>
> **已解決：**\
> 此問題已在 2025 年 10 月 GDK Update 2 中解決。
>
> **指引：**\
> 如果可能，請考慮停用額外的檔案壓縮。

### 已解決：必須在新增 XUser 之前呼叫 XGameInviteRegisterForPendingEvent

> **問題：**\
> 在 Steam Deck 上，必須在新增 `XUsers` 之前呼叫 `XGameInviteRegisterForPendingEvent`，否則它們不會正確註冊邀請通知。此順序需求並非刻意設計。
>
> **適用於：**\
> 2025 年 10 月 GDK Update 1
>
> **已解決：**\
> 此問題已在 2025 年 10 月 GDK Update 2 中解決。

### 已解決：XGameInviteRegisterForPendingEvent 需要設定 connectionString

> **問題：**\
> 在 Steam Deck 上，對於缺少 XBOX Multiplayer Activity (MPA) `connectionString` 的邀請，`XGameInviteRegisterForPendingEvent` 不會叫用遊戲回呼。雖然傳送邀請時這是選擇性欄位，但 `XGameRuntime` 會捨棄沒有此欄位的邀請承載。
>
> **適用於：**\
> 2025 年 10 月 GDK Update 1
>
> **已解決：**\
> 此問題已在 2025 年 10 月 GDK Update 2 中解決。
>
> **因應措施：**\
> 傳送邀請時請提供非空白的連接字串。如果接收端不需要，可以忽略它。

## 文件

> 2025 年 10 月版 GDKX 的離線文件會由 GDKX 安裝程式安裝在您的開發電腦上。執行安裝程式之後，GDKX 的說明檔 (gdk.chm) 位於 C:\Program Files (x86)\Microsoft GDK\Documentation。

> * 線上 GDKX 文件位於 [https://aka.ms/gdkonline](https://aka.ms/gdkonline)。


## Related topics

- [Microsoft Game Development Kit (GDK) 版本資訊](https://docs.xbox.com/zh-TW/announcements/gdk/release-notes.md)
- [Microsoft Game Development Kit (GDK) 的新功能](https://docs.xbox.com/zh-TW/announcements/gdk/whats-new.md)
- [使用 2025 年 10 月 GDK 實作 Game Saves](https://docs.xbox.com/zh-TW/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [GameInput 常見問題集](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-faq.md)
- [搭配 Microsoft Game Development Kit (GDK) 使用 Clang](https://docs.xbox.com/zh-TW/tools/tools-pc/visualstudio/gr-vs-clang.md)