> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装与升级

## 环境要求

安装 Qoder CLI CN 前，请确认你的环境满足以下要求：

- **操作系统**：macOS、Linux、Windows（推荐使用 Windows Terminal）。
- **CPU 架构**：arm64、amd64。
- **Node.js**：仅旧版 npm 安装方式需要 Node.js >= 20.18.1。

> Windows (arm64) 暂时不支持。

## 安装

新安装请使用安装脚本。它会安装原生独立可执行文件，尤其在 Windows 上可获得更好的启动和运行性能。

### 使用安装脚本（推荐）

安装脚本会根据操作系统和 CPU 架构自动选择兼容的原生版本，完成下载并配置可执行文件。

**macOS / Linux**

```shell
curl -fsSL https://static.qoder.com.cn/qoder-cli-cn/install.sh | bash
```

**Windows PowerShell**

```shell
irm https://static.qoder.com.cn/qoder-cli-cn/install.ps1 | iex
```

**Windows CMD**

```shell
curl -fsSL https://static.qoder.com.cn/qoder-cli-cn/install.cmd -o install.cmd && install.cmd
```

### 使用 npm 安装（不推荐新安装使用）

npm 包通过 Node.js 运行 JavaScript bundle，不使用原生独立运行时，因此启动和运行性能可能较低，在 Windows 上尤其明显。该方式仅为兼容现有环境而保留；新安装请使用安装脚本。

如果仍需使用 npm 兼容方式，请先安装 Node.js >= 20.18.1，再运行：

```shell
npm install -g @qodercn-ai/qoderclicn
```

## 验证安装

安装完成后，运行下列命令。如果打印出 CLI 版本号，则表示安装成功：

```shell
qodercn --version
```

如果提示找不到命令，请检查安装目录是否已加入系统 `PATH`。相关排查步骤见 [安装与升级问题](/cli/troubleshoot-install)。

## 首次运行

在任意项目根目录运行以下命令，即可进入默认的交互式（TUI）模式：

```shell
qodercn
```

首次运行时，Qoder CLI CN 会引导你完成登录。登录方式详见 [登录与认证](/cli/authentication)。

## 升级

Qoder CLI CN 默认启用自动升级。你也可以随时手动升级到最新版本。

### 使用安装脚本升级

**macOS / Linux**

```shell
curl -fsSL https://static.qoder.com.cn/qoder-cli-cn/install.sh | bash -s -- --force
```

**Windows PowerShell**

```shell
irm https://static.qoder.com.cn/qoder-cli-cn/install.ps1 | iex
```

**Windows CMD**

```shell
curl -fsSL https://static.qoder.com.cn/qoder-cli-cn/install.cmd -o install.cmd && install.cmd
```

### 使用内置更新命令

```shell
qodercn update
```

### 升级已有的 npm 安装

已有 npm 安装在迁移到推荐的安装脚本前，可以继续使用以下命令升级：

```shell
npm install -g @qodercn-ai/qoderclicn@latest
```

## 自动升级设置

自动升级默认开启。要禁用自动升级，在 `~/.qoder-cn/settings.json` 中把 `general.enableAutoUpdate` 设置为 `false`：

```json
{
  "general": {
    "enableAutoUpdate": false
  }
}
```

配置文件的作用范围和生效顺序，见 [配置文件与生效顺序](/cli/settings)。

## 卸载

卸载方式取决于你的安装方式：

- **通过 npm 安装**：执行 `npm uninstall -g @qodercn-ai/qoderclicn`。
- **通过安装脚本安装**：删除安装脚本放置的可执行文件，并从 `PATH` 中移除对应目录。

如果你希望同时清理配置和本地数据，可以删除配置目录（默认 `~/.qoder-cn`）。删除前请确认其中没有需要保留的会话、记忆或设置。

> 配置目录位置可以通过 `QODERCN_CONFIG_DIR` 环境变量自定义，默认是 `~/.qoder-cn`。如果你设置过该变量，请删除对应目录。