跳转到主要内容
XBOX CLI 不需要配置文件。其设置来自内置于可执行文件中的默认值,你可以使用环境变量针对某个 shell 覆盖这些设置,或使用选项针对单个命令进行覆盖。

配置源和优先级

设置来自三个源,后面的源会覆盖前面的源:
  1. 内置默认值,编译到可执行文件中。请参阅设置。
  2. 环境变量。请参阅环境变量。
  3. 命令行选项。请参阅CLI 选项覆盖。
新版本会带来自己的默认值,因此无需沿用任何设置文件。 卖家、PlayFab 游戏、XBOX 游戏和沙盒不是设置;有关命令从何处获取它们,请参阅 上下文。

设置

  • AzureAd:* 用于配置用户登录;请参阅身份验证。
  • PlayFab:StudioBaseUrl 是用于工作室 API (/Studio/*) 的 PlayFab 终结点,例如 playfab service-principal 调用的那些 API。
  • XboxPartner:TimeoutSeconds 是 game 等命令的请求超时(以秒为单位),必须为正数。
  • XblPCSandbox:Path 是 pc sandbox 命令运行的 XblPCSandbox.exe。如果未设置,CLI 会先在其自身目录中查找,然后在 PATH 中查找。
  • AuditLog:Enabled 用于启用审核日志。
  • Telemetry:* 在遥测中进行了介绍。
当 PlayFab:BaseUrlTemplate、PlayFab:StudioBaseUrl 或 XboxPartner:BaseUrl 不是内置默认值时,每个向该终结点发送令牌的命令都会先向 stderr 写入警告。

环境变量

设置的变量由 XBOX_ 加上其键组成,并用 __(两个下划线)替换每个 :, 因此 Telemetry:Enabled 对应 XBOX_TELEMETRY__ENABLED。名称请使用大写字母。变量适用于设置它的 shell 以及该 shell 启动的每个命令:
设置中的每个设置都有对应的变量。CLI 还会读取以下变量: XBOX_AUTHENTICATION__ 设置仅从环境变量中读取,从不从内置默认值或选项中读取。请参阅 自动化(服务主体)身份验证。

CLI 选项覆盖

对于单个命令,选项会覆盖其他所有源。 有关其他全局选项,请参阅命令。

遥测配置

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

从读取 appsettings.json 的版本升级

早期版本会从可执行文件旁边读取 appsettings.json。如果你更改了其中的值,请改为设置其 XBOX_ 变量:例如,"AzureAd": { "ClientId": "..." } 对应 XBOX_AZUREAD__CLIENTID。在完成迁移之前,你可能会看到以下消息:
  • --config-env 会失败并显示此错误。请删除该选项,并改为设置 XBOX_ 变量。
  • 当可执行文件旁边存在 appsettings*.json 文件时,命令会将此说明写入 stderr。请删除该文件。
  • 如果之前的错误消息引导你设置了 XBOX_PLAYFAB__REQUESTHEADERS__0__VALUE,PlayFab 命令会失败,并显示指明该变量的错误。请删除该变量。
最后修改于 2026年11月19日