> ## 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 不需要配置文件。其设置来自内置于可执行文件中的默认值,你可以使用环境变量针对某个 shell 覆盖这些设置,或使用选项针对单个命令进行覆盖。

## 配置源和优先级

设置来自三个源,后面的源会覆盖前面的源:

1. 内置默认值,编译到可执行文件中。请参阅[设置](#settings)。
2. 环境变量。请参阅[环境变量](#environment-variables)。
3. 命令行选项。请参阅[CLI 选项覆盖](#cli-option-overrides)。

新版本会带来自己的默认值,因此无需沿用任何设置文件。

卖家、PlayFab 游戏、XBOX 游戏和沙盒不是设置;有关命令从何处获取它们,请参阅
[上下文](https://docs.xbox.com/zh-CN/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-CN/tools/xbox-cli/authentication.md#overriding-entra-id-settings)。
* `PlayFab:StudioBaseUrl` 是用于工作室 API (`/Studio/*`) 的 PlayFab 终结点,例如
  [`playfab service-principal`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/service-principal) 调用的那些 API。
* `XboxPartner:TimeoutSeconds` 是 [`game`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/game) 等命令的请求超时(以秒为单位),必须为正数。
* `XblPCSandbox:Path` 是 [`pc sandbox`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/pc)
  命令运行的 `XblPCSandbox.exe`。如果未设置,CLI 会先在其自身目录中查找,然后在 `PATH` 中查找。
* `AuditLog:Enabled` 用于启用[审核日志](https://docs.xbox.com/zh-CN/tools/xbox-cli/audit-log.md)。
* `Telemetry:*` 在[遥测](https://docs.xbox.com/zh-CN/tools/xbox-cli/telemetry.md)中进行了介绍。

当 `PlayFab:BaseUrlTemplate`、`PlayFab:StudioBaseUrl` 或 `XboxPartner:BaseUrl` 不是内置默认值时,每个向该终结点发送令牌的命令都会先向 stderr 写入警告。

## 环境变量

设置的变量由 `XBOX_` 加上其键组成,并用 `__`(两个下划线)替换每个 `:`,
因此 `Telemetry:Enabled` 对应 `XBOX_TELEMETRY__ENABLED`。名称请使用大写字母。变量适用于设置它的 shell 以及该 shell 启动的每个命令:

```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-CN/tools/xbox-cli/commands/context.md) |
| `XBOX_PROFILE` | 未传递 `--profile` 时,已保存值所来自的[配置文件](https://docs.xbox.com/zh-CN/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-CN/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-CN/tools/xbox-cli/commands/game) 和 [`seller`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/seller) |
| `--disable-telemetry` | 为此命令设置 `Telemetry:Enabled=false` |

有关其他全局选项,请参阅[命令](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands.md)。

## 遥测配置

除非你将其关闭,否则正式版本会收集有限的匿名遥测数据。若要针对单个命令关闭遥测:

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

若要针对某个 shell 关闭遥测:

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

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

有关收集的内容,请参阅[遥测](https://docs.xbox.com/zh-CN/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-CN/services/xbox-services/multiplayer/matchmaking/config/index.md)
- [HTTP 配置](https://docs.xbox.com/zh-CN/services/playfab/sdks/c/http-config.md)
- [门户配置](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/portal-config/index.md)
- [配置 XBOX 服务](https://docs.xbox.com/zh-CN/publishing/game-publishing/concepts/xbox-services.md)
- [分段配置](https://docs.xbox.com/zh-CN/services/playfab/live-service-management/game-configuration/segmentation/segmentation-configuration.md)
