跳转到主要内容
xbl 命令系列属于实验性功能。其 CLI 接口可能会根据反馈而更改或被删除。 xbox xbl 管理 XBOX 服务配置(工作配置和已发布配置的状态、配置文档、发布以及配置架构)以及成就图像。若要列出配置命令所针对的沙盒,请使用 xbox sandbox list。 这些命令使用的配置与 Partner Center 编辑的配置相同。有关每项 XBOX 服务功能的作用及其配置方式,请参阅 XBOX 开发人员文档中的门户配置概述。

共享行为

卖家和沙盒

除 schema 命令外,每个命令都接受 --seller-id。如果未指定,命令会使用 XBOX_SELLER_ID 或通过 xbox context set 保存的卖家,然后使用你唯一的卖家;如果你有多个卖家,请传递 --seller-id。 当你省略 --sandbox-id 时,config status 和 config publish 会从 XBOX_SANDBOX_ID 或已保存的 sandbox-id 获取它。对于沙盒文档,config download 和 config save 需要在命令行上提供 --sandbox-id。

游戏定位

config list、config status、config publish,以及沙盒范围的 config download 和 config save 通过 --scid 接受游戏的服务配置标识符 (SCID),或通过 --title-id 接受其 XBOX 游戏 ID,但不能同时接受两者。如果两者都未指定,它们会使用 XBOX_TITLE_ID 或已保存的 title-id;请参阅上下文。--scid 会忽略这两者。
  • --title-id 为十六进制,与 game get 显示的形式相同:00000001 到 7FFFFFFF,可带可选的 0x 前缀。对于其他游戏 ID,请传递 SCID。
  • 读取绑定到另一个游戏配置的游戏时,会使用主游戏的 SCID。
  • 通过绑定游戏的 ID 执行 config save 和 config publish 会被拒绝,即使使用 --validate-only 也是如此 (bound_title_requires_scid)。错误会指明主游戏和 SCID;请使用该 --scid 重新运行。
  • 通过 --title-id 保存或发布到其他游戏所绑定的配置时,会更改所有这些游戏的配置。在终端中,CLI 会列出绑定的游戏并先进行询问;如果没有终端,则会失败。--allow-shared-configuration 会跳过该询问。通过 --scid 进行写入时不会询问。
  • config save 和 config publish 会将它们使用的卖家和 SCID 写入 stderr。读取命令在使用 --verbose 时也会这样做。
以下命令保存一个游戏 ID,然后使用它来读取、下载和验证该游戏在 XDKS.1 中的配置。最后一个命令改为使用 --title-id 指定游戏:

输出

每个 xbl 命令都接受 --output table,以及 json(默认)和 json-compact。每个命令的选项表都列出了其表格列。

错误

失败的请求以 1 退出,并将 JSON 错误写入 stderr,其中包含 status、title、detail 以及 code(如果服务发送了)。请根据 status 或 code 而不是 detail 的措辞进行分支处理。429 错误包含 retryAfterSeconds;请参阅速率限制。 当 XBOX 服务验证拒绝配置时,错误会在 validation 下列出每条消息:
不使用 --validate-only 时,config save 和 config publish 会说明失败的更改是否可能已被应用: 以 3 退出时,请勿重新提交。stderr 会打印一个用于检查的只读命令:对于保存,是 config download --view draft,用于与你保存的文件进行比较;对于发布,是 config status。

config

检查、下载、保存和发布一个 SCID 的 XBOX 服务配置。沙盒包含一个工作配置(由 config save 更改)和一个已发布配置(在 config publish 使工作配置上线后,玩家和测试帐户会看到该配置)。

config list 和 config status

这两个命令都会报告最新的工作版本和已发布版本、每个版本的提交时间,以及工作版本是否有未发布的更改。已发布的提交时间是已发布版本的提交时间,而不是发布完成的时间。 config list 返回一个数组,每个沙盒对应一个对象。config status 返回一个沙盒的一个对象,并在 lastPublish 下添加其上次发布;如果没有可报告的内容,则为 null。对于 --sandbox-id ALL,lastPublish 始终为 null,因为 ALL 中的游戏范围配置是通过发布到 HIDDEN 来上线的。

