> ## 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.

# 已知问题

> XBOX CLI 最新版本中的问题和未完成的功能,以及如何解决这些问题。

本页列出了 XBOX CLI 最新版本中的已知问题,包括未完成的功能。如果你的问题已在此处列出,则无需报告。

仅支持最新版本。[`xbox upgrade`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/upgrade) 会告诉你是否有更新的版本可用。标记为**已修复**的条目已在最新版本中修复,并会在下一个版本中删除。

## 如果你的问题未列出

1. 使用 [`xbox upgrade`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/upgrade) 检查你是否正在运行最新版本。
2. 搜索[现有问题](https://github.com/xbox/cli/issues)。
3. 如果尚未报告该问题,请使用 [`xbox feedback`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/feedback) 进行报告,该命令会打开一个已填写环境详细信息的 bug 报告。问题是公开的,因此请省略任何你不愿公开分享的内容。

## 更新 CLI

### `xbox upgrade` 失败并显示 HTTP 301

**已修复**

CLI 的公共存储库已迁移,v0.2.1 中的 [`xbox upgrade`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/upgrade) 每次都会失败,并显示
`HTTP 301: GitHub release metadata is unavailable`。

**解决方法**:按照[安装](https://docs.xbox.com/zh-CN/tools/xbox-cli/installation.md)下载最新版本。

## 登录和权限

### 某些命令目前还不能与个人 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`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/service-principal) 授予服务主体访问权限后,`xbox playfab` 命令即可与服务主体一起使用。请参阅
[自动化(服务主体)身份验证](https://docs.xbox.com/zh-CN/tools/xbox-cli/authentication.md#automation-service-principal-authentication)。

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

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

**解决方法**:在 Partner Center 中选择所需的卖家,然后再次运行该命令。

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

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

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

[`xbox game list`、`xbox game get` 和 `xbox game create`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/game) 使用你上次在 Partner Center 中选择的卖家,而不是你使用 `--seller-id` 传递或保存在[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)中的卖家,因此 `game create` 可能会在另一个卖家中创建游戏。不属于你的卖家 ID(例如输入错误的 ID)不会导致这些命令失败;它们会返回你自己的游戏。

**解决方法**:在 Partner Center 中选择所需的卖家,然后在创建游戏之前,检查 `xbox game list` 是否显示该卖家的游戏。此更改最多可能需要 15 分钟才能反映到 CLI 中。

### `xbox sandbox` 命令仅显示全局沙盒

当你使用 `--seller-id` 传递或保存在[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)中的卖家不是你上次在 Partner Center 中选择的卖家时,
[`xbox sandbox list` 和 `xbox sandbox get`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/sandbox) 只能找到 `CERT`、
`CERT.DEBUG` 和 `RETAIL` 沙盒,且不会失败。`xbox sandbox create` 会在你上次选择的卖家中创建沙盒,如果那是另一个卖家,它会以 `4` 退出,因为它无法回读该沙盒。请勿再次创建该沙盒。

**解决方法**:在 Partner Center 中选择所需的卖家,然后使用该卖家再次运行该命令。此更改最多可能需要 15 分钟才能反映到 CLI 中。

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

### `xbox audience list` 可能会超时

[`xbox audience list`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/audience) 可能会耗时过长,导致请求超时。`--name` 没有帮助,因为它会在读取所有受众之后才筛选列表。

## XBOX 服务配置

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

[`xbox xbl config download --view published`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/xbl) 保存的某些已发布 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`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/api-policy),它需要 `--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`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/group) 上的 `--member-ids`,都采用逗号分隔的列表。它们将改为可重复的选项,因此使用它们的脚本将需要更新。

在此之前,`--keys` 无法指定包含逗号的键。若要读取这样的键,请使用 `--key` 传递它,该选项会接受完整的名称,但 `delete` 只有 `--keys`。

**解决方法**:若要删除该键,请使用 [`xbox playfab api`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/api) 调用 `delete` 所使用的 API。对于游戏数据,请将该键的值设置为 `null`;对于内部游戏数据,请改用 `/Admin/SetTitleInternalData`:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/SetTitleData --body '{"Key":"Level,Bonus","Value":null}'
```

对于玩家数据,请在 `KeysToRemove` 中列出该键,并使用[玩家数据](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/player-data.md)中与数据可见性对应的更新 API:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/UpdateUserData --body '{"PlayFabId":"PLAYER123","KeysToRemove":["Level,Bonus"]}'
```

## 脚本和代理

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

少数命令在无法判断是否已进行更改时(例如请求发送后超时)会以 `3` 退出,其页面会对此进行说明。其他所有命令(包括所有 PlayFab 命令)在任何失败时都会以 `1` 退出,因此脚本无法将这种情况与未进行更改的情况区分开来。

**解决方法**:当会更改内容的命令失败时,请先检查当前状态,然后再重新运行该命令。


## Related topics

- [PC 版 Unity 开发入门（内容）](https://docs.xbox.com/zh-CN/build/gdk-and-engines/unity/unity.md)
- [发行说明 - XBOX PC Remote Tools（2026 年 3 月）](https://docs.xbox.com/zh-CN/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md)
- [使用 Playtest](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/playtest-preview.md)
- [XBOX PC Remote Tools 常见问题解答和故障排除指南](https://docs.xbox.com/zh-CN/tools/tools-pc/xbox-pc-remote-tools/faq.md)
- [Visual Studio 2019 GDK 支持说明](https://docs.xbox.com/zh-CN/tools/tools-console/visualstudio/vs-2019-support-notes.md)
