> ## 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 游戏的版本,然后使用 XBOX CLI 和 Partner Center 创建、发布并共享该版本的游戏测试。

游戏测试让选定的一组玩家可以在发布之前或之后,在 XBOX 主机和 PC 上安装你的游戏版本,而无需认证,也无需 Microsoft Store 产品详情页。本页将引导你完成从上传版本到与测试人员共享游戏测试的过程。
[Playtest 概述](https://learn.microsoft.com/gaming/game-publishing/concepts/playtest)介绍了游戏测试的工作原理。

本页中的大多数命令都是实验性命令,因此其选项和输出可能会更改。请参阅
[实验性命令](https://docs.xbox.com/zh-CN/tools/xbox-cli/cli-command-lifecycle.md)。

## 开始之前

* 一个已设置为开发 XBOX 游戏的 Partner Center 帐户,其中包含一个游戏。游戏测试无需单独申请访问权限。
* 游戏的年龄分级。在 Partner Center 中游戏的**年龄分级**页面上,完成一次国际年龄分级联盟 (IARC) 问卷。没有年龄分级,就无法发布游戏测试。
* 在 Partner Center 中管理游戏程序包的权限。如果没有此权限,`package` 和
  `playtest` 命令会失败,并显示 403 `package_permission_denied`。请向你的 Partner Center 帐户的管理员申请此权限;如果游戏属于另一个卖家,请传递 `--seller-id`。
* 使用 `xbox auth login` 登录并选择卖家,如[入门](https://docs.xbox.com/zh-CN/tools/xbox-cli/getting-started.md)中所述。

游戏测试在 RETAIL 沙盒中运行。如果版本使用 XBOX 登录或其他 XBOX 服务,请先按照[在游戏测试中使用 XBOX 服务](https://docs.xbox.com/zh-CN/tools/xbox-cli/xbox-services-in-a-playtest.md)进行操作。

示例使用 Store ID `9N0000000000`。可以使用
`xbox game list --output table` 查找你的游戏的 Store ID。

## 1. 上传程序包

CLI 不会上传程序包。请使用 2026 年 10 月或更高版本的 XBOX
游戏开发工具包 (GDK) 中的 `makepkg` 上传版本。对于版本位于 `layout` 文件夹中的 PC 游戏:

```text theme={null}
makepkg upload /d layout /msixvc2 /pc /storeid 9N0000000000 /branch Main
```

[makepkg 参考](https://learn.microsoft.com/gaming/gdk/docs/features/common/packaging/deployment/makepkg)
介绍了其他程序包格式。之后,Partner Center 会处理该程序包,这可能需要一段时间。若要检查处理情况:

```bash theme={null}
xbox package list --store-id 9N0000000000 --output table
```

当 `STATE` 为 `Processed` 且 `PLAYTEST` 为 `true` 时,程序包即准备就绪。记下其 `PACKAGE ID`。
表格不显示验证结果,因此请在 JSON 中检查其 `validationItems` 不包含严重级别为 `Error` 的项:

```bash theme={null}
xbox package list --store-id 9N0000000000
```

如果 `STATE` 为 `ProcessFailed`、`PLAYTEST` 保持为 `false`,或者存在 `Error` 项,请查看[游戏测试的先决条件](https://learn.microsoft.com/gaming/game-publishing/concepts/playtest-preview#prerequisites-for-a-playtest)中的程序包要求。

## 2. 创建受众

受众决定谁可以安装游戏测试。Partner Center 将其称为客户组。在 Partner Center 的**应用和游戏**工作区中,选择**客户组**,然后选择**创建新组**。选择**已知用户组**,添加你的测试人员,然后保存。

或者,在 `testers.txt` 中列出测试人员的电子邮件地址(每行一个),然后使用实验性的
[`audience create`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/audience#creating-an-audience) 命令创建受众:

```bash theme={null}
xbox audience create --name "Nod Arena testers" --members-file testers.txt
```

记下受众的 `id`,以便将其添加到游戏测试中。

## 3. 创建游戏测试

如果你使用 `audience create` 创建了受众,请使用它输出的 `id`。如果你在 Partner Center 中创建了组,请查找其 `ID`:

```bash theme={null}
xbox audience list --output table
```

如果 `xbox audience list` 超时(这是一个[已知问题](https://docs.xbox.com/zh-CN/tools/xbox-cli/known-issues.md#xbox-audience-list-can-time-out)),请在创建游戏测试时省略 `--audience-id`。之后,在 Partner Center 中,从**服务**下游戏的 Playtest 页面打开该游戏测试,选择步骤 2 中的组,然后保存但不发布。

创建游戏测试:

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

* `--pc-package-id` 采用步骤 1 中的程序包 ID。对于主机程序包,请使用 `--console-package-id`。
* `--audience-id` 采用受众的 ID。重复此选项可添加更多受众。
* 测试人员可以在 `--start` 到 `--end` 期间安装游戏测试。不含时间的日期表示 UTC 午夜。

该命令在创建游戏测试之前会进行询问,然后以 JSON 形式输出游戏测试。记下游戏测试的 ID,即 `details` 下的 `playtestId`。

如果命令以 `3` 退出,则表示它无法判断游戏测试是否已创建。请使用它输出的命令重试,该命令不会创建第二个游戏测试。

## 4. 发布游戏测试

使用步骤 3 中的 ID 发布游戏测试:

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

该命令会等待游戏测试变为 `Live`(如果其开始日期尚未到来,则为 `Scheduled`),然后以 `0` 退出。其他退出代码表示游戏测试尚未发布:

| 退出代码 | 含义 |
| - | - |
| 1 | Partner Center 的检查失败,例如因为游戏测试没有程序包、受众或年龄分级。未发布任何内容。修复命令列出的检查项,然后再次发布。 |
| 2 | 发布失败。 |
| 3 | 结果未知。在再次发布之前,请使用 `xbox playtest get` 检查游戏测试。 |
| 4 | 5 分钟后游戏测试仍在发布中。稍后使用 `xbox playtest get` 进行检查。 |

请参阅[发布游戏测试](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playtest.md#publishing-a-playtest)。

## 5. 共享游戏测试

游戏测试上线后,其受众中的测试人员可以在自己的库中找到它:

* 在主机上,位于**完整库**中的 **Playtest** 筛选器下。
* 在 PC 上,位于 XBOX 应用的**库**中的**访问**筛选器下。

新添加的测试人员需要先注销并重新登录。

你还可以向测试人员发送链接。在 Partner Center 中游戏的 Playtest 页面上,为游戏测试选择**共享**,然后复制以 `msxbox://playtest/` 开头的链接。CLI 目前还无法显示此链接。该链接仅适用于游戏测试受众中的人员,在 PC 上,它会在 XBOX 应用中打开游戏测试。请参阅
[与测试人员共享游戏测试](https://learn.microsoft.com/gaming/game-publishing/concepts/playtest-preview#share-a-playtest-with-testers)。

## 脚本和持续集成

你可以使用服务主体从持续集成 (CI) 管道上传程序包。请参阅
[上传程序包](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/package.md#uploading-packages)。`xbox package` 和
`xbox playtest` 命令尚不接受服务主体,因此它们需要已登录的用户。请参阅
[自动化(服务主体)身份验证](https://docs.xbox.com/zh-CN/tools/xbox-cli/authentication.md#automation-service-principal-authentication)。

在你登录期间运行的脚本中,请向 `playtest create` 和
`playtest publish` 传递 `--confirm`,因为在没有终端的情况下,它们无法询问你,也不会进行任何更改。请读取它们输出的 JSON,并检查其退出代码。若要等待发布超过 5 分钟,请传递
`--timeout`。


## Related topics

- [入门](https://docs.xbox.com/zh-CN/tools/xbox-cli/getting-started.md)
- [XBOX CLI](https://docs.xbox.com/zh-CN/tools/xbox-cli/index.md)
- [使用 Playtest](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/playtest-preview.md)
- [Game Manager 快速入门](https://docs.xbox.com/zh-CN/services/playfab/live-service-management/gamemanager/quickstart.md)
- [制作游戏 第 1 部分 - 设置](https://docs.xbox.com/zh-CN/services/playfab/economy-monetization/economy-v2/tutorials/craftingGame/crafting-game-environment.md)
