> ## 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-CN/tools/xbox-cli/commands/playtest.md)。若要上传程序包,请参阅[上传程序包](#uploading-packages)。

这些命令属于实验性命令:其选项和输出可能会更改。请参阅
[实验性命令](https://docs.xbox.com/zh-CN/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 游戏 ID(而非其 PlayFab 游戏 ID),例如 `1234ABCD`。当该游戏 ID 对应多个游戏时,命令会要求提供 `--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-CN/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"
    }
  ]
}
```

当以下所有条件都为 true 时,程序包即可用于游戏测试:

* `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 Game Development Kit
(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,其中包含关联 ID。`--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

- [Playtest](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playtest.md)
- [你的第一个游戏测试](https://docs.xbox.com/zh-CN/tools/xbox-cli/first-playtest.md)
- [PlayFab Party SDK](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/networking/party-sdks/overview.md)
- [XPackageKind](https://docs.xbox.com/zh-CN/reference/system/xpackage/enums/xpackagekind.md)
- [XPackageGetMountPathSize](https://docs.xbox.com/zh-CN/reference/system/xpackage/functions/xpackagegetmountpathsize.md)
