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

# 套件

> 列出及取得 Partner Center 遊戲的套件、檢查組建是否可用於試玩測試，以及了解如何上傳組建。

套件是 Partner Center 已接收並處理的遊戲組建。`package` 命令可列出及取得遊戲的套件，讓您檢查套件是否已準備好用於[試玩測試](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playtest.md)。若要上傳套件，請參閱[上傳套件](#uploading-packages)。

這些命令為實驗性功能：其選項和輸出可能會變更。請參閱[實驗性命令](https://docs.xbox.com/zh-TW/tools/xbox-cli/cli-command-lifecycle.md)。它們需要具備遊戲的 Partner Center 套件讀取權限，開發人員角色已包含此權限。

## 命令

| 命令 | 描述 |
| - | - |
| `package list` | 列出遊戲 Main 分支上的套件。 |
| `package get <package-id>` | 取得一個套件。 |

## 引數和選項

| 引數或選項 | 適用於 | 必要 | 描述 |
| - | - | - | - |
| `<package-id>` | `get` | 是 | 套件 ID，來自 `package list`。 |
| `--store-id <id>` | 全部 | 兩者之一 | 遊戲的 Store ID，例如 `9N0000000000`。 |
| `--xbox-title-id <id>` | 全部 | 兩者之一 | 遊戲的 XBOX 遊戲識別碼 (而非其 PlayFab 遊戲識別碼)，例如 `1234ABCD`。當該遊戲識別碼對應到多個遊戲時，命令會要求提供 `--store-id`。 |
| `--seller-id <id>` | 全部 | 否 | Partner Center 賣方 ID。 |
| `--base-url <url>` | 全部 | 否 | 要求的基底 URL，會覆寫 `XboxPartner:BaseUrl` 設定索引鍵。 |
| `--output <format>` | 全部 | 否 | `json` (預設)、`json-compact` 或 `table`。 |

賣方來自 `--seller-id` 或您已儲存的賣方；請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)。若兩者皆無，命令會使用您唯一的賣方，而當您屬於多個賣方時，會要求提供 `--seller-id`。`--xbox-title-id` 一律需要賣方。

## 列出套件

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

`package list` 會寫入遊戲 Main 分支的 ID，以及包含服務所傳回之每個欄位的 `packages` 陣列。`package get` 會以相同的形式寫入一個套件。摘錄如下：

```json theme={null}
{
  "packageSetId": "22222222-3333-4444-5555-666666666666",
  "packages": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "version": "1.0.0.0",
      "platform": "PC",
      "packageType": "Msixvc",
      "processingState": "Processed",
      "isAvailableForPlaytest": true,
      "validationItems": [],
      "fileName": "Nod.Arena_1.0.0.0_x64.msixvc",
      "createdAt": "2026-11-04T18:00:00Z"
    }
  ]
}
```

當下列所有條件都成立時，套件即已準備好用於試玩測試：

* `processingState` 為 `Processed`。它會從 `PendingUpload` 經過 `Uploaded` 和 `Processing` 變為 `Processed`，或變為 `ProcessFailed`。
* `validationItems` (Partner Center 在處理套件時發現的問題) 中沒有嚴重性為 `Error` 的項目。
* `isAvailableForPlaytest` 為 `true`。

`--output table` 包含 `PACKAGE ID`、`VERSION`、`PLATFORM`、`STATE`、`PLAYTEST` 和 `CREATED` 欄。它不會顯示驗證結果，因此請在 JSON 中檢查 `validationItems`。

## 上傳套件

CLI 不會上傳套件。請使用 XBOX 遊戲開發套件 (GDK) 中的 `makepkg` 上傳套件；請參閱 [makepkg 參考](https://learn.microsoft.com/gaming/gdk/docs/features/common/packaging/deployment/makepkg)，若是從持續整合 (CI) 上傳，請參閱 [Package Uploader](https://learn.microsoft.com/gaming/gdk/docs/features/common/packaging/package-uploader)。然後執行 `package list` 以檢查套件是否已準備就緒。

## 錯誤

無論 `--output` 為何，錯誤都會以文字形式傳送到 stderr，並附上相互關聯識別碼。`--verbose` 會加入回應本文。失敗時會以 `1` 結束。

| 錯誤 | 處理方式 |
| - | - |
| HTTP 401 | 使用 `xbox auth login` 重新登入。 |
| HTTP 403，`package_permission_denied` | 您不具備此賣方之遊戲的套件讀取權限。請向 Partner Center 帳戶的管理員要求開發人員角色，或者如果遊戲屬於另一個賣方，請傳遞 `--seller-id`。 |
| HTTP 403，`identity_override_not_authorized` | 您不屬於該賣方。請檢查賣方，並使用 `xbox seller list` 找出您的賣方。 |
| HTTP 400，`seller_selection_required` | 您屬於多個賣方。請傳遞 `--seller-id`。 |
| HTTP 404，`game_not_found` | 賣方沒有具有該 Store ID 的遊戲。請檢查 `--store-id` 和 `--seller-id`。 |

## 範例

```bash theme={null}
xbox package list --store-id 9N0000000000
xbox package list --xbox-title-id 1234ABCD --seller-id 1234567 --output table
xbox package get 11111111-2222-3333-4444-555555555555 --store-id 9N0000000000
```


## Related topics

- [套件](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/game-package-management.md)
- [Publisher Content 套件](https://docs.xbox.com/zh-TW/build/core-features/common/packaging/packaging-publisher-content.md)
- [套件 (傳統體驗)](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/packages-overview.md)
- [建立套件 (makepkg.exe)](https://docs.xbox.com/zh-TW/build/core-features/common/packaging/deployment/makepkg.md)
- [管理套件 (wdapp.exe)](https://docs.xbox.com/zh-TW/tools/tools-console/console_commandlinetools/wdapp.md)
