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

# Playtest

> 列出、获取、比较、创建、更新、发布和删除 XBOX 游戏的游戏测试。

游戏测试让一组选定的玩家在发布前试玩游戏。`playtest` 命令读取 Partner Center 中游戏的游戏测试,并创建、更新、发布和删除它们。`create`、`update`、`publish` 和 `delete` 在进行更改之前会进行询问。

`create`、`update`、`publish` 和 `delete` 属于实验性命令:其选项和输出可能会更改或被删除。请参阅[实验性命令](https://docs.xbox.com/zh-CN/tools/xbox-cli/cli-command-lifecycle.md)。

## 命令

| 命令 | 说明 |
| - | - |
| `playtest list` | 列出游戏的游戏测试。 |
| `playtest get <playtest-id>` | 获取一个游戏测试:其详细信息、程序包、图像、受众和 `etag`。 |
| `playtest diff <playtest-id>` | 将游戏测试与其上次发布的版本或另一个游戏测试进行比较。 |
| `playtest create` | 创建专用草稿游戏测试(实验性)。 |
| `playtest update <playtest-id>` | 更改游戏测试。已发布的游戏测试会恢复为草稿(实验性)。 |
| `playtest publish <playtest-id>` | 发布游戏测试(从其开始日期起向其受众提供),并等待其变为已计划或已上线状态(实验性)。 |
| `playtest delete <playtest-id>` | 删除游戏测试,并等待其被删除(实验性)。 |

## 参数和选项

| 参数或选项 | 适用于 | 必需 | 说明 |
| - | - | - | - |
| `<playtest-id>` | `get`、`diff`、`update`、`publish`、`delete` | 是 | 来自 `list` 的 `playtestId`,例如 `11111111-2222-3333-4444-555555555555`。 |
| `--store-id <id>` | 全部 | 二者之一 | 游戏的 Store ID,例如 `9N0000000000`。 |
| `--xbox-title-id <id>` | 全部 | 二者之一 | 游戏的 XBOX 游戏 ID(而非其 PlayFab 游戏 ID),例如 `1234ABCD`。如果它不匹配任何游戏或匹配多个游戏,错误会列出应改为传递的 Store ID。 |
| `--compare-to <playtest-id>` | `diff` | 否 | 要与之比较的另一个游戏测试,而不是上次发布的版本。 |
| `--name <name>` | `create`、`update` | `create` | 游戏测试的名称,向玩家显示。不能为空。 |
| `--description <text>` | `create`、`update` | 否 | 简短说明。在 `update` 中,`""` 会将其清除。 |
| `--long-description <text>` | `create`、`update` | 否 | 详细说明。在 `update` 中,`""` 会将其清除。 |
| `--start <date>` | `create`、`update` | `create` | 游戏测试的开始时间。请参阅[日期](#dates)。 |
| `--end <date>` | `create`、`update` | `create` | 游戏测试的结束时间。必须晚于 `--start`。 |
| `--audience-id <id>` | `create`、`update` | 否 | 可以加入的受众,来自 [`audience list`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/audience)。重复此选项可添加更多受众。请参阅[选择受众](#choosing-audiences)。 |
| `--pc-package-id <id>` | `create`、`update` | 否 | 玩家获取的 PC 程序包。请参阅[程序包](#packages)。 |
| `--console-package-id <id>` | `create`、`update` | 否 | 玩家获取的主机程序包。请参阅[程序包](#packages)。 |
| `--idempotency-key <key>` | `create` | 否 | 1 到 50 个可打印 ASCII 字符,用于代替新的 GUID。请参阅[创建游戏测试](#creating-a-playtest)。 |
| `--if-match <etag>` | `update` | 否 | 仅当游戏测试仍具有来自 `playtest get` 的此 `etag` 时才更新。请参阅[更新游戏测试](#updating-a-playtest)。 |
| `--no-wait` | `publish`、`delete` | 否 | 发布或删除一进入队列就立即返回。不能与 `--timeout` 结合使用。 |
| `--timeout <duration>` | `publish`、`delete` | 否 | 等待时长,例如 `90s`、`10m` 或 `2h`。默认为 `5m`;最长为 `7d`。 |
| `--confirm` (`--yes`, `-y`) | `create`、`update`、`publish`、`delete` | 否 | 跳过确认提示。如果不使用此选项且没有终端,命令会拒绝进行更改。 |
| `--seller-id <id>` | 全部 | 如果未保存 | Partner Center 卖家 ID。请参阅[上下文](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md)。 |
| `--base-url <url>` | 全部 | 否 | 请求的基 URL,替代 `XboxPartner:BaseUrl` 配置键。 |
| `--output <format>` | 全部 | 否 | `json`(默认)、`json-compact` 或 `table`。`create`、`update`、`publish` 和 `delete` 拒绝 `table`。 |

## 示例

列出游戏测试、获取一个游戏测试并比较两个游戏测试:

```bash theme={null}
xbox playtest list --store-id 9N0000000000
xbox playtest list --xbox-title-id 1234ABCD --output table
xbox playtest get 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
xbox playtest diff 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --compare-to 22222222-3333-4444-5555-666666666666 --output table
```

为受众创建游戏测试:

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --audience-id 1152921504606846976
```

更改游戏测试的结束日期:

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30
```

发布游戏测试:

```bash theme={null}
xbox playtest publish 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

删除游戏测试:

```bash theme={null}
xbox playtest delete 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

## 读取游戏测试

`playtest list` 写入一个 `playtests` 数组。其表格包含 `PLAYTEST ID`、`NAME`、`STATUS`、`TYPE`、`START` 和 `END` 列。摘录:

```json theme={null}
{ "playtests": [ { "playtestId": "11111111-2222-3333-4444-555555555555", "name": "Alpha", "status": "Live", "type": "Private" } ] }
```

`playtest get` 按服务返回的原样写入游戏测试。`etag` 是要传递给 `update --if-match` 的版本,`audiences.audienceIds` 列出可以加入的受众。其表格包含 `FIELD` 和 `VALUE` 行。

`playtest diff` 写入 `hasDiffData`、`current` 和 `compared`。当 `hasDiffData` 为 `false` 时,没有可比较的内容,并且会省略 `compared`。其表格仅在 `FIELD`、`CURRENT` 和 `COMPARED` 列中显示有差异的字段。不比较图像。

## 创建游戏测试

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15
```

`playtest create` 创建一个专用草稿游戏测试,并按照 `playtest get` 的方式将其写出。再次运行会创建另一个游戏测试;使用 [`playtest delete`](#deleting-a-playtest) 删除你不需要的游戏测试。

每次创建都会发送一个幂等键;除非你传递 `--idempotency-key`,否则它是一个新的 GUID。重复使用某个键的创建会返回该键创建的游戏测试,并忽略任何不同的选项。

当结果未知时(例如超时之后),命令以 `3` 退出,并打印一个使用相同键重试的命令:

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --idempotency-key 11111111-2222-3333-4444-555555555555
```

如果第一个请求已创建游戏测试,重试会返回该游戏测试,否则会创建它。当某个选项包含换行符时,只会打印键;请使用 `--idempotency-key` 和该键运行相同的命令。如果重试被拒绝(例如因为结束日期已过),请先检查 `playtest list`,然后再使用新键创建游戏测试。

## 程序包

一个游戏测试可以有一个 PC 程序包和一个主机程序包。从 [`xbox package list`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/package#listing-packages) 中选择一个已可用于游戏测试的程序包,并将其 `id` 传递给对应其平台的选项:

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --pc-package-id 11111111-2222-3333-4444-555555555555
```

在 `update` 中,省略的程序包选项会保留其程序包,新 ID 会替换它,`""` 会删除它:

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --pc-package-id 22222222-3333-4444-5555-666666666666 --console-package-id ""
```

## 更新游戏测试

> [!WARNING]
>
> 任何更新都会使已发布的游戏测试恢复为草稿,这与在 Partner Center 中编辑它的效果相同。请使用 `playtest publish` 再次发布它,使其可供玩家使用。

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30
```

`playtest update` 仅更改你传递的选项,并且至少需要一个选项。它按照 `playtest get` 的方式写出更新后的游戏测试。在 Partner Center 中配置的游戏图稿会被保留;链接到游戏测试的其他图稿会被替换为占位符。

为避免覆盖他人的更改,请在 `--if-match` 中传递来自 `playtest get` 的 `etag`。其两侧的双引号是可选的,`*`、弱 (`W/`) etag 和 etag 列表会被拒绝:

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --end 2026-11-30 --if-match 0x8DD1234ABCD5678
```

当结果未知时,命令以 `3` 退出。重试之前,请使用 `playtest get` 检查游戏测试。

## 选择受众

受众是卖家在 Partner Center 中管理的一组玩家,例如测试人员。将来自 [`audience list`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/audience) 的 `id` 传递给 `--audience-id`,重复此选项可添加更多受众:

```bash theme={null}
xbox playtest create --store-id 9N0000000000 --name "Nod Arena alpha" --start 2026-11-01 --end 2026-11-15 --audience-id 1152921504606846976 --audience-id 1152921504606846977
```

如果不使用 `--audience-id`,`create` 会创建一个没有受众的游戏测试,而 `update` 会保留现有受众。在 `update` 中,你传递的 ID 会替换游戏测试的所有受众。若要删除所有受众,请仅传递 `""`:

```bash theme={null}
xbox playtest update 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000 --audience-id ""
```

`""` 不能与受众 ID 结合使用,`create` 会拒绝它。游戏测试至少需要一个受众才能发布。

## 发布游戏测试

如果游戏使用 XBOX 服务,请在发布之前设置其配置和禁运。请参阅[在游戏测试中使用 XBOX 服务](https://docs.xbox.com/zh-CN/tools/xbox-cli/xbox-services-in-a-playtest.md)。

```bash theme={null}
xbox playtest publish 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

发布会从开始日期起向受众提供游戏测试。该命令发布它首先读取的版本;如果游戏测试在此期间发生更改,发布会以 `412` 失败,且不会更改任何内容。

在要求你确认之前,该命令会检查游戏的 XBOX 服务设置(例如其禁运日期是否晚于游戏测试的结束日期),并在 stderr 上列出需要查看的任何内容。这些检查仅供参考;`--confirm` 会直接发布而不询问。

然后,服务会运行自己的检查。当某项检查阻止发布时,不会将任何内容加入队列,命令会在 stderr 上列出每项检查并以 `1` 退出。修复错误后再次发布。因缺少年龄分级而被阻止的游戏测试需要在 Partner Center 中完成年龄分级调查问卷。

发布进入队列后,命令会等待游戏测试变为 `Scheduled`、`Live` 或 `PublishFailed`,并按照 `playtest get` 的方式将其写出。按 Ctrl+C 会停止等待,但发布会继续进行。使用 `--no-wait` 时,命令会在发布进入队列后立即写入 `publishJobId` 和任何 `warnings`;之后请使用 `playtest get` 跟踪它。

| 退出代码 | 含义 |
| - | - |
| `0` | 游戏测试为 `Scheduled` 或 `Live`。使用 `--no-wait` 时,表示发布已进入队列。 |
| `1` | 未发布,例如因为某项检查阻止了发布或游戏测试已更改。 |
| `2` | 发布失败:游戏测试为 `PublishFailed`。 |
| `3` | 请求已发送,但结果未知。再次发布之前,请使用 `playtest get` 检查游戏测试。 |
| `4` | 发布已进入队列,但等待在其完成之前结束。请使用 `playtest get` 检查它。 |

## 删除游戏测试

```bash theme={null}
xbox playtest delete 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```

`playtest delete` 删除它首先读取的游戏测试版本。它会等待游戏测试变为 `Deleted` 或消失,然后写入服务的响应(包含 `status`)。按 Ctrl+C 会停止等待,但删除会继续进行。使用 `--no-wait` 时,它会在删除进入队列后立即写入响应。出现 `412` 后,删除可能已进入队列,因此请等待一分钟,并在再次删除之前使用 `playtest get` 进行检查。

| 退出代码 | 含义 |
| - | - |
| `0` | 已删除。使用 `--no-wait` 时,表示删除已进入队列。 |
| `1` | 未删除,例如因为游戏测试已更改或其状态不允许删除。 |
| `3` | 请求已发送,但结果未知。再次删除之前,请使用 `playtest get` 检查游戏测试。 |
| `4` | 删除已进入队列,但在等待结束之前游戏测试未变为 `Deleted`。请使用 `playtest get` 检查它。 |

## 日期

`--start` 和 `--end` 接受 ISO 8601 日期和时间,例如 `2026-11-01T09:00:00-07:00` 或 `2026-11-01T16:00:00Z`。不带时间的日期表示 UTC 午夜,不带偏移量的时间为 UTC。当更新仅传递一个日期时,服务会将其与游戏测试的另一个日期进行核对。

## 错误

除非上面的退出代码表另有说明,否则失败信息会写入 stderr,并以 `1` 退出。当结果未知时,`create` 和 `update` 以 `3` 退出。服务返回的失败包括其 HTTP 状态,`--verbose` 会添加服务的响应,其 `code` 字段如下所示:

| 状态 | `code` | 含义 |
| - | - | - |
| 400 | `invalid_playtest_request` | `create` 或 `update` 发送了无效请求,例如结束时间不晚于开始时间。 |
| 400 | `playtest_audience_not_found` | 某个 `--audience-id` 不是卖家的受众之一。消息会显示用于检查的 `audience list` 命令。 |
| 400 | `playtest_package_not_found` | 游戏没有具有该 ID 的程序包。 |
| 400 | `playtest_package_ambiguous` | 程序包 ID 匹配多个程序包集且其中没有一个位于游戏的 Main 分支上,或者匹配多个市场组且其中没有一个是 `default`。 |
| 400 | `playtest_package_platform_mismatch` | 程序包与其选项的平台不匹配,例如在 `--pc-package-id` 中传递了主机程序包。请使用 `xbox package list` 检查其平台。 |
| 400 | `playtest_request_rejected` | Partner Center 拒绝了该请求,例如 `create` 或 `update` 的结束日期已过去或程序包尚不可用于游戏测试,或者 `publish` 的是已删除的游戏测试。 |
| 403 | `audience_permission_denied` | 你传递了 `--audience-id`,但没有该卖家的 Partner Center 客户组读取权限。未进行任何更改。请向 Partner Center 帐户的管理员申请访问权限。 |
| 403 | `package_permission_denied` | 对于 `list`、`get` 和 `diff`,你没有该游戏的程序包读取权限(开发人员角色包含此权限)。对于其他命令,你没有更改该游戏的游戏测试的权限。请向 Partner Center 帐户的管理员申请访问权限。 |
| 403 | `playtest_not_enabled` | 该游戏和卖家未启用游戏测试,或者服务目前无法进行检查。如果应该已启用,请稍后重试。 |
| 404 | `playtest_not_found` | 游戏没有具有该 ID 或 `--compare-to` ID 的游戏测试。消息会显示用于检查的 `playtest list` 命令。 |
| 404 | `game_not_found` | 卖家没有具有该 Store ID 的游戏。请检查 `--store-id` 和 `--seller-id`。 |
| 409 | `playtest_not_editable` | 游戏测试的状态目前不允许 `update`,例如正在发布时。请使用 `playtest get` 检查它。 |
| 409 | `playtest_ended` | 游戏测试已结束,而 `update` 未传递 `--end`。请在更改时传递一个未来的 `--end`。 |
| 409 | `playtest_not_publishable` | 游戏测试的状态不允许 `publish`,或者自读取以来已更改。请使用 `playtest get` 检查它。 |
| 409 | `playtest_not_deletable` | 游戏测试的状态不允许 `delete`。请使用 `playtest get` 检查它。 |
| 412 | `playtest_precondition_failed` | 游戏测试自读取以来已更改。对于 `update`,请运行 `playtest get`,检查你的更改是否仍然适用,然后使用新的 `etag` 重试。对于 `publish` 和 `delete`,请检查游戏测试并重试。 |
| 422 | `playtest_publish_blocked` | 服务的发布检查失败,因此未将任何内容加入队列。命令会列出每项检查。 |

对于其他失败,命令会显示服务的消息。429 表示你发送的请求过多;请按照消息所述等待相应时长后再重试。


## Related topics

- [使用 Playtest](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/playtest-preview.md)
- [Playtest 概述](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/playtest.md)
- [发布前测试选项](https://docs.xbox.com/zh-CN/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-prerelease.md)
- [产品更改和内容更新](https://docs.xbox.com/zh-CN/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-post-release-lifecycle.md)
- [沙盒](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/sandboxes.md)
