---
title: "安装和更新 Claude Code"
description: "Claude Code 安装不要只复制一条命令。先选原生安装器、Homebrew、WinGet 或 Linux 包管理器，再验证 PATH、doctor 和更新策略。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

安装 Claude Code 最容易出错的地方，不是命令本身，而是选错了安装通道。官方当前优先推荐原生安装器（native installer）；Homebrew、WinGet、apt、dnf、apk 也能用，但更新策略不同。——Aaron

> [!NOTE]
> **这一章用 12 分钟换什么**：上一章先讲 Claude Code 是什么。这一章只解决一件事：怎么把它正确装到本机，并确认以后能更新、能被 PATH 找到、能跑健康检查。

## 1. 先选安装通道，不要先复制命令

新手看到安装文档，通常第一反应是找一条命令复制。

这会带来两个问题：

- 在 PowerShell 里复制了 CMD 命令。
- 用 Homebrew 装完后，以为它会自动更新。

所以先问自己：你要的是官方推荐的自动更新，还是系统包管理器统一管理？

| 安装通道 | 适合谁 | 自动更新 |
|------|------|------|
| 原生安装器（Native installer） | 大多数个人用户和新手 | 是 |
| Homebrew | macOS 用户统一用 brew 管工具 | 默认否，可选择启用 |
| WinGet | Windows 用户统一用 winget 管工具 | 默认否，可选择启用 |
| apt / dnf / apk | Linux 用户统一用系统包管理器 | 否 |
| npm | 旧方式或特殊环境兜底 | 不推荐作为首选 |

