Microsoft Game Development Kit (GDK) 发行说明

​

2026 年 4 月 Microsoft Game Development Kit (GDK) 发行说明

​

简介

​

GDKX

• 2026 年 4 月 GDKX 可以与 2019 年 11 月及更高版本的 GDKX 并行安装。
• 你可以从 https://aka.ms/gdkdl 下载 GDKX 版本。
• 所有 GDKX 版本的发行说明位于 https://aka.ms/gdkreleasenotes。

​

GDK

• 你可以在 https://aka.ms/gdk-winget 下载 GDK 版本并查看其发行说明。

​

关于本文档

• 新增功能
• 发行说明:
  • 2026 年 4 月 GDK Update 5
  • 2026 年 4 月 GDK Update 4
  • 2026 年 4 月 GDK Update 3
  • 2026 年 4 月 GDK Update 2
  • 2026 年 4 月 GDK Update 1
  • 2026 年 4 月 GDK
• 已知问题
• 文档

注意:发行说明的描述后面带有一个编号,例如 [12345678]。对于 GDKX 用户,此编号表示 Microsoft 用于跟踪与该项相关的工作和历史记录的内部 ID。如果你对某条发行说明有疑问,此编号可能对你的开发人员客户经理有所帮助。

​

2026 年 4 月 Microsoft Game Development Kit 新增功能

• GDKX 和 GDK 以两种类型发布:主要版本(侧重于功能,每年两次)和更新(侧重于修复,根据合作伙伴需要随时发布)。
• 若要查看完整的”新增功能”部分,请参阅新增功能的联机版本。
• 若要查看以前版本的发行说明,对于 GDKX,请参阅 GDK 论坛上的发行说明帖子。对于 GDKX 和 GDK,你可以在联机文档的 GDK 发行说明中查看发行说明。

​

2026 年 4 月 GDK Update 5

​

问题修复

​

PlayFab Party

已将 PlayFab Party 更新到 v1.10.26,其中包括以下修复:

• 修复了销毁 PartyEndpoint 时可能发生的崩溃。
• 修复了对 /MultiplayerServer/GetCognitiveServicesToken 返回的空响应、格式错误的响应或不完整响应的处理。Party 现在会将请求报告为失败,而不是可能崩溃。
• 修复了远程设备离开对等网络后直接连接设置才完成时可能发生的崩溃。

[63883777]

​

系统

修复了向 XSpeechSynthesizerCreateStreamFromText 传递大型字符串时,xgameruntime.dll!OnRuntimeDisconnected 中可能发生的游戏崩溃。[63860960]

改进了执行游戏存档读取或写入操作时对内存压力的处理。[63996543]

改进了游戏存档读取或写入操作失败时返回的错误代码。[63996543]

​

2026 年 4 月 GDK Update 4

​

问题修复

​

Social Manager

修复了 GDK C Thunks DLL 未导出 Privacy 静音列表、阻止列表和 Social 好友请求计数更改处理程序函数的问题。该问题导致调用这些函数的游戏在无提示的情况下链接到 XSAPI 静态库而不是 thunks DLL,最终导致运行时不匹配。[63776691]

修复了填充 Social Manager 社交关系图时发生的堆栈溢出崩溃。该崩溃是由于 PeoplehubService::DeserializeUser 使用了 17 KB 的堆栈帧,其中保存了每个 XblSocialManagerUser 的三个冗余副本。[63776693]

​

MSIXVC1(打包)

不带 /msixvc2 选项的 makepkg2 pack 再次可以正常工作,不会再报告有关 /usepublisherkey 选项的错误。此问题是在 Update 3 中引入的。[63529609]

​

Wdapp

修复了对同时包含 ARM64 和 x64 二进制文件的游戏使用 wdapp register 时,在 ARM64 计算机上未选择相应二进制文件的问题。[63756866]

​

PIX

修复了 PIX 时间线中不显示命名围栏箭头的问题。[63446892]

​

2026 年 4 月 GDK Update 3

​

通知

​