config list 选项

config status 选项

这两个命令的表格都包含 SANDBOX、WORKING、WORKING COMMIT、PUBLISHED、PUBLISHED COMMIT 和 UNPUBLISHED 列。config status 还添加了 PUBLISH STATUS,即上次发布的 status。

config list 和 config status 示例

config download 和 config save

下载、验证和保存 XBOX 服务配置文档集。文档集属于沙盒(默认值,需要 SCID 或游戏 ID 以及 --sandbox-id)或属于帐户(--type account,不接受 SCID、游戏 ID 或沙盒)。 config download 会将文档集的 ETag 保存在文档旁边,名为 <sandbox>.etag,帐户范围则为 Account.etag;在 Windows 上,该文件是隐藏的。config save 会读取与 --file 匹配的第一个文件旁边的 ETag 文件,并在保存后重写该文件。如果配置在你下载后发生了更改,保存会失败;传递 --force 可覆盖这些更改进行保存,或传递 --etag 自行提供 ETag。 config save 在保存之前不会询问,--confirm 也不适用于它。请先使用 --validate-only 运行它。

config download 选项

config save 选项

当 XBOX 服务无法保存文档时(使用 --validate-only 时 CanCommit 为 false,否则 Committed 为 false),该命令仍会将结果写入 stdout,将每条验证消息写入 stderr,保持 ETag 文件不变,并以 1 退出:
与最新工作文档相同的文档不算失败:不会保存任何内容,ValidationInfo 报告 FilesNotChangedCommit,并且命令以 0 退出。

config download 和 config save 示例

将最新的草稿沙盒文档下载到 xbox-config 中:
编辑文档后,验证所有文档,或仅验证你更改的两个文档:
附带消息保存它们:
下载一个文档在已发布版本 7 中的内容:
下载帐户的草稿文档:

config publish

将 XBOX 服务配置的工作版本发布到沙盒的已发布配置。发布是异步的:使用 config publish 启动发布,然后针对目标沙盒运行 config status,直到 lastPublish.status 为 Success 或 Failed。

源选择

--sandbox-id 是目标。源是源沙盒的一个工作版本,源沙盒默认为目标沙盒: 当源沙盒有未发布的更改时,其最新工作版本并不是该沙盒中已上线的版本。此时,不带 --configset 的跨沙盒发布会发出警告,并指明已上线的版本:
若要准确推广源中已上线的内容,请先使用 --validate-only 运行,然后添加其建议的 --configset。在 JSON 输出中,SourceVersion 是所使用的工作版本,sourceHasUnpublishedChanges 说明它是否与源中已上线的内容不同,sourceLiveVersion 是在找到时该处已上线的版本。 游戏范围的发布 (--sandbox-id HIDDEN) 始终发布 ALL 中最新的工作配置,因此它不接受 --source-sandbox-id 或 --configset。若要查看哪个版本将上线,请先运行 config status --sandbox-id ALL 并读取 workingVersion。

确认

在以下情况下,config publish 会在发布之前进行询问: 在终端中,它会描述此次发布并进行询问。如果没有终端,它会拒绝执行并以 1 退出。--confirm (--yes, -y) 会跳过询问,--validate-only 从不询问。请参阅安全性和破坏性操作。 在询问 RETAIL 发布之前,它会验证此次发布并列出发布添加的成就。如果你回答“是”,它会发布经过验证的工作版本,因此上线的内容就是所列出的内容:
如果该验证失败,它不会发布任何内容,也不会询问。因此,在终端中,通过 --title-id 向其他游戏所绑定的配置进行 RETAIL 发布时,需要 --allow-shared-configuration。使用 --confirm 时不会显示列表,因此请先运行 --validate-only 以查看列表。

