> ## 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-TW/tools/xbox-cli/cli-command-lifecycle.md)。

## 開始之前

* 一個已設定為可開發 XBOX 遊戲且其中有遊戲的 Partner Center 帳戶。試玩測試不需要另外要求存取權。
* 遊戲的年齡分級。在 Partner Center 中遊戲的 **Age ratings** 頁面上，完成一次 International Age Rating Coalition (IARC) 問卷。沒有分級就無法發佈試玩測試。
* 在 Partner Center 中管理遊戲套件的權限。若沒有此權限，`package` 和 `playtest` 命令會以 403 `package_permission_denied` 失敗。請向您 Partner Center 帳戶的管理員要求此權限，或者如果遊戲屬於其他賣方，請傳遞 `--seller-id`。
* 依照[開始使用](https://docs.xbox.com/zh-TW/tools/xbox-cli/getting-started.md)中的說明，使用 `xbox auth login` 登入並選擇賣方。

試玩測試會在 RETAIL 沙箱中執行。如果組建使用 XBOX 登入或其他 XBOX services，請先依照[在試玩測試中使用 XBOX services](https://docs.xbox.com/zh-TW/tools/xbox-cli/xbox-services-in-a-playtest.md) 進行操作。

範例使用 Store ID `9N0000000000`。使用 `xbox game list --output table` 尋找您遊戲的 Store ID。

## 1. 上傳套件

CLI 不會上傳套件。請使用 2026 年 10 月或更新版本 XBOX Game Development Kit (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 的 **Apps and games** 工作區中，選取 **Customer groups**，然後選取 **Create new group**。選擇 **Known user group**、新增您的測試人員，然後儲存。

或者，在 `testers.txt` 中列出測試人員的電子郵件地址 (每行一個)，並使用實驗性的 [`audience create`](https://docs.xbox.com/zh-TW/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-TW/tools/xbox-cli/known-issues.md#xbox-audience-list-can-time-out))，請在建立試玩測試時省略 `--audience-id`。之後，在 Partner Center 中，從遊戲 **Services** 下的 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-TW/tools/xbox-cli/commands/playtest.md#publishing-a-playtest)。

## 5. 分享

試玩測試上線後，其對象中的測試人員就可以在其收藏庫中找到它：

* 在主機上，位於 **Full Library** 的 **Playtest** 篩選條件下。
* 在 PC 上，位於 XBOX 應用程式 **Library** 的 **Access** 篩選條件下。

新加入的測試人員必須先登出再重新登入。

您也可以傳送連結給測試人員。在 Partner Center 中遊戲的 Playtest 頁面上，選取試玩測試上的 **Share**，然後複製以 `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-TW/tools/xbox-cli/commands/package.md#uploading-packages)。`xbox package` 和 `xbox playtest` 命令尚不接受服務主體，因此需要已登入的使用者。請參閱[自動化 (服務主體) 驗證](https://docs.xbox.com/zh-TW/tools/xbox-cli/authentication.md#automation-service-principal-authentication)。

在您登入時執行的指令碼中，請將 `--confirm` 傳遞給 `playtest create` 和 `playtest publish`，因為沒有終端機時，它們無法詢問您，也不會進行任何變更。請讀取它們列印的 JSON，並檢查其結束代碼。若要等候發佈超過 5 分鐘，請傳遞 `--timeout`。


## Related topics

- [開始使用](https://docs.xbox.com/zh-TW/tools/xbox-cli/getting-started.md)
- [XBOX CLI](https://docs.xbox.com/zh-TW/tools/xbox-cli/index.md)
- [使用 Playtest](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/playtest-preview.md)
- [Playtest](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playtest.md)
- [在試玩測試中使用 XBOX services](https://docs.xbox.com/zh-TW/tools/xbox-cli/xbox-services-in-a-playtest.md)