Publisher Content

PC 和主机游戏现在可以附带 Publisher Content。这是一种新的包类型,允许游戏发行商在自己的 CDN 上托管和更新内容,同时由平台继续管理安装、后台下载、完整性和用户体验。 开发人员在其 MicrosoftGame.config 中声明它(通过基础游戏上新增的 PublisherContent 元素和内容包上的 PublisherContentBaseProduct 字段),并使用相应的新 makepkg 参数生成包。 游戏可以使用新的 XPackageGetPackageKind() API 识别现有 GDK API 返回的包的类型。除了 Game 和 Content 之外,该 API 现在还会报告 XPackageKind::PublisherContent。 [63082917]

​

PlayFab Party

用于生成该库的 Windows 平台工具集已从 v142 升级到 v143。[63294760]

​

PIX

新增了一个用于转换编程计时捕获的 CLI 工具:convertpevt.exe。[62666766]

​

问题修复

​

Clang/LLVM

XBOX Game OS 综合库 xgameplatform.lib 已更新,新增以下 Win32 API,以支持 clang/LLVM 的 PGO 检测实现:FlushViewOfFile、VirtualUnlock。 使用 clang/LLVM PGO 的开发人员还需要为 clang/LLVM 实现所使用的一些旧版 POSIX API 提供链接别名,才能成功链接:

#pragma comment(linker, "/alternatename:fileno=_fileno")
#pragma comment(linker, "/alternatename:getpid=_getpid")
#pragma comment(linker, "/alternatename:strdup=_strdup")

[62740693]

​

PIX

加载大型外部着色器 PDB 缓存时更加可靠和一致。[63014983]

​

PIX DirectStorage

修复了在计时捕获中从 Element Details 视图或 Range Details 视图导航时缩放行为不正确的问题。[62664029]

修复了在深色模式下,计时捕获时间线中指示 DirectStorage 批次开始的菱形标记难以辨认的问题。[62664035]

​

XBOX Manager

修复了在 Remote Control 选项卡中查看主机或组的视频时可能发生的 XBOX Manager 崩溃。[62844048]

​

PlayFab Game Saves

修复了 Steam Deck 上的一些轻微遥测报告问题,这些问题导致在保存操作期间某些诊断字段填充不正确。[62642608]

在 Steam Deck 上禁用了冲突失败方上传功能,以与 XBOX/GRTS 行为保持一致。[62642612]

修复了 PlayFab Game Saves 错误处理缺失的注册表项,从而导致初始化错误的问题。[62642607]

​

Social Manager

修复了当初始 People Hub 好友列表请求始终未完成时,Social Manager 好友列表可能在整个会话中间歇性保持为空(XblSocialManagerDoWork 未引发 LocalUserAdded 事件)的问题。初始请求现在会自动恢复,因此无需重新启动游戏即可填充社交关系图。[63202269]

修复了当好友正在玩的游戏的显示名称包含连字符时,Social Manager 返回错误的游戏名称和丰富状态文本的问题。该问题是由于状态字符串在第一个连字符处拆分,而不是在预期的”空格-连字符-空格”分隔符处拆分。[63202289]

​

PlayFab Party

修复了当游戏尚未配置音频输出时,音频处理语音流不生成任何缓冲区的问题。[63294702]

修复了在音频处理处于活动状态时于网络之间切换可能导致语音丢失的问题。[63294760]

修复了音频处理捕获流处于活动状态时缺少最终语音转文本转录的问题。[63294760]

修复了在 Party 完成关闭之前删除进程任务队列时,关闭过程中可能发生的崩溃。[63294760]

修复了内部 HTTP 跟踪对象可能在其支持的异步任务完成之前被删除而导致的释放后使用问题。[63294760]

修复了在某些 WMI 注册表配置错误的 PC 环境中,PlayFab Party 无法绑定到其 UDP 多人游戏端口的 bug。[63251323]

​

Publisher Content

修复了 XTaskQueue 中的一个内部 bug,以防止在拆除期间无限等待。[63190218]

