跳转到主要内容
本页列出了 XBOX CLI 最新版本中的已知问题,包括未完成的功能。如果你的问题已在此处列出,则无需报告。 仅支持最新版本。xbox upgrade 会告诉你是否有更新的版本可用。标记为已修复的条目已在最新版本中修复,并会在下一个版本中删除。

如果你的问题未列出

  1. 使用 xbox upgrade 检查你是否正在运行最新版本。
  2. 搜索现有问题。
  3. 如果尚未报告该问题,请使用 xbox feedback 进行报告,该命令会打开一个已填写环境详细信息的 bug 报告。问题是公开的,因此请省略任何你不愿公开分享的内容。

更新 CLI

xbox upgrade 失败并显示 HTTP 301

已修复 CLI 的公共存储库已迁移,v0.2.1 中的 xbox upgrade 每次都会失败,并显示 HTTP 301: GitHub release metadata is unavailable。 解决方法:按照安装下载最新版本。

登录和权限

某些命令目前还不能与个人 Microsoft 帐户一起使用

当你使用个人 Microsoft 帐户(而不是工作或学校帐户)登录时,用于 XBOX 服务配置、测试帐户、程序包、游戏测试和受众的命令无法正常工作。XBOX 服务配置和测试帐户命令会失败并显示 HTTP 502,报告为服务不可用,但重试也无济于事。 解决方法:使用工作或学校帐户在 Partner Center 中加入你的卖家,并使用该帐户登录 CLI。

xbox game、xbox xbl 和类似命令尚不接受服务主体

服务主体可以登录,但当它运行 audience、game、package、playtest、sandbox、 seller、test-account 和 xbl 命令时,这些命令会失败并显示授权错误,因为它们调用的服务尚不接受服务主体。 解决方法:以已登录用户的身份运行这些命令。在有人使用 xbox playfab service-principal set 授予服务主体访问权限后,xbox playfab 命令即可与服务主体一起使用。请参阅 自动化(服务主体)身份验证。

当你属于多个卖家时,某些卖家的命令会被拒绝

如果你属于多个 Partner Center 卖家,则对于除你上次在 Partner Center 中选择的卖家之外的所有卖家,用于 XBOX 服务配置、测试帐户、程序包、游戏测试和受众的命令都可能会被拒绝。 解决方法:在 Partner Center 中选择所需的卖家,然后再次运行该命令。

xbox seller list 有时会遗漏你的某个卖家

如果你属于多个 Partner Center 卖家,xbox seller list 有时会遗漏其中一个卖家且不显示错误,而下一次运行可能会列出它。在该卖家缺失期间,针对该卖家的命令(例如 xbox audience list)可能会被拒绝,并且目前尚不清楚在 Partner Center 中选择该卖家是否有帮助。

xbox game 命令会忽略 --seller-id

xbox game list、xbox game get 和 xbox game create 使用你上次在 Partner Center 中选择的卖家,而不是你使用 --seller-id 传递或保存在上下文中的卖家,因此 game create 可能会在另一个卖家中创建游戏。不属于你的卖家 ID(例如输入错误的 ID)不会导致这些命令失败;它们会返回你自己的游戏。 解决方法:在 Partner Center 中选择所需的卖家,然后在创建游戏之前,检查 xbox game list 是否显示该卖家的游戏。此更改最多可能需要 15 分钟才能反映到 CLI 中。

xbox sandbox 命令仅显示全局沙盒

当你使用 --seller-id 传递或保存在上下文中的卖家不是你上次在 Partner Center 中选择的卖家时, xbox sandbox list 和 xbox sandbox get 只能找到 CERT、 CERT.DEBUG 和 RETAIL 沙盒,且不会失败。xbox sandbox create 会在你上次选择的卖家中创建沙盒,如果那是另一个卖家,它会以 4 退出,因为它无法回读该沙盒。请勿再次创建该沙盒。 解决方法:在 Partner Center 中选择所需的卖家,然后使用该卖家再次运行该命令。此更改最多可能需要 15 分钟才能反映到 CLI 中。

使用游戏测试和受众进行测试

xbox audience list 可能会超时

xbox audience list 可能会耗时过长,导致请求超时。--name 没有帮助,因为它会在读取所有受众之后才筛选列表。

XBOX 服务配置

某些下载的 XML 文档声明了错误的编码

xbox xbl config download --view published 保存的某些已发布 XML 文档(例如 mpsdtitleinfo.xml 和 titlename-localization.xml)声明了 encoding="utf-16",但实际以 UTF-8 编码,因此信任该声明的 XML 读取器无法加载它们。 解决方法:在分析文件之前,先将其解码为 UTF-8。

PlayFab

xbox playfab api /Admin/UpdatePolicy 可能会在未经确认的情况下覆盖策略

如果请求正文中包含 "OverwritePolicy": true,此调用会替换游戏的整个 API 访问策略,而不具备 xbox playfab api-policy set --overwrite 的保护措施:它不需要 --confirm,并且可以使用已保存上下文或 XBOX_PLAYFAB_TITLE_ID 中的游戏。 错误的策略可能会将所有玩家锁定在游戏之外。 解决方法:改用 xbox playfab api-policy set --overwrite,它需要 --confirm,并且需要使用 --playfab-title-id 传递游戏。

playfab title-data delete 和 playfab player-data delete 不会先询问

其他删除内容的命令会在运行之前进行询问,或者在没有 --confirm 的情况下拒绝运行。而这两个命令会立即删除你指定的键。

--keys 和 --member-ids 采用逗号分隔的列表

xbox playfab title-data 和 xbox playfab player-data 上的 --keys,以及 xbox playfab group member 上的 --member-ids,都采用逗号分隔的列表。它们将改为可重复的选项,因此使用它们的脚本将需要更新。 在此之前,--keys 无法指定包含逗号的键。若要读取这样的键,请使用 --key 传递它,该选项会接受完整的名称,但 delete 只有 --keys。 解决方法:若要删除该键,请使用 xbox playfab api 调用 delete 所使用的 API。对于游戏数据,请将该键的值设置为 null;对于内部游戏数据,请改用 /Admin/SetTitleInternalData:
对于玩家数据,请在 KeysToRemove 中列出该键,并使用玩家数据中与数据可见性对应的更新 API:

脚本和代理

当无法确定更改是否已完成时,大多数命令会以 1 退出

少数命令在无法判断是否已进行更改时(例如请求发送后超时)会以 3 退出,其页面会对此进行说明。其他所有命令(包括所有 PlayFab 命令)在任何失败时都会以 1 退出,因此脚本无法将这种情况与未进行更改的情况区分开来。 解决方法:当会更改内容的命令失败时,请先检查当前状态,然后再重新运行该命令。
最后修改于 2026年11月19日