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

# 安装

> 下载并安装适用于 Windows、Linux 或 macOS 的 CLI。

在 Windows 上使用 WinGet 安装 XBOX CLI,在 Linux 或 macOS 上使用安装脚本安装,或者在任何平台上从发布存档安装。若要改为从源代码生成,请参阅
[从源代码生成](https://github.com/xbox/cli/blob/v0.4.2/docs/contributing/building-from-source.md)。

## Windows:使用 WinGet 安装

在 Windows 上,使用 Windows 程序包管理器 [WinGet](https://learn.microsoft.com/windows/package-manager/winget/)
安装 CLI:

```powershell theme={null}
winget install xbox
xbox --version
```

WinGet 会将 `xbox` 添加到你的 `PATH`,并且不需要管理员权限。如果安装后终端找不到
`xbox`,请打开新的终端;如果你使用 IDE 的集成终端,请重启 IDE。

若要更新 CLI:

```powershell theme={null}
winget upgrade Microsoft.Gaming.XBOXDeveloperCLI
```

若要删除它:

```powershell theme={null}
winget uninstall Microsoft.Gaming.XBOXDeveloperCLI
```

卸载后,你已保存的设置和登录数据会保留在 `%LOCALAPPDATA%\XboxDevCLI` 中。只能使用 WinGet 更新 WinGet 安装,而不能使用本页中的 ZIP 步骤。请继续执行
[后续步骤](#next-steps)。

## Linux 和 macOS:使用脚本安装

在 Linux x64 或 macOS 上,安装脚本会将最新版本下载到
`~/.local/opt/xboxdevcli`,并在 shell 的启动文件中将该目录添加到你的 `PATH`。
它需要 `curl` 和 `unzip`:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/xbox/cli/main/install.sh | sh
```

该脚本会输出它更改的启动文件。打开新的终端,然后使用
`xbox --version` 检查版本。若要更新 CLI,请再次运行该脚本。若要删除它,请删除
`~/.local/opt/xboxdevcli` 以及脚本添加到该启动文件中的那一行。

## 下载版本

当 WinGet 和安装脚本都不适用时(例如在没有 WinGet 的 Windows 电脑上),请从发布存档安装。

从 [GitHub 发布页面](https://github.com/xbox/cli/releases/latest)下载适用于你的操作系统和 CPU 的存档:

| 平台 | 资产 | 二进制文件 |
| - | - | - |
| Windows x64 | `xbox-win-x64.zip` | `xbox.exe` |
| Linux x64 | `xbox-linux-x64.zip` | `xbox` |
| Apple 芯片上的 macOS | `xbox-osx-arm64.zip` | `xbox` |
| Intel 上的 macOS | `xbox-osx-x64.zip` | `xbox` |

Linux x64 二进制文件需要 glibc 2.27 或更高版本。macOS 二进制文件由 Microsoft 签名并经过 Apple 公证。你无需安装 .NET。

将整个存档解压缩到一个新的独立目录中,并按照适用于你的平台的步骤将该目录添加到你的 `PATH`。如果该目录中已有安装,请改为按照
[更新 ZIP 安装](#update-a-zip-installation)进行操作。

## Windows (PowerShell)

1. 解压缩存档,并检查解压出的可执行文件:

   ```powershell theme={null}
   $cliDir = Join-Path $env:LOCALAPPDATA 'Programs\XboxDevCLI'
   Expand-Archive -LiteralPath "$HOME\Downloads\xbox-win-x64.zip" -DestinationPath $cliDir
   & "$cliDir\xbox.exe" --version
   ```

2. 将该目录添加到你的 `PATH`。从 Windows 搜索中打开**编辑帐户的环境变量**。在**用户变量**下,编辑 **Path**,选择**新建**,然后输入该目录,例如 `C:\Users\<you>\AppData\Local\Programs\XboxDevCLI`。

3. 打开新的终端,然后检查版本:

   ```powershell theme={null}
   xbox --version
   ```

## Linux 和 macOS(Bash 或 Zsh)

1. 解压缩存档,并检查解压出的可执行文件。此示例使用 Linux x64;在
   macOS 上,对于 Apple 芯片,请使用 `xbox-osx-arm64.zip`,对于 Intel,请使用 `xbox-osx-x64.zip`:

   ```bash theme={null}
   cli_dir="$HOME/.local/opt/xboxdevcli"
   mkdir -p "$cli_dir"
   unzip "$HOME/Downloads/xbox-linux-x64.zip" -d "$cli_dir"
   chmod u+x "$cli_dir/xbox"
   "$cli_dir/xbox" --version
   ```

2. 将该目录添加到你的 `PATH`。对于 Zsh(macOS 上的默认 shell),请将此行添加到 `~/.zshrc`;对于 Bash,请将其添加到 `~/.bashrc`:

   ```bash theme={null}
   export PATH="$HOME/.local/opt/xboxdevcli:$PATH"
   ```

3. 打开新的终端,然后检查版本:

   ```bash theme={null}
   xbox --version
   ```

## 验证安装

`xbox --version` 会显示你所下载版本的版本号,不含标记开头的 `v`。
如果显示的是较旧的版本,则说明你的 `PATH` 中有另一个 `xbox` 副本排在前面。请在 PowerShell 中使用
`Get-Command xbox -All`,或在 Bash 或 Zsh 中使用 `type -a xbox` 找到它,然后将其从你的
`PATH` 中删除。

## 检查更新

`xbox upgrade` 会告诉你是否有更新的版本,以及如何安装它。请参阅
[Upgrade](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/upgrade.md)。

```bash theme={null}
xbox upgrade
```

若要更新 WinGet 安装,请运行 `winget upgrade Microsoft.Gaming.XBOXDeveloperCLI`。若要更新脚本安装,请再次运行[安装脚本](#linux-and-macos-install-with-a-script)。若要更新 ZIP 安装,请按照下一节进行操作。

## 更新 ZIP 安装

你已保存的设置和登录数据与安装分开存储,因此会被保留。
请参阅[值的保存位置](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/context.md#where-values-are-saved)。

1. 从 `xbox upgrade` 显示的发布页面或
   [GitHub 发布页面](https://github.com/xbox/cli/releases/latest)下载新版本的存档,并将其解压缩到新目录中。
2. 关闭所有正在运行的 `xbox` 进程。
3. 用新的安装目录替换旧的安装目录(使用相同的路径),或者按照 [Windows (PowerShell)](#windows-powershell) 或
   [Linux 和 macOS(Bash 或 Zsh)](#linux-and-macos-bash-or-zsh)中的说明,将你的 `PATH` 条目更改为新目录。
4. 打开新的终端,然后检查 `xbox --version` 是否显示新版本。

在新版本正常工作之前,请保留旧目录,但将其从你的 `PATH` 中移除。如果你的登录已过期,请再次运行 `xbox auth login`。

## 后续步骤

* [入门](https://docs.xbox.com/zh-CN/tools/xbox-cli/getting-started.md):登录、选择你的 Partner Center 卖家并列出其游戏。
* [命令](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands.md):完整的命令参考。
* [遥测](https://docs.xbox.com/zh-CN/tools/xbox-cli/telemetry.md):CLI 收集的内容以及如何将其关闭。


## Related topics

- [归因安装](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/client/advertising/attribute-install.md)
- [流式安装:状态](https://docs.xbox.com/zh-CN/build/core-features/common/packaging/packaging-installstatus.md)
- [流式安装:调试](https://docs.xbox.com/zh-CN/build/core-features/common/packaging/packaging-debugging.md)
- [流式安装工具](https://docs.xbox.com/zh-CN/build/core-features/common/packaging/deployment/atoc-deployment-tools.md)
- [提取 Microsoft GDK 安装负载](https://docs.xbox.com/zh-CN/build/console-features/build-without-install/extract-setup-payload.md)