​

MSIXVC2

现在,即使 Intelligent Delivery layout.xml 中有多个功能使用同一个图像文件,也能成功创建 MSIXVC2。[63117723]

MSIXVC2 pack 命令会正常忽略 /maxencryptionfragments 和 /nogameos 选项(这些选项对 MSIXVC2 不起作用),以便更轻松地将其接入现有生成管道。[63118134]

MSIXVC2 pack 命令现在会正确包含源目录中属于符号链接的文件。以前,它会错误地将这些文件视为长度为 0 的文件。[63118309]

​

2026 年 4 月 GDK Update 2

​

通知

​

开发人员工具

适用于 Visual Studio 2019 的 Direct3D 12 Desktop Game (Classic) 模板不再包含 ARM64 配置。使用 Visual Studio 2019 面向 ARM64 的支持已弃用。需要 Visual Studio 2022 或更高版本。[62468394]

​

提供 Markdown 文件

GDK 安装程序中新增了一个包含 GDK 文档 Markdown 文件的 .zip 文件。以前,此 .zip 文件只能在 https://aka.ms/gdkdl 单独下载。[62398050]

​

问题修复

​

输入

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

​

PIX

修复了打开在 Lockhart 40GB 上获取的捕获时,PIX 错误地将主机模式报告为 Lockhart 的问题。[62490828]

​

媒体

修复了在未提交输入视频样本的情况下创建并销毁解码器时,H.264 解码器 Media Foundation Transform (MFT) 在销毁期间停止响应的问题。[62525251]

​

系统

修复了未签名(本地)MSIXVC2 包使用 wdapp 安装失败的问题。[62386086]

​

2026 年 4 月 GDK Update 1

​

通知

​

XBOX Game Package Manager

创建和上传 MSIXVC2 包时,请使用 GitHub 上最新发布的 XBOX Game Package Manager (XGPM) UI 版本。此版本包含多项修复。若要下载,请转到 releases - Microsoft/PackageUploader。

​

问题修复

​

系统

修复了 XGameActivationAcceptPendingInvite API 中的内存泄漏。[61953160]

修复了 XLaunchUri 在 URI 长度超过 21 个字符时失败的问题。[62181431]

修复了 XGameInvite.h 和 XGameProtocol.h GDK 头文件中可能导致 C4768 编译器错误的问题。[62181564]

​

MSIXVC2

修复了 MSIXVC2 预览版中的各种组件可靠性和性能问题。[62225080]

​

开发人员工具

修复了 MicrosoftGame.config Editor 在报告成功的同时无提示地无法保存或创建新文件的问题。[62226865]

​

2026 年 4 月 GDK

​

通知

​

GDK 布局弃用

2025 年 10 月和 2026 年 4 月的 GDK 版本同时包含简化布局和旧版布局。从 2026 年 10 月 GDK 开始,安装程序默认仅安装简化布局。旧版布局仍可作为可选安装项进行选择,但它已被弃用,不再是推荐的开发路径。 从 2027 年 4 月 GDK 版本开始,旧版布局将不再受支持,并将从安装程序中移除。

​

API 弃用

XGameActivation API 已取代 XGameProtocol 和 XGameInvite API,为所有游戏激活方案提供单一的 API 接口。因此,XGameProtocol 和 XGameInvite 现已弃用。现有实现将继续正常运行,但我们建议迁移到 XGameActivation,以用于新的开发并确保未来的兼容性。 以下 API 已弃用。

• XGameProtocolRegisterForActivation
• XGameProtocolUnregisterForActivation
• XGameInviteRegisterForEvent
• XGameInviteUnregisterForEvent
• XGameInviteRegisterForPendingEvent
• XGameInviteUnregisterForPendingEvent
• XGameInviteAcceptPendingInvite

有关详细信息,请参阅 XGameActivation。 [61232139]

​

开发人员工具

