# 如何安装Qwen Code CLI：终端AI编码助手一步步教程

学习如何安装Qwen Code CLI，这款为终端设计的开源AI编码助手。提供Windows、macOS和Linux系统下通过npm、快速安装脚本、Homebrew等方式的分步教程及故障排除指引。

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

Language: zh

Published: 2026-04-07

Updated: 2026-04-07

## 前置条件

在安装 **Qwen Code CLI**（由通义千问模型提供支持的官方终端 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 账户进行身份验证（会打开浏览器进行一键登录）。登录后，它会应用默认设置并进入交互式终端界面。

为了获得最佳效果，请先导航到您的项目目录：

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

在会话中，使用 `/help`、`/model` 等命令来切换模型，或使用 `@文件名` 来引用文件。

## 步骤 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 结对编程助手。在项目文件夹内，可尝试简单提示，如“解释这个代码库”或“重构此函数以提升性能”。

编码愉快！