# 如何安裝 Qwen Code CLI：終端機 AI 程式碼代理逐步教學

學習如何在終端機安裝開源 AI 程式碼代理 Qwen Code CLI。提供 npm、快速安裝腳本、Homebrew 以及在 Windows、macOS 和 Linux 上的故障排除逐步說明。

Canonical URL: https://a2a-mcp.org/blog/qwen-cli-install-zh-TW

Language: zh-TW

Published: 2026-04-07

Updated: 2026-04-07

## 前置要求

在安裝 **Qwen Code CLI**（官方基於 Qwen 模型的終端型 AI 編碼助手）之前，請確保滿足以下條件：

- **Node.js** 版本 20 或更高（建議：最新的 LTS 版本）。從 [nodejs.org](https://nodejs.org) 下載。
- Windows 上具有管理員權限的終端機或命令提示字元。
- 網路連線，用於下載套件和模型。
- 可選但建議：Git（用於手動原始碼安裝）以及 macOS/Linux 上的 Homebrew。

**驗證 Node.js 安裝**：

```bash
node --version
npm --version
```

預期輸出會顯示如 `v20.x.x` 或更高的版本號。

## 步驟 1：選擇您的安裝方式

Qwen Code CLI 提供多種安裝途徑。對於大多數使用者，**快速安裝腳本**是推薦選項，它能自動處理相依項目。

### 快速安裝（推薦）

**Linux / macOS**：

```bash
bash -c "$(curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh)"
```

**Windows（以管理員身份執行命令提示字元）**：

```cmd
curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat
```

執行後，重新啟動您的終端機以更新 PATH。

## 步驟 2：透過 npm 手動安裝

如果您偏好手動控制：

```bash
npm install -g @qwen-code/qwen-code@latest
```

這會全域安裝 `qwen` 指令。

**在 macOS/Linux 上使用 sudo**（若出現權限問題）：

```bash
sudo npm install -g @qwen-code/qwen-code@latest
```

## 步驟 3：透過 Homebrew 安裝（macOS & Linux）

```bash
brew install qwen-code
```

## 步驟 4：驗證安裝

執行以下指令以確認安裝成功：

```bash
qwen --version
```

您應該會看到類似以下的輸出：

```
Qwen Code CLI v0.x.x
```

## 步驟 5：首次啟動與驗證

啟動互動式 CLI：

```bash
qwen
```

首次執行時，CLI 會提示您使用 Qwen 帳號進行驗證（將開啟瀏覽器進行一鍵登入）。登入後，它會套用預設設定並進入互動式終端機 UI。

為獲得最佳效果，請先導航至您的專案目錄：

```bash
cd /path/to/your/project
qwen
```

在會話中，使用如 `/help`、`/model` 等指令來切換模型，或透過 `@filename` 來參照檔案。

## 步驟 6：從原始碼手動安裝（進階）

適用於希望取得最新未發布更改的開發者：

```bash
git clone https://github.com/QwenLM/qwen-code.git
cd qwen-code
npm install
npm install -g .
```

然後使用 `qwen --version` 進行驗證。

## 常見問題與疑難排解

- **找不到 'qwen' 指令**：重新開啟終端機或執行 `hash -r`（Linux/macOS）。在 Windows 上，請關閉並重新開啟命令提示字元。請確認 Node.js 全域 bin 目錄已在您的 PATH 環境變數中。

- **npm install 過程出現權限錯誤**：在 Linux/macOS 上使用 `sudo`，或在 Windows 上以系統管理員身份執行命令提示字元。

- **Node.js 版本太舊**：使用 `nvm` 或官方安裝程式升級至 Node 20+。

- **阿里雲資產下載出現網路問題**：可嘗試使用 npm 安裝方法作為備用方案。

- **在 Termux 或某些 Linux 發行版上安裝失敗**：使用 `--ignore-scripts` 標誌：`npm install -g @qwen-code/qwen-code@latest --ignore-scripts`。

- **驗證功能無法運作**：請確認您的瀏覽器允許彈出視窗，且您擁有有效的 Qwen 帳號。

若問題持續存在，請查看官方 GitHub 儲存庫：https://github.com/QwenLM/qwen-code。

## 下一步

- **探索互動式 UI**：輸入 `/help` 以查看可用的斜線指令。
- **嘗試代理式編碼**：要求 CLI 使用自然語言重構程式碼、解釋檔案或自動化任務。
- **設定模型**：使用 `/model` 來選擇 Qwen3-Coder 或其他支援的後端（包括本地的 Ollama）。
- **整合 VS Code**：安裝 Qwen Code Companion 擴充功能以實現無縫的編輯器整合。
- **自訂設定**：編輯 `~/.qwen/settings.json` 以調整主題、預設模型和進階選項。

現在您已準備好在終端機中直接使用 Qwen Code CLI 作為強大的 AI 配對程式設計師。請在您的專案資料夾內，從簡單的提示開始，例如「解釋這個程式碼庫」或「重構這個函式以提升效能」。

祝您編碼愉快！