Visual Studio 2019 的主流支持已到期。扩展支持将持续到 2029 年 4 月。有关 Visual Studio 2019 产品生命周期和服务的详细信息,请参阅 Visual Studio 2019 Product Lifecycle and Servicing。 Visual Studio 2019 和 v142 工具集编译器自 2024 年 4 月起已结束主流支持,仅接收安全服务更新。在 GDK 的未来版本中,将移除对 Visual Studio 2019 集成以及通过 Visual Studio 2022/Visual Studio 2026 使用 v142 平台工具集的支持。此过程将包括移除 Microsoft.Xbox.Services.142.GDK.C.lib 库。对于 Visual Studio 2022 和 Visual Studio 2026,我们建议改用在 2026 年 4 月 GDK 中新增的 Microsoft.Xbox.Services.143.GDK.C.lib。 [61594513]

Visual Studio 2019 不再支持适用于 XBOX 的 Address Sanitizer (ASAN)。[60868415]

现在可以从 XBOX Manager 的 Media Capture 选项卡将屏幕截图复制到剪贴板。[41667882]

wdcapture、wdcapturesession 和 xblpcsandbox 等 PC 命令行工具现在支持通过反馈中心应用直接提交 bug 反馈。[60250549]

Package Uploader 现在支持联合凭据。[60771527]

​

Microsoft Azure PlayFab

PlayFab Multiplayer 已更新到 v1.9.0。有关详细信息,请参阅 PlayFab Multiplayer C++ SDK Release Notes - PlayFab | Microsoft Learn。[61288995]

​

Microsoft Azure PlayFab Party

PlayFab Party 已更新到 v1.10.18。有关详细信息,请参阅 PlayFab Party Release Notes - PlayFab | Microsoft Learn。[61288995]

​

问题修复

修复了在运行 xbapp.exe 或 xbconnect.exe 等 GDK XBOX 命令行工具后,非英语命令提示符中的语言设置变为英语的问题。[59688191]

修复了 XBOX Game Package Manager 未在 UI 中填充上次选择的分支的问题。[60771527]

​

已知问题

​

makepkg2:/priorpackage 不会为 MSIXVC2 包生成比较报告

问题:
在 makepkg2 中,打包 MSIXVC2 包时使用 /priorpackage 标志不会生成比较报告。此版本中的 MSIXVC2 包不支持生成比较报告。 适用于:

• 2026 年 4 月 GDK

解决方法:
目前没有。 状态:
此问题将在未来的 GDK 更新中修复。 [61771743]

​

makepkg2:layout.xml 要求所有功能都具有 DisplayName

问题:
在 makepkg2 中,layout.xml 分析器要求所有功能都具有 DisplayName 属性,包括显示名称没有意义的隐藏功能。 适用于:

• 2026 年 4 月 GDK

解决方法:
为 layout.xml 中的所有隐藏功能添加一个占位 DisplayName 属性。 状态:
此问题将在未来的 GDK 更新中修复。 [61767246]

​

makepkg2:当 MicrosoftGame.config 中缺少 ContentId 时 /contentid 标志失败

问题:
在 makepkg2 中,如果 MicrosoftGame.config 中未指定 ContentId,使用 /contentid 标志会导致以下错误。 /contentid specified on the command line does not match the ContentId derived from the MicrosoftGame.config file. 此行为与 makepkg 不同,后者在这种情况下会直接接受 /contentid 值。 适用于:

• 2026 年 4 月 GDK

解决方法:
使用 /contentidoverride 代替 /contentid。 状态:
此问题将在未来的 GDK 更新中修复。 [61767256]

​

无法通过 Microsoft Partner Center 的 Web UI 上传 MSIXVC2 包

问题:
如果 .msixvc 包是使用新的 makepkg2 工具生成的,则将其上传到 Partner Center 会失败。 适用于:

• Partner Center Web UI

解决方法:
使用以下工具之一将 MSIXVC2 包上传到 Partner Center。

• makepkg2 upload 命令:makepkg2 upload /d <content_directory> /branch "<BranchName>" /msixvc2
• XBOX Game Package Manager:从 https://github.com/microsoft/PackageUploader 下载最新版本。

