> ## 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) 的中断性变更、通知、bug 修复和已知问题。

## 简介

欢迎使用 2025 年 10 月 Microsoft Game Development Kit 版本。你可以使用 GDK 开发能够通过认证并获准在 Windows 11 PC 和 Windows 10 PC 上发布的游戏。

### 关于本文档

本文档分为以下几个部分。

* [新增功能](#whats-new-in-the-october-2025-microsoft-game-development-kit)
* **发行说明：**
  * [2025 年 10 月 GDK 更新 5](#october-2025-gdk-update-5)
  * [2025 年 10 月 GDK 更新 4](#october-2025-gdk-update-4)
  * [2025 年 10 月 GDK 更新 3](#october-2025-gdk-update-3)
  * [2025 年 10 月 GDK 更新 2](#october-2025-gdk-update-2)
  * [2025 年 10 月 GDK 更新 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-CN/announcements/gdk/whats-new.md)的联机版本。

## 2025 年 10 月 GDK 更新 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` 之后（例如在挂起时）调用 PlayFab Game Saves 结果函数（如 `PFGameSaveFilesUploadWithUiResult`）会返回 `E_PF_GAMESAVE_NOT_INITIALIZED`，而不是已完成操作的结果的问题。\[64040433]

## 2025 年 10 月 GDK 更新 4

### 问题修复

#### PlayFab Game Saves

> 修复了应用云文件夹删除操作时可能会删除从未同步过的本地文件的问题，并提高了上传进度报告的粒度，以便游戏在压缩期间能够以动画形式显示确定性进度栏。\[63666969]

> 修复了失败的云存储传输被报告为成功的问题，该问题可能会导致以缺失数据的状态完成存档，并永久阻止该玩家的存档在所有设备上同步。\[63475452]

> 修复了可能在同步期间导致存档数据丢失、在游戏存档共享 GDK 上下文时导致内存损坏，以及错误处理验证失败的清单的问题。\[63647898]

> 修复了游戏存档同步进度回调报告总大小为零，导致游戏无法显示确定性进度栏的问题。\[63529869]

## 2025 年 10 月 GDK 更新 3

### 通知

#### 文件类型关联注册

> PC 游戏现在可以在 MicrosoftGame.Config 中注册文件类型关联。当用户打开具有已注册扩展名的文件时，游戏将会启动或被置于前台。此行为通过 `XGameActivation*` API（例如 `XGameActivationRegisterForEvent()`）启用。

#### 输入

> 使用简单进程间通信 (SIPC) 的支持动作感应的控制器现在共享 PC 传感器融合管道。加速度计和陀螺仪缩放、启动时陀螺仪偏差捕获以及基于静止状态的漂移校正现在与 PC 一致。因此，`IGameInputReading::GetMotionState` 会返回漂移有界的、相对于重力的方向。

#### PlayFab Game Saves

> 在 Steam Deck 上选择“保留本地”或“保留云端”时保留并回滚到被丢弃的游戏存档的功能已被禁用，以与 XBOX/Gaming Runtime Services (GRTS) 的行为保持一致。

### 问题修复

#### 网络

> 修复了库在调试器中暂停期间丢失 WebSocket 连接后可能崩溃的问题。

#### XBOX 服务

> 修复了由于 `libHttpClient` 中的释放后使用情况，基于 WinHTTP 的 HTTP 调用可能出现不稳定的问题。

#### 输入

> 修复了在 XBOX 上调用 `NuGet` 版本 `GameInput` 中的 `GameInputCreate` 时可能出现内存不足错误的问题。

> 修复了恢复挂起的游戏后可能丢失输入的问题。

#### 媒体

> 修复了在创建并销毁 H.264 解码器 Media Foundation Transform (MFT) 而未提交输入视频样本时，该解码器在销毁期间停止响应的问题。

#### PlayFab Game Saves

> 修复了 `PFGameSaves` 错误处理缺失的注册表项，从而导致初始化错误的问题。

> 修复了 Steam Deck 上的一些轻微遥测报告问题，即在存档操作期间某些诊断字段填充不正确。

## 2025 年 10 月 GDK 更新 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`。此设置可用于调试网络问题、代理配置和身份验证问题。该功能需要选择启用，禁用时不会产生任何影响。

#### 网络

> `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 上未触发的问题。
>
> * 邀请未提供多人活动连接字符串时
> * 游戏在 `XUser` 已添加之后才添加邀请处理程序时

> 修复了进程内 Gaming Runtime 未使用 WinHTTP 代理设置的问题，该问题会在通过 `netsh winhttp set proxy` 配置代理（例如 Fiddler）时导致 `E_XAL_NETWORK` 错误。

## 2025 年 10 月 GDK 更新 1

### 通知

#### 跨平台功能

> 添加了 `XUserSignOutAsync` 和 `XUserSignOutResult`，以支持玩家在 Steam Deck 上注销。`XUserIsSignOutPresent` 可用于确定当前设备是否支持通过 API 注销。

#### XBOX 服务

> 添加了三个新 API—`XGameInviteRegisterForPendingEvent`、`XGameInviteUnregisterForPendingEvent` 和 `XGameInviteAcceptPendingInvite`—以恢复 `XGameInvite` 回调的一致性，这些回调以前在进程内和进程外场景中的行为不一致。新的待处理邀请处理程序仅在进程内流程中调用。游戏处理邀请接受后，将调用 `XGameInviteAcceptPendingInvite`。这会触发邀请已接受回调。
>
> 在 Windows 和 XBOX 主机上（Gaming Runtime Services (GRTS) 可用的平台），由 shell UI 负责邀请接受流程。仅当邀请被接受时才会通知游戏。对于进程内场景（例如 Steam Deck），由游戏处理邀请接受。收到邀请时会触发 `XGameInvite` 回调，以便游戏能够管理接受流程。

#### Microsoft Azure PlayFab Game Saves

> 上传进度跟踪现在报告压缩后的字节数。此更改使进度回调和遥测与实际流式传输的数据保持一致，并防止在大型存档压缩效果不佳时过早显示“已完成”百分比。

> 已启用以前处于休眠状态的 `PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood` 和 `RollbackToLastConflict` 标志。它们现在会在 `PFGameSaveFilesAddUserWithUiAsync` 期间遵循回滚请求。游戏会获得预期的选择，而不是始终同步到最新存档。

> 初始化现在会在出现 `E_INVALIDARG` 失败（例如缺少 Steam Deck 存档路径）后正确清理。此更改可确保后续调用不再报告“已初始化”。

> 添加了日志记录，以改进在进程外运行时的诊断。

### 问题修复

#### Microsoft Azure PlayFab Party

> 修复了在没有登录 `XUser` 时无法建立 PlayFab Party 语音聊天的问题，包括在没有 XBOX 网络用户的情况下在 Windows 上玩的 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 命令行工具 (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 更新 1
> * 2025 年 10 月 GDK 更新 2
>
> **指导：**\
> 如果操作因帐户更改而失败，请删除该用户并重新添加该用户，以确保正确登录。

#### 已解决：下载压缩的存档数据

> **问题：**\
> PlayFab Game Saves 在下载大于其未压缩大小的压缩存档数据时可能会遇到问题。这种情况最常见于游戏除了使用 PlayFab Game Saves 之外还使用自己的文件压缩时。
>
> **适用于：**
>
> * 2025 年 10 月 GDK
> * 2025 年 10 月 GDK 更新 1
>
> **已解决：**\
> 此问题已在 2025 年 10 月 GDK 更新 2 中解决。
>
> **指导：**\
> 如果可能，请考虑禁用额外的文件压缩。

### 已解决：必须在添加 XUsers 之前调用 XGameInviteRegisterForPendingEvent

> **问题：**\
> 在 Steam Deck 上，必须在添加 `XUsers` 之前调用 `XGameInviteRegisterForPendingEvent`，否则这些用户将无法正确注册邀请通知。此顺序要求并非有意为之。
>
> **适用于：**\
> 2025 年 10 月 GDK 更新 1
>
> **已解决：**\
> 此问题已在 2025 年 10 月 GDK 更新 2 中解决。

### 已解决：XGameInviteRegisterForPendingEvent 要求设置 connectionString

> **问题：**\
> 在 Steam Deck 上，对于缺少 XBOX 多人活动 (MPA) `connectionString` 的邀请，`XGameInviteRegisterForPendingEvent` 不会调用游戏回调。尽管发送邀请时这是一个可选字段，但 `XGameRuntime` 会丢弃没有该字段的邀请负载。
>
> **适用于：**\
> 2025 年 10 月 GDK 更新 1
>
> **已解决：**\
> 此问题已在 2025 年 10 月 GDK 更新 2 中解决。
>
> **解决方法：**\
> 发送邀请时提供非空的连接字符串。如果接收端不需要，则将其忽略。

## 文档

> GDKX 安装程序会在你的开发 PC 上安装 2025 年 10 月版 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-CN/announcements/gdk/release-notes.md)
- [Microsoft Game Development Kit (GDK) 新增功能](https://docs.xbox.com/zh-CN/announcements/gdk/whats-new.md)
- [GameInput 常见问题](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-faq.md)
- [使用 2025 年 10 月 GDK 实现 Game Saves](https://docs.xbox.com/zh-CN/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [MicrosoftGame.config 附加参考](https://docs.xbox.com/zh-CN/reference/system/microsoftgameconfig/microsoftgameconfig-schema.md)