> ## 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 CLI 最新版本中的問題和尚未完成的功能，以及如何因應。

此頁面列出 XBOX CLI 最新版本中的已知問題，包括尚未完成的功能。如果您的問題已列於此處，就不需要回報。

只支援最新版本。[`xbox upgrade`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/upgrade) 會告訴您是否有較新的版本可用。標示為**已修正**的項目已在最新版本中修正，並會在下一個版本中移除。

## 如果您的問題未列出

1. 使用 [`xbox upgrade`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/upgrade) 確認您執行的是最新版本。
2. 搜尋[現有的問題](https://github.com/xbox/cli/issues)。
3. 如果尚未有人回報，請使用 [`xbox feedback`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/feedback) 回報，它會開啟已填入您環境詳細資料的錯誤報告。問題是公開的，因此請省略您不願公開分享的任何內容。

## 更新 CLI

### `xbox upgrade` 失敗並顯示 HTTP 301

**已修正**

CLI 的公用存放庫已移動，而 v0.2.1 中的 [`xbox upgrade`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/upgrade) 每次都會失敗並顯示 `HTTP 301: GitHub release metadata is unavailable`。

\*\*因應措施：\*\*依照[安裝](https://docs.xbox.com/zh-TW/tools/xbox-cli/installation.md)下載最新版本。

## 登入和權限

### 有些命令尚無法搭配個人 Microsoft 帳戶使用

當您使用個人 Microsoft 帳戶而非公司或學校帳戶登入時，XBOX services 組態、測試帳戶、套件、試玩測試和對象的命令無法運作。XBOX services 組態和測試帳戶命令會失敗並顯示 HTTP 502，回報為服務無法使用，但重試並沒有幫助。

\*\*因應措施：\*\*使用公司或學校帳戶在 Partner Center 中加入您的賣方，並使用該帳戶登入 CLI。

### `xbox game`、`xbox xbl` 和類似命令尚不接受服務主體

服務主體可以登入，但由它執行 `audience`、`game`、`package`、`playtest`、`sandbox`、`seller`、`test-account` 和 `xbl` 命令時，這些命令會因授權錯誤而失敗，因為它們所呼叫的服務尚不接受服務主體。

\*\*因應措施：\*\*以已登入的使用者身分執行這些命令。在有人使用 [`xbox playfab service-principal set`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/service-principal) 授與服務主體存取權後，`xbox playfab` 命令即可搭配服務主體使用。請參閱[自動化 (服務主體) 驗證](https://docs.xbox.com/zh-TW/tools/xbox-cli/authentication.md#automation-service-principal-authentication)。

### 當您屬於多個賣方時，某些賣方的命令會遭到拒絕

如果您屬於多個 Partner Center 賣方，除了您最後在 Partner Center 中選取的賣方以外，其他每個賣方的 XBOX services 組態、測試帳戶、套件、試玩測試和對象命令都可能遭到拒絕。

\*\*因應措施：\*\*在 Partner Center 中選取您要的賣方，然後再次執行命令。

### `xbox seller list` 有時會遺漏您的其中一個賣方

如果您屬於多個 Partner Center 賣方，[`xbox seller list`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/seller) 有時會在沒有錯誤的情況下遺漏其中一個，而下一次執行可能會列出它。在它遺漏期間，該賣方的命令 (例如 [`xbox audience list`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/audience)) 可能會遭到拒絕，而目前並不知道在 Partner Center 中選取它是否有幫助。

### `xbox game` 命令會忽略 `--seller-id`

[`xbox game list`、`xbox game get` 和 `xbox game create`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/game) 會使用您最後在 Partner Center 中選取的賣方，而不是您以 `--seller-id` 傳遞或儲存在[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)中的賣方，因此 `game create` 可能會在其他賣方中建立遊戲。不屬於您的賣方 ID (例如輸入錯誤的 ID) 不會使它們失敗；它們會傳回您自己的遊戲。

\*\*因應措施：\*\*在 Partner Center 中選取您要的賣方，然後在建立遊戲之前，先確認 `xbox game list` 顯示的是該賣方的遊戲。此變更最多可能需要 15 分鐘才會反映到 CLI。

### `xbox sandbox` 命令只會顯示全域沙箱

當您以 `--seller-id` 傳遞或儲存在[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)中的賣方，不是您最後在 Partner Center 中選取的賣方時，[`xbox sandbox list` 和 `xbox sandbox get`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/sandbox) 只會找到 `CERT`、`CERT.DEBUG` 和 `RETAIL` 沙箱，而不會失敗。`xbox sandbox create` 會在您最後選取的賣方中建立沙箱，而如果那是其他賣方，它會以 `4` 結束，因為它無法讀回該沙箱。請勿再次建立它。

\*\*因應措施：\*\*在 Partner Center 中選取您要的賣方，然後使用該賣方再次執行命令。此變更最多可能需要 15 分鐘才會反映到 CLI。

## 使用試玩測試和對象進行測試

### `xbox audience list` 可能會逾時

[`xbox audience list`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/audience) 可能會花費過長的時間，導致要求逾時。`--name` 沒有幫助，因為它是在讀取每個對象之後才篩選清單。

## XBOX services 組態

### 某些下載的 XML 文件宣告了錯誤的編碼

[`xbox xbl config download --view published`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/xbl) 所儲存的某些已發佈 XML 文件 (例如 `mpsdtitleinfo.xml` 和 `titlename-localization.xml`) 宣告了 `encoding="utf-16"`，但實際上是以 UTF-8 編碼，因此信任該宣告的 XML 讀取器會無法載入它們。

\*\*因應措施：\*\*在剖析檔案之前，先將其解碼為 UTF-8。

## PlayFab

### `xbox playfab api /Admin/UpdatePolicy` 可能會在未確認的情況下覆寫原則

當要求本文中有 `"OverwritePolicy": true` 時，此呼叫會取代遊戲的整個 API 存取原則，而沒有 `xbox playfab api-policy set --overwrite` 的保護措施：它不需要 `--confirm`，而且可以使用已儲存內容或 `XBOX_PLAYFAB_TITLE_ID` 中的遊戲。錯誤的原則可能會將所有玩家鎖定在遊戲之外。

\*\*因應措施：\*\*改用 [`xbox playfab api-policy set --overwrite`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/api-policy)，它需要 `--confirm`，以及以 `--playfab-title-id` 傳遞的遊戲。

### `playfab title-data delete` 和 `playfab player-data delete` 不會先詢問

其他會刪除內容的命令在執行之前會先詢問，或在沒有 `--confirm` 時拒絕執行。這兩個命令會立即刪除您指定的索引鍵。

### `--keys` 和 `--member-ids` 採用以逗號分隔的清單

`xbox playfab title-data` 和 `xbox playfab player-data` 上的 `--keys`，以及 [`xbox playfab group member`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/group) 上的 `--member-ids`，採用以逗號分隔的清單。它們將會變更為可重複的選項，因此使用它們的指令碼將需要更新。

在那之前，`--keys` 無法指定包含逗號的索引鍵。若要讀取這類索引鍵，請使用 `--key` 傳遞它，此選項會將名稱視為一個整體，但 `delete` 只有 `--keys`。

\*\*因應措施：\*\*若要刪除該索引鍵，請使用 [`xbox playfab api`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/api) 呼叫 `delete` 所使用的 API。若為遊戲資料，請將索引鍵的值設定為 `null`；若為內部遊戲資料，則改用 `/Admin/SetTitleInternalData`：

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/SetTitleData --body '{"Key":"Level,Bonus","Value":null}'
```

若為玩家資料，請在 `KeysToRemove` 中列出索引鍵，並使用[玩家資料](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/player-data.md)中適用於該資料可見度的更新 API：

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/UpdateUserData --body '{"PlayFabId":"PLAYER123","KeysToRemove":["Level,Bonus"]}'
```

## 指令碼和代理程式

### 當無法得知變更是否完成時，大多數命令會以 1 結束

少數命令在無法判斷是否已進行變更時 (例如要求在傳送後逾時)，會以 `3` 結束，其頁面會加以說明。其他所有命令 (包括每個 PlayFab 命令) 在任何失敗時都會以 `1` 結束，因此指令碼無法區分這種情況與未進行變更的情況。

\*\*因應措施：\*\*當會變更內容的命令失敗時，請在再次執行之前先檢查目前的狀態。


## Related topics

- [開始使用 Unity 進行 PC 開發 (內容)](https://docs.xbox.com/zh-TW/build/gdk-and-engines/unity/unity.md)
- [版本資訊 - XBOX PC 遠端工具 (2026 年 3 月)](https://docs.xbox.com/zh-TW/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md)
- [使用 Playtest](https://docs.xbox.com/zh-TW/publishing/game-publishing/concepts/playtest-preview.md)
- [Visual Studio 2019 GDK 支援注意事項](https://docs.xbox.com/zh-TW/tools/tools-console/visualstudio/vs-2019-support-notes.md)
- [XBOX PC Remote Tools 常見問題集和疑難排解指南](https://docs.xbox.com/zh-TW/tools/tools-pc/xbox-pc-remote-tools/faq.md)