状态:
Partner Center 将在未来几个月内更新,以支持通过 Web 上传 MSIXVC2 包。

​

XboxPcTray.exe 可能会阻止 MSIXVC2 包的卸载或更新

问题:
XboxPcTray.exe 有时会保留游戏 Content 文件夹的句柄,这可能会导致卸载或更新操作无法完成。 适用于:

• 2026 年 4 月 GDK

解决方法:
在尝试卸载或更新之前,关闭 XBOX PC Tray 应用。若要关闭它,请右键单击系统托盘中的 XboxPcTray 图标,然后选择 Quit。你也可以在任务管理器中结束 XboxPcTray.exe 进程。 状态:
此问题将在未来的 GDK 更新中修复。 [61618609]

​

无法通过 Package Uploader 上传 MSIXVC2 包

问题:
如果 .msixvc 包是使用带 /msixvc2 标志的 makepkg2 工具生成的,则通过 Package Uploader 命令行工具将其上传到 Partner Center 会失败,并返回 400 (Bad Request) 错误。尽管 MSIXVC 和 MSIXVC2 包使用相同的 .msixvc 文件扩展名,但 MSIXVC2 包使用不同的内部格式,而 Package Uploader 目前不支持该格式。 适用于:

• Package Uploader CLI (PackageUploader.exe)

解决方法:
使用以下工具之一上传 MSIXVC2 包。

• makepkg2 upload 命令:makepkg2 upload /d <content_directory> /branch "<BranchName>" /msixvc2>
• XBOX Game Package Manager: 从 https://github.com/microsoft/PackageUploader 下载最新版本。

状态:
此问题将在 Package Uploader 的未来版本中解决。

​

Partner Center 的 UI 中 MSIXVC2 包的大小显示为 1 字节

问题:
Partner Center 显示的已上传 MSIXVC2 包大小不正确。无论包的实际大小如何,都显示为 1 字节。 适用于:

• Partner Center

解决方法:
目前没有。 状态:
此问题将在未来的 GDK 工具更新中修复。

​

适用于 Visual Studio 2026 的 Build With/Out Install (BWOI) MSBuild 集成

问题:
适用于 Visual Studio 2026 的 Build With/Out Install (BWOI) MSBuild 集成与以前的版本略有不同。在当前的 Visual Studio 2026 版本中,BWOI 实现必须”锁定”到特定的 VCTargetsPath。其结果是,即使 PlatformToolset 值设置为 v142 或 v143,所有项目也都会使用 v145 或 clang-cl 生成。在标准 Visual Studio 方案中,这些较旧的工具集通常可以正确生成。 适用于:

• 2026 年 4 月 GDK

解决方法:
有关解决方法的详细信息,请参阅 BWOIExample。 状态:
GDK 团队和 Visual Studio 团队正在努力在未来的 Visual Studio 版本中解决此问题。 [61855642]

​

文档

2026 年 4 月版 GDKX 的脱机文档由 GDKX 安装程序安装在你的开发 PC 上。运行安装程序后,GDKX 的帮助文件 (gdk.chm) 位于 C:\Program Files (x86)\Microsoft GDK\Documentation。

• GDKX 和 GDK 的联机文档位于 Game Development Kit (GDK) 文档。

​

2025 年 10 月 Microsoft Game Development Kit (GDK) 发行说明

​

简介

​

关于本文档

• 新增功能
• 发行说明:
  • 2025 年 10 月 GDK Update 4
  • 2025 年 10 月 GDK Update 3
  • 2025 年 10 月 GDK Update 2
  • 2025 年 10 月 GDK Update 1
  • 2025 年 10 月 GDK
• 已知问题
• 文档

​

2025 年 10 月 Microsoft Game Development Kit 新增功能

• GDK 以两种类型发布:主要版本(侧重于功能,每年两次)和更新(侧重于修复,根据需要随时发布)。
• 若要查看完整的”新增功能”部分,请参阅新增功能的联机版本。