RETAIL 发布添加的成就

成就在 RETAIL 中上线后,便无法删除,其解锁规则和玩家分数也无法更改。因此,RETAIL 发布会说明它添加了哪些 RETAIL 中尚不存在的成就 ID:
  • 使用 --validate-only 时,列表会写入 stderr,JSON 输出会将其包含在 achievementChanges.added 中。
  • 在终端中不使用 --validate-only 时,列表会显示在询问之前,如确认中所示。
不添加任何成就的发布也会说明这一点。其他沙盒不会列出成就。

重新发布

config publish 仅发布更改。如果自目标上次成功发布以来没有任何更改,则不会启动发布,结果的 Status 为 AlreadyPublished。发布失败后,再次运行 config publish 会重试该发布。 有时 XBOX 会为某个产品锁定 RETAIL,此时从 RETAIL 到 RETAIL 的发布会失败,并返回 retail_locked。若要仍然发布,请添加 --republish:它会将所选配置(默认为 RETAIL 的最新工作配置)强制发布到 RETAIL。从其他沙盒(例如 CERT)发布到 RETAIL 也会解除锁定,但会用该沙盒的工作文档替换 RETAIL 的工作文档。 --republish 会进行完整发布,即使没有任何更改也是如此。它不能与 --validate-only 结合使用。

诊断

来自 XBOX 服务的验证诊断(例如首次在没有禁运的情况下发布到 RETAIL 时的警告)会写入 stderr,每行一条。JSON 输出会将它们保存在 ValidationResult 中。
验证失败时,config publish 以 1 退出,并在 validation 下列出每条消息,如错误中所示。

跨沙盒发布会替换全局游戏存储文件

从一个沙盒发布到另一个沙盒会使目标的全局游戏存储文件成为源的精确副本。仅目标拥有的文件会被删除,且无法恢复。
全局文件是游戏的每个玩家都会读取的文件,例如新闻源和地图: 复制会获取发布运行时源所包含的任何内容。玩家自己的数据不受影响,同一沙盒内的发布也不会改动全局文件。若要保留某个目标文件,请在发布之前将其添加到源沙盒。 每次跨沙盒发布都会将此警告写入 stderr(包括使用 --validate-only 时),并将其包含在确认询问中:

config publish 选项

config publish 示例

验证到 SANDBOX1 的发布而不实际发布:
发布 SANDBOX1 的最新工作配置,使其在 SANDBOX1 中上线:
将 SANDBOX1 的最新工作版本发布到 SANDBOX2。这还会用 SANDBOX1 的全局游戏存储文件替换 SANDBOX2 的全局游戏存储文件:
将 SANDBOX1 的工作版本 42 发布到 SANDBOX2:
验证从 CERT 到 RETAIL 的发布,这会列出它添加的成就:
然后将输出的 SourceVersion 作为 --configset 传递,以在不显示提示的情况下发布你验证过的版本:
尽管没有任何更改,仍再次发布 SANDBOX1:
检查到 SANDBOX2 的发布:

schema

发现和下载 XBOX 服务配置文档架构。

schema list 选项

schema get 选项

schema get 写入一个 JSON 对象:

schema download 选项

每个架构都保存为 <type>_<version>.xsd(类型为小写),并且该命令会打印已保存的路径。使用 --dest - 时,它会改为将原始 XSD 写入 stdout,并且 --output 不适用。

schema 示例


典型的配置往返流程

  1. 查找你可以访问的沙盒:
  2. 查看工作配置和已发布配置的状态:
  3. 下载草稿文档集,这也会保存 SANDBOX1.etag:
  4. 编辑 xbox-config 中的文档,然后验证它们:
  5. 保存它们:
  6. 在 SANDBOX1 中发布它们:
  7. 检查发布,并重复此操作,直到其状态为 Success 或 Failed:
最后修改于 2026年11月19日