安装和更新 Claude Code

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

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

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

这会带来两个问题：

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

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

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

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

2. 先看系统要求

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

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

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

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

macOS、Linux、WSL 用这条：

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

Windows PowerShell 用这条：

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

Windows CMD 用这条：

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

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

常见报错也能直接判断：

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

4. Homebrew、WinGet 和 Linux 包管理器

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

macOS Homebrew：

brew install --cask claude-code

Windows WinGet：

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：最新通道，更快拿到新版本。

5. 不推荐新手从 npm 开始

早期很多教程会写：

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

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

原因很现实：

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

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

排查时可以看：

which claude
claude --version

Windows PowerShell：

where.exe claude
claude --version

6. 安装后怎么验证

安装完成后按三步验证。

claude --version

claude doctor

cd your-project
claude

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

7. 更新通道怎么选

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

例如选择 stable：

{
  "autoUpdatesChannel": "stable"
}

常见选择：

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

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

{
  "minimumVersion": "2.1.0"
}

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

claude update

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

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

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

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 选择时按项目位置判断：

9. 常见问题先这样排

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

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。

官方来源

• Advanced setup
• Quickstart
• Troubleshoot installation and login
• Claude Code settings

接下来去哪

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