​

2025 年 10 月 GDK Update 4

​

问题修复

​

PlayFab Game Saves

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

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

修复了可能导致同步期间丢失存档数据、游戏存档共享 GDK 上下文时内存损坏以及未通过验证的清单处理不正确的问题。[63647898]

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

​

2025 年 10 月 GDK Update 3

​

通知

​

注册文件类型关联

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

​

输入

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

​

PlayFab Game Saves

在 Steam Deck 上选择 Keep Local 或 Keep Cloud 时保留并回滚到被放弃的游戏存档的功能已禁用,以与 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 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。此设置有助于调试网络问题、代理配置和身份验证问题。此功能需要选择启用,禁用时不会产生任何影响。

​

网络

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 现在会在触发争用回调之前正确验证已完成的清单是否确实由另一台设备创建,从而防止向游戏发送误报通知。

修复了在 Gaming Runtime Services (GRTS) 上,如果指定的存档文件夹目录尚不存在,或提供的路径缺少尾部反斜杠,PlayFab Game Saves 初始化会失败的问题。PlayFab SDK 现在会在需要时自动创建目录,并在初始化之前确保路径格式正确。

修复了一个同步问题:在已完成的云清单版本已超过某个过时的挂起清单之后,进程内版本的 PlayFab Game Saves 可能会错误地重用该挂起清单。现在,只有当挂起清单既属于当前设备,并且其版本高于已完成的云版本时,才会重用它。此变更可防止在多设备同步方案中出现潜在的数据不一致。

修复了使用不同存储提供程序(进程内与 Gaming Runtime Services (GRTS))在设备之间同步游戏存档时,文件修改时间戳不正确的问题。现在,创建压缩存档时会正确保留文件时间戳并将其转换为 UTC,确保所有平台上的时间戳行为一致。

修复了 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 连接字符串时
• 游戏在 XUser 已添加之后才添加邀请处理程序时

修复了进程内游戏运行时未使用 WinHTTP 代理设置的问题。该问题导致通过 netsh winhttp set proxy 配置了代理(例如 Fiddler)时出现 E_XAL_NETWORK 错误。

​

2025 年 10 月 GDK Update 1

• GDKX 和 GDK 以两种类型发布:主要版本(侧重于功能,每年两次)和更新(侧重于修复,根据合作伙伴需要随时发布)。
• 若要查看完整的”新增功能”部分,请参阅新增功能的联机版本。
• 若要查看以前版本的发行说明,请参阅 GDK 论坛上的发行说明帖子,或在联机文档的 GDK 发行说明中查看发行说明。

​

通知

​

API 弃用

XGameActivation API 已取代 XGameProtocol 和 XGameInvite API,为所有游戏激活方案提供单一的 API 接口。因此,XGameProtocol 和 XGameInvite 现已弃用。现有实现将继续正常运行,但我们建议迁移到 XGameActivation,以用于新的开发并确保未来的兼容性。 以下 API 已弃用。

• XGameProtocolRegisterForActivation
• XGameProtocolUnregisterForActivation
• XGameInviteRegisterForEvent
• XGameInviteUnregisterForEvent
• XGameInviteRegisterForPendingEvent
• XGameInviteUnregisterForPendingEvent
• XGameInviteAcceptPendingInvite

有关详细信息,请参阅 XGameActivation。 [61232139]

​

跨平台功能

已添加 XUserSignOutAsync 和 XUserSignOutResult,以支持在 Steam Deck 上注销玩家。可以使用 XUserIsSignOutPresent 确定当前设备是否支持通过 API 注销。[59457172]

​

XBOX 服务

