> ## 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、在 Linux 或 macOS 上使用安裝指令碼，或在任何平台上從版本封存安裝 XBOX CLI。若要改為從原始碼建置，請參閱[從原始碼建置](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`，並在殼層的啟動檔案中將該目錄新增至您的 `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 PC 上)，請從版本封存安裝。

從 [GitHub Releases 頁面](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 搜尋開啟 **Edit environment variables for your account**。在 **User variables** 下，編輯 **Path**、選取 **New**，然後輸入目錄，例如 `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 上的預設殼層)，請將此行新增至 `~/.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` 會告訴您是否有較新的版本，以及如何安裝它。請參閱[升級](https://docs.xbox.com/zh-TW/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-TW/tools/xbox-cli/commands/context.md#where-values-are-saved)。

1. 從 `xbox upgrade` 顯示的版本頁面，或從 [GitHub Releases 頁面](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-TW/tools/xbox-cli/getting-started.md)：登入、選擇您的 Partner Center 賣方，並列出其遊戲。
* [命令](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands.md)：完整的命令參考。
* [遙測](https://docs.xbox.com/zh-TW/tools/xbox-cli/telemetry.md)：CLI 收集的內容，以及如何將其關閉。


## Related topics

- [歸因安裝](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/client/advertising/attribute-install.md)
- [串流安裝：狀態](https://docs.xbox.com/zh-TW/build/core-features/common/packaging/packaging-installstatus.md)
- [串流安裝：偵錯](https://docs.xbox.com/zh-TW/build/core-features/common/packaging/packaging-debugging.md)
- [串流安裝工具](https://docs.xbox.com/zh-TW/build/core-features/common/packaging/deployment/atoc-deployment-tools.md)
- [自動安裝 URI (API 內容)](https://docs.xbox.com/zh-TW/reference/deviceportal/unattendedsetup/atoc-rest-unattendedsetup.md)