官方 [Advanced setup](https://code.claude.com/docs/en/setup) 现在明确写到：Homebrew、WinGet、apt、dnf、apk 安装默认不会自动更新。要拿到新功能和安全修复，需要手动升级；Homebrew 和 WinGet 可以通过 `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1` 选择让 Claude Code 后台升级自身，Linux 包管理器仍需要手动升级。

> [!IMPORTANT]
> **一句话选择**：不知道选什么，就用原生安装器；已经有严格包管理习惯，再用 Homebrew、WinGet 或 Linux 包管理器。

把选择压成一张移动端也能读的判断表：

| 你的情况 | 推荐通道 |
|------|------|
| 不确定怎么选，想省心自动更新 | 原生安装器 |
| macOS 上所有开发工具都走 Homebrew | Homebrew |
| Windows 上统一用 WinGet 管软件 | WinGet |
| Linux 机器要求走系统 repo | apt / dnf / apk |
| 旧环境、特殊约束、临时兜底 | npm，但不作为新手首选 |

## 2. 先看系统要求

官方 setup 文档列出的基础要求可以压成这张表：

| 类型 | 要求 |
|------|------|
| macOS | macOS 13.0+ |
| Windows | Windows 10 1809+ 或 Windows Server 2019+ |
| Linux | Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+ |
| 架构 | x64 或 ARM64 |
| 内存 | 4 GB+ |
| Shell | Bash、Zsh、PowerShell 或 CMD |
| 网络 | 能访问互联网 |
| 地区 | 位于 Anthropic 支持的国家或地区 |

还有两个新手容易忽略的点：

- Windows 原生环境推荐安装 Git for Windows，这样 Claude Code 可以使用 Bash tool；没有 Git Bash 时会回退到 PowerShell。
- WSL 2 适合 Linux 工具链和 sandboxed command execution；Native Windows 不支持 sandboxing。

> [!TIP]
> 系统要求基线会随官方支持矩阵缓慢上调。本表是当前抓取的版本下限，**安装前请对照官方 [Advanced setup § System requirements](https://code.claude.com/docs/en/setup#system-requirements) 当前页**确认你的系统是否在支持范围内。

> [!WARNING]
> **不要跨环境安装**：项目在 WSL 文件系统里，就在 WSL 终端里安装和运行 `claude`；项目在 Windows 原生路径里，就用 Windows 原生入口。不要在 PowerShell 里装完后跨去操作 WSL 项目。

## 3. 原生安装器：官方推荐首选

macOS、Linux、WSL 用这条：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Windows PowerShell 用这条：

```powershell
irm https://claude.ai/install.ps1 | iex
```

Windows CMD 用这条：

```batch
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

如果你不熟终端，先看命令提示符：

| 你看到的提示符 | 该用哪条 |
|------|------|
| `$` 或 `%` | macOS / Linux / WSL 命令 |
| `PS C:\...>` | PowerShell 命令 |
| `C:\...>` | CMD 命令 |

常见报错也能直接判断：

- `irm` 不是内部或外部命令：在 CMD 里跑了 PowerShell 命令。
- `&&` 不是有效语句分隔符：在旧 PowerShell 里跑了 CMD 命令。
- `claude: command not found`：PATH 没刷新或安装目录没进 PATH。

> [!TIP]
> **安装后先重开终端**：很多 PATH 问题不是安装失败，而是当前 shell 还没加载新路径。重开终端后再跑 `claude --version`。

## 4. Homebrew、WinGet 和 Linux 包管理器

如果你想让系统包管理器统一管理 Claude Code，也可以。

macOS Homebrew：

```bash
brew install --cask claude-code
```

Windows WinGet：

```powershell
winget install Anthropic.ClaudeCode
```

Linux apt / dnf / apk 官方也支持，但第一次配置会涉及添加 Anthropic package repository 和签名 key。新手不需要背命令，按官方 setup 页面复制当前命令即可。

重点不是怎么装，而是怎么更新：

- Homebrew stable：`brew upgrade claude-code`。
- Homebrew latest：`brew upgrade claude-code@latest`。
- WinGet：`winget upgrade Anthropic.ClaudeCode`。
- apt：`sudo apt update && sudo apt upgrade claude-code`。
- dnf：`sudo dnf upgrade claude-code`。
- apk：`sudo apk upgrade claude-code`。

Homebrew 有两个 cask：

- `claude-code`：稳定通道，通常比最新发布慢一些，避开明显回归。
- `claude-code@latest`：最新通道，更快拿到新版本。

> [!IMPORTANT]
> **更新策略别记错**：原生安装器会自动更新；Homebrew 和 WinGet 默认不自动更新，但可以在 `settings.json` 里设 `"env": { "CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1" }` 让 Claude Code 后台跑升级命令（WinGet 在 Claude Code 运行时升级可能因可执行文件被锁失败，会回退到提示手动命令）；apt、dnf、apk 仍要手动升级。用包管理器就要把升级命令纳入你的维护习惯。

## 5. 不推荐新手从 npm 开始

早期很多教程会写：

```bash
npm install -g @anthropic-ai/claude-code
```

现在不建议把它作为新手首选。

原因很现实：

- Node / npm 版本和全局目录经常出权限问题。
- `sudo npm install -g` 容易留下 root-owned 文件。
- 多个安装来源并存时，PATH 里到底跑的是哪个 `claude` 很难判断。

如果你已经装过 npm 版，又遇到登录、更新、命令路径混乱，官方 troubleshoot-install 文档建议迁移到原生安装。

排查时可以看：

```bash
which claude
claude --version
```

Windows PowerShell：

```powershell
where.exe claude
claude --version
```

> [!CAUTION]
> **不要混装多个来源**：同一台机器上同时有 npm、Homebrew、原生安装，很容易出现“我升级了 A，但终端实际跑的是 B”的问题。

## 6. 安装后怎么验证

安装完成后按三步验证。

<Steps>

<Step>

### 看命令是否能找到

```bash
claude --version
```

如果报 `command not found`，先重开终端再试一次（PATH 可能没刷新）；仍失败查 § 9 排障顺序。

</Step>

<Step>

### 跑健康检查

```bash
claude doctor
```

`claude doctor` 会检查安装健康度、设置、MCP 配置、环境等问题。它比单纯看版本更有价值——版本能跑不代表配置和依赖都对。

</Step>

<Step>

### 进入真实项目试运行

```bash
cd your-project
claude
```

进入后先不要大改代码，先问：

```text
这个项目是做什么的？请先不要改代码，只解释项目结构和主要入口。
```

如果这一步能读懂项目，说明安装、登录和基础文件访问基本可用。

</Step>

</Steps>

> [!TIP]
> **最小验收**：`claude --version` 能输出版本，`claude doctor` 无关键错误，真实项目里能回答项目结构，才算安装完成。

## 7. 更新通道怎么选

原生安装器会自动更新。你可以在 Claude Code 里用 `/config` 调整 auto-update channel（自动更新通道），也可以写入 settings（设置文件）。

例如选择 stable：

```json
{
  "autoUpdatesChannel": "stable"
}
```

常见选择：

- `latest`：想尽快拿到新功能，能接受偶发回归。
- `stable`：日常工作主力机，优先稳定。

团队场景可以用 `minimumVersion` 提醒大家更新到某个最低版本：

```json
{
  "minimumVersion": "2.1.0"
}
```

不想等后台自动检查、立刻拉一次更新：

```bash
claude update
```

需要彻底关闭后台自动更新（例如自分发 Claude Code 给团队、要锁版本）：

```json
{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}
```

`DISABLE_AUTOUPDATER` 只关后台检查；`claude update` 和 `claude install` 仍能跑。要堵住所有更新路径（包括手动），改用 `DISABLE_UPDATES`。

> [!WARNING]
> **不要为了新功能牺牲主力环境**：如果 Claude Code 是你的日常生产工具，主力机用 stable，备用机或测试环境用 latest 更稳。

## 8. Windows 怎么选：Native、WSL 2、WSL 1

Windows 用户最容易纠结。

官方当前把 Windows 分成三种：

- **Native Windows**：适合 Windows 原生项目、PowerShell、VS Code Windows 环境；不支持 sandboxing。
- **WSL 2**：适合 Linux 工具链、Node/Python/Rust 等类 Unix 项目；支持 sandboxing。
- **WSL 1**：无法使用 WSL 2 时兜底；不支持 sandboxing。

简单判断：

- 项目平时就在 Windows 路径里开发，用 Native Windows。
- 项目平时就在 WSL 里开发，用 WSL 2。
- 需要 sandboxed command execution，优先 WSL 2。
- 不要让 Claude Code 跨 Windows/WSL 边界操作同一个项目。

Windows 选择时按项目位置判断：

| 项目位置 / 需求 | 推荐入口 |
|------|------|
| 项目在 Windows 原生路径，主要用 PowerShell 或 VS Code Windows | Native Windows |
| 项目在 WSL 文件系统，依赖 Linux 工具链 | WSL 2 |
| 需要 sandboxed command execution（沙盒命令执行） | WSL 2 |
| 机器无法使用 WSL 2 | WSL 1 兜底，但不支持 sandboxing |

## 9. 常见问题先这样排

- `claude` 找不到：重开终端、检查 PATH、看 `which claude` / `where.exe claude`。
- 版本不是刚装的：可能混装，检查多个安装来源。
- 登录失败：看认证章节，确认账号、地区、网络和凭据。
- 搜索文件失败：确认 ripgrep、文件权限和当前目录。
- Windows 命令失败：确认 PowerShell、CMD、Git Bash 没混用。
- WSL 项目访问慢：确认项目是否放在 WSL 文件系统内。
- 更新后行为异常：看版本号，必要时切 stable 或按官方排障回退。

> [!IMPORTANT]
> **排障顺序**：先确认“终端实际运行的是哪个 `claude`”，再看登录、网络、权限。路径不清楚时，后面所有排查都会偏。

## 10. 本章自检

试着用自己的话回答：

1. 为什么新手优先推荐原生安装器，而不是一上来用 Homebrew / WinGet？对应 §1-§4。
2. Homebrew、WinGet、apt、dnf、apk 安装方式和原生安装的最大差别是什么？对应 §4。
3. 安装后为什么要跑 `claude doctor`，而不是只看 `claude --version`？对应 §6。
4. Windows 项目和 WSL 项目为什么不要跨环境操作？对应 §8。
5. 出现命令混乱时，为什么先看 `which claude` / `where.exe claude`？对应 §9。

> [!IMPORTANT]
> **过关标准**：你能为自己的系统选出一个安装通道，并说清它怎么更新、怎么验证、出了 PATH 问题先查哪里。

<details id="glossary">
<summary><b>本篇术语速查表</b></summary>

- **Native installer**：原生安装器，官方推荐的安装方式，支持自动更新。
- **Homebrew**：macOS 包管理器，可以安装 Claude Code；默认不自动更新，可选择启用 Claude Code 后台升级。
- **WinGet**：Windows 包管理器，可以安装 Claude Code；默认不自动更新，可选择启用 Claude Code 后台升级。
- **PATH**：命令搜索路径，shell 用来查找 `claude` 命令的位置列表。
- **`claude doctor`**：健康检查命令，检查安装、配置、MCP、环境等问题。
- **Auto-update channel**：自动更新通道，原生安装使用的 latest / stable 更新选择。
- **`minimumVersion`**：最低版本要求，项目或团队用来提醒更新到某个最低版本。
- **WSL**：Windows Subsystem for Linux，Windows 上运行 Linux 环境的机制。
- **Git Bash**：Git for Windows 附带的 Bash，Windows 原生 Claude Code 使用 Bash tool 的常见依赖。
- **Sandboxing**：沙盒，限制命令进程文件和网络访问的安全机制。

</details>

## 官方来源

- [Advanced setup](https://code.claude.com/docs/en/setup)
- [Quickstart](https://code.claude.com/docs/en/quickstart)
- [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install)
- [Claude Code settings](https://code.claude.com/docs/en/settings)

## 接下来去哪

<Cards>
  <Card href="/docs/claude-code/official/00-getting-started/authentication" title="登录与认证" description="安装完成后，下一步是登录：订阅、Console、企业云供应商和凭据优先级怎么选。" />
  <Card href="/docs/claude-code/official/00-getting-started/overview" title="Claude Code 是什么（上一篇）" description="如果你还不确定为什么要装 Claude Code，先回到产品定位和 agentic loop。" />
  <Card href="/docs/claude-code/official/00-getting-started/platforms" title="选择平台与集成" description="安装后不一定只在终端用。看 CLI、Desktop、IDE、Web 和 Mobile 的入口差异。" />
</Cards>

如果只记一个判断：**安装不是结束，而是建立可验证、可更新、路径清晰的本地入口；命令能跑、doctor 通过、真实项目能读懂，才算装好。**