新增了三个 API:XGameInviteRegisterForPendingEvent、XGameInviteUnregisterForPendingEvent 和 XGameInviteAcceptPendingInvite,用于恢复 XGameInvite 回调的一致性。以前,这些回调在进程内和进程外方案中的行为不一致。新的挂起邀请处理程序仅在进程内流程中调用。游戏处理邀请接受后,会调用 XGameInviteAcceptPendingInvite。这将触发邀请已接受回调。 在 Windows 和 XBOX 主机上(可使用 Gaming Runtime Services (GRTS)),由 shell UI 负责邀请接受流程。仅在邀请被接受时才会通知游戏。对于进程内方案(例如 Steam Deck),由游戏处理邀请接受。收到邀请时会触发 XGameInvite 回调,以便游戏可以管理接受流程。 [59693389]

​

图形

对于 XBOX One 系列,新增了 D3D12XBOX_PIPELINE_STATE_FLAG_VS_EXPORT_VIEWPORT_INDEX_REUSE 标志,以防止在使用索引重用和导出 SV_ViewportArrayIndex 的顶点着色器时出现去重问题。[59989696]

​

系统

现在可以在 XBOX 上初始化 DirectStorage 时减小 StagingBuffer 的大小,从而释放游戏内存。 现在提供了相应的枚举值,与默认的 32 MB 暂存大小相比,最多可节省 16 MB 缓冲区。但是,使用较小的缓冲区时,文件性能会略有下降。有关详细信息,请参阅 DirectStorage。 [60006847]

现已提供新接口 IDStorageFactoryX2。它公开了一个用于创建 DirectStorage 队列的新 API CreateQueue1。此 API 采用新的队列定义结构,可以控制新创建的 DirectStorage 队列中是否进行自动提交。有关详细信息,请参阅 DirectStorage。[60039148]

2025 年 10 月 GDK 引入了 XGameUi 回调。它们允许开发人员在 Steam Deck 平台上实现自己的 UX。其中一些回调(尤其是不涉及任何用户交互的 UI 组件的回调)没有关联的 SetResponse API,而这些 API 负责完成异步 UI 调用。现在已引入这些 API,使开发人员能够在 Steam Deck 上完成所有 XGameUi 调用。[60149696]

​

Microsoft Azure PlayFab Game Saves

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

已启用之前处于休眠状态的 PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood 和 RollbackToLastConflict 标志。它们现在会在 PFGameSaveFilesAddUserWithUiAsync 期间响应回滚请求。游戏会获得预期的选择,而不是始终同步到最新存档。[60147982]

现在,在发生 E_INVALIDARG 失败(例如缺少 Steam Deck 存档路径)后,初始化会正确清理。此变更确保后续调用不再报告”已初始化”。[60148008]

添加了日志记录,以改进在进程外运行时的诊断。[60148021]

​

PIX

转换编程计时捕获时,UI 中的 GPU Only Events 设置被忽略。这些设置现在会应用于转换后的捕获。[60294683]

​

问题修复

​

Microsoft Azure PlayFab Party

修复了在没有登录 XUser 时(包括在 Windows 上没有 XBOX 网络用户的情况下玩 Steam 游戏以及在 Steam Deck 上)无法建立 PlayFab Party 语音聊天的问题。[59804895]

​

XBOX 服务

修复了在 Steam Deck 上游戏从 XGameInvite 回调接收的 URI 与在 Windows 上接收的 URI 不一致的问题。Steam Deck URI 仅包含连接字符串,缺少发送方信息和受邀用户 XUID。[59990660]

​

系统

修复了进程内 XGameRuntime 中 XGameGetXboxTitleId 失败并返回 E_GAMERUNTIME_SERVICE_NOT_AVAILABLE 的问题。此失败产生了连锁反应,导致其他 XBOX API(包括 XblMultiplayerActivitySendInvitesAsync)也失败。[60043213]

修复了游戏调用 XLaunchNewGame 后,Visual Studio 中的 Break On Suspend Timeout 配置不生效的问题。[60063672]

​

图形

修复了对于使用增量颜色压缩 (DCC) 的呈现缓冲区,D3D12XBOX_RESOURCE_FLAG_FORCE_TEXTURE_COMPATIBILITY 标志未被遵循的问题。[60237976]

​

GDK 工具

