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

# 組態

> CLI 如何從其內建預設值、環境變數和命令列選項分層套用設定。

XBOX CLI 不需要組態檔。其設定來自內建於可執行檔中的預設值，您可以使用環境變數針對殼層進行覆寫，或使用選項針對單一命令進行覆寫。

## 組態來源和優先順序

設定來自三個來源，後面的來源會覆寫前面的來源：

1. 編譯到可執行檔中的內建預設值。請參閱[設定](#settings)。
2. 環境變數。請參閱[環境變數](#environment-variables)。
3. 命令列選項。請參閱[CLI 選項覆寫](#cli-option-overrides)。

新版本會帶有自己的預設值，因此沒有需要沿用的設定檔。

賣方、PlayFab 遊戲、XBOX 遊戲和沙箱不是設定；如需命令從何處取得這些值，請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md)。

## 設定

| 索引鍵 | 環境變數 | 選項 | 內建預設值 |
| - | - | - | - |
| `AzureAd:ClientId` | `XBOX_AZUREAD__CLIENTID` | `--client-id` | CLI 本身的 Microsoft Entra ID 應用程式 |
| `AzureAd:TenantId` | `XBOX_AZUREAD__TENANTID` | `--tenant-id` | `common` |
| `AzureAd:Scopes` | `XBOX_AZUREAD__SCOPES` | `--scopes` | 內建 |
| `PlayFab:BaseUrlTemplate` | `XBOX_PLAYFAB__BASEURLTEMPLATE` | 無 | 內建 |
| `PlayFab:StudioBaseUrl` | `XBOX_PLAYFAB__STUDIOBASEURL` | 無 | 內建 |
| `PlayFab:MaxRequestBodyBytes` | `XBOX_PLAYFAB__MAXREQUESTBODYBYTES` | 無 | `1048576` (1 MiB) |
| `PlayFab:MaxResponseBytes` | `XBOX_PLAYFAB__MAXRESPONSEBYTES` | 無 | `4194304` (4 MiB) |
| `XboxPartner:BaseUrl` | `XBOX_XBOXPARTNER__BASEURL` | `--base-url`，適用於接受此選項的命令 | 內建 |
| `XboxPartner:TimeoutSeconds` | `XBOX_XBOXPARTNER__TIMEOUTSECONDS` | 無 | `120` |
| `XblPCSandbox:Path` | `XBOX_XBLPCSANDBOX__PATH` | 無 | 未設定 |
| `AuditLog:Enabled` | `XBOX_AUDITLOG__ENABLED` | 無 | `false` |
| `Telemetry:Enabled` | `XBOX_TELEMETRY__ENABLED` | `--disable-telemetry` 會設定為 `false` | `true` |

* `AzureAd:*` 用於設定使用者登入；請參閱[驗證](https://docs.xbox.com/zh-TW/tools/xbox-cli/authentication.md#overriding-entra-id-settings)。
* `PlayFab:StudioBaseUrl` 是 Studio API (`/Studio/*`) 的 PlayFab 端點，例如 [`playfab service-principal`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/service-principal) 所呼叫的 API。
* `XboxPartner:TimeoutSeconds` 是 [`game`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/game) 等命令的要求逾時 (以秒為單位)，且必須是正數。
* `XblPCSandbox:Path` 是 [`pc sandbox`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/pc) 命令所執行的 `XblPCSandbox.exe`。未設定時，CLI 會先在其本身的目錄中尋找，然後在 `PATH` 中尋找。
* `AuditLog:Enabled` 會開啟[稽核記錄](https://docs.xbox.com/zh-TW/tools/xbox-cli/audit-log.md)。
* `Telemetry:*` 的說明請參閱[遙測](https://docs.xbox.com/zh-TW/tools/xbox-cli/telemetry.md)。

當 `PlayFab:BaseUrlTemplate`、`PlayFab:StudioBaseUrl` 或 `XboxPartner:BaseUrl` 不是內建預設值時，每個將權杖傳送至該端點的命令都會先將警告寫入 stderr。

## 環境變數

設定的變數是 `XBOX_` 加上其索引鍵，並以 `__` (兩個底線) 取代每個 `:`，因此 `Telemetry:Enabled` 為 `XBOX_TELEMETRY__ENABLED`。名稱請以大寫撰寫。變數會套用至設定它的殼層，以及該殼層啟動的每個命令：

```bash theme={null}
# Linux / macOS
export XBOX_XBOXPARTNER__TIMEOUTSECONDS=300
xbox game list
```

```powershell theme={null}
# Windows PowerShell
$env:XBOX_XBOXPARTNER__TIMEOUTSECONDS = "300"
xbox game list
```

[設定](#settings)中的每個設定都有變數。CLI 也會讀取下列變數：

| 環境變數 | 用途 |
| - | - |
| `XBOX_PLAYFAB_TITLE_ID`、`XBOX_SELLER_ID`、`XBOX_SANDBOX_ID`、`XBOX_TITLE_ID` | 內容值；請參閱[內容](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md) |
| `XBOX_PROFILE` | 未傳遞 `--profile` 時，已儲存值所來自的[設定檔](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/context.md#profiles) |
| `XBOX_TELEMETRY_OPTOUT` | 設定為 `1`、`true` 或 `yes` 時關閉遙測 |
| `XBOX_AUTHENTICATION__MODE` 和其他 `XBOX_AUTHENTICATION__` 變數 | 服務主體登入 |

`XBOX_AUTHENTICATION__` 設定只會從環境變數讀取，絕不會從內建預設值或選項讀取。請參閱[自動化 (服務主體) 驗證](https://docs.xbox.com/zh-TW/tools/xbox-cli/authentication.md#automation-service-principal-authentication)。

## CLI 選項覆寫

選項會針對單一命令覆寫其他所有來源。

| 選項 | 組態索引鍵或行為 |
| - | - |
| `--client-id` | 使用者登入的 `AzureAd:ClientId`；在服務主體模式中會被拒絕 |
| `--tenant-id` | 使用者登入的 `AzureAd:TenantId`；在服務主體模式中會被拒絕 |
| `--scopes` | `AzureAd:Scopes` |
| `--base-url` | `XboxPartner:BaseUrl`，適用於接受此選項的命令，例如 [`game`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/game) 和 [`seller`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/seller) |
| `--disable-telemetry` | 為此命令設定 `Telemetry:Enabled=false` |

如需其他全域選項，請參閱[命令](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands.md)。

## 遙測組態

除非您將其關閉，否則正式版本會收集有限的匿名遙測。若要針對單一命令關閉：

```bash theme={null}
xbox --disable-telemetry auth status
```

若要針對殼層關閉：

```bash theme={null}
export XBOX_TELEMETRY_OPTOUT=1
```

```powershell theme={null}
$env:XBOX_TELEMETRY_OPTOUT = "1"
```

如需收集的內容，請參閱[遙測](https://docs.xbox.com/zh-TW/tools/xbox-cli/telemetry.md)。

## 從讀取 appsettings.json 的版本升級

較早的版本會從可執行檔旁邊讀取 `appsettings.json`。如果您曾變更其中的值，請改為設定其 `XBOX_` 變數：例如，`"AzureAd": { "ClientId": "..." }` 會變成 `XBOX_AZUREAD__CLIENTID`。在您完成之前，可能會看到下列訊息：

* `--config-env` 會失敗並顯示此錯誤。請移除此選項，並改為設定 `XBOX_` 變數。

  ```text theme={null}
  --config-env is no longer supported because settings files are no longer read. Set XBOX_ environment variables instead, such as XBOX_AZUREAD__CLIENTID.
  ```

* 當可執行檔旁邊有 `appsettings*.json` 檔案時，命令會將此附註寫入 stderr。請刪除該檔案。

  ```text theme={null}
  Note: '<file>' is no longer read. Settings come from the built-in defaults, XBOX_ environment variables, and command options. Delete the file to hide this note.
  ```

* 如果先前的錯誤訊息導致您設定了 `XBOX_PLAYFAB__REQUESTHEADERS__0__VALUE`，PlayFab 命令會失敗並顯示指出該變數名稱的錯誤。請移除該變數。


## Related topics

- [在單一部署中啟用多個建置組態](https://docs.xbox.com/zh-TW/tools/tools-console/visualstudio/multiple-build-configurations.md)
- [內容測試應用程式 (CTA) 串流組態](https://docs.xbox.com/zh-TW/build/core-features/common/game-streaming/game-streaming-content-test-application-stream-config.md)
- [在試玩測試中使用 XBOX services](https://docs.xbox.com/zh-TW/tools/xbox-cli/xbox-services-in-a-playtest.md)
- [GetAllSettings](https://docs.xbox.com/zh-TW/reference/tools/xtf/xtfconsolecontrol/interfaces/IXtfConsoleControlClient/methods/ixtfconsolecontrolclient_getallsettings.md)
- [GetConfigValue](https://docs.xbox.com/zh-TW/reference/tools/xtf/xtfconsolecontrol/interfaces/IXtfConsoleControlClient/methods/ixtfconsolecontrolclient_getconfigvalue.md)