修复了从 XBOX One GDK 命令提示符或 Scarlett GDK 命令提示符执行了错误版本的 dxc.exe 的问题。执行的是 Windows 版本,而不是 XBOX 版本。[60265047]

​

PIX

修复了将 ExecuteIndirect 与 Simple DispatchMesh 命令一起使用时,Mesh Shader Output 显示错误的问题。[60270639]

​

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 所在的路径中。[56987338]

Touch Adaptation Kit Command Line Tool (TAK CLI) (tak.exe) 已从 GDK 安装程序中移除。有关如何下载此工具的说明,请转到 GitHub 上的 TAK CLI。[57605599]

​

问题修复

​

图形

修复了 XBOX Series X|S 主机上 Direct3D 12 驱动程序中的一个问题,该问题导致在创建块压缩资源的非块压缩视图(着色器资源视图 (SRV) 和无序访问视图 (UAV))时使用了错误的大小。[57051436]

​

已知问题

​

脱机 Markdown .zip 文件

问题:
脱机 Markdown .zip 文件目前不可用。 适用于:

• 2025 年 10 月 GDK
• 2025 年 10 月 GDK Update 1

指导:
你仍然可以从 https://aka.ms/gdkdl 下载编译的 HTML 帮助 (.chm) 文件形式的脱机文档。 [60279334]

​

XUserResolveIssueWithUiAsync 流程

问题:
XUserResolveIssueWithUiAsync API 旨在解决用户帐户问题(例如令牌或同意问题),而不是更改已登录的身份。但是,最初使用帐户 A 登录的用户可能会完成此流程并使用帐户 B 登录,从而产生不同的 XUID。 影响:
如果在此流程中帐户发生更改,API 会检测到不匹配并自动使操作失败。 适用于:

• 2025 年 10 月 GDK
• 2025 年 10 月 GDK Update 1

指导:
如果操作由于帐户更改而失败,请移除该用户并重新添加,以确保正确登录。 [59960311]

​

下载压缩的存档数据

问题:
下载压缩后大小大于未压缩大小的存档数据时,PlayFab Game Saves 可能会遇到问题。这种情况最常见于游戏在使用 PlayFab Game Saves 的同时还使用了自己的文件压缩。 适用于:

• 2025 年 10 月 GDK
• 2025 年 10 月 GDK Update 1

指导:
如果可能,请考虑禁用额外的文件压缩。 状态:
此问题将在未来的 GDK 更新中修复。 [60348127]

​

XblTestAccountGui 工具测试帐户错误

问题:
XblTestAccountGui 工具可能无法登录测试帐户。如果出现这种情况,将显示以下错误消息。 Live auth error: Login Error: The remote server returned an error: (400) Bad Request. 适用于:

• 2025 年 10 月 GDK
• 2025 年 10 月 GDK Update 1

状态:
此问题已在 XBOX Live 开发人员工具的最新 GitHub 版本中更正。这些工具可从 https://aka.ms/xbltools 获取。此修复将包含在未来的 GDK 版本中。 [60428977]

​

必须在添加 XUser 之前调用 XGameInviteRegisterForPendingEvent

问题:
在 Steam Deck 上,必须在添加 XUsers 之前调用 XGameInviteRegisterForPendingEvent,否则它们将无法正确注册邀请通知。此顺序要求并非有意为之。 适用于:
2025 年 10 月 GDK Update 1 状态:
此问题将在未来的 GDK 版本中修复。 [60470935]

​

XGameInviteRegisterForPendingEvent 要求设置 connectionString

问题:
在 Steam Deck 上,对于缺少 XBOX Multiplayer Activity (MPA) connectionString 的邀请,XGameInviteRegisterForPendingEvent 不会调用游戏回调。尽管在发送邀请时这是一个可选字段,但 XGameRuntime 会丢弃不包含该字段的邀请负载。

适用于:
2025 年 10 月 GDK Update 1 解决方法:
发送邀请时提供非空的连接字符串。如果接收端不需要,可将其忽略。 状态:
此问题将在未来的 GDK 版本中修复。 [60470935]