Claude Code 安装教程（2026 最新版）

本文基于官方最新文档整理：Advanced setup、Quickstart。

重要变化：官方现在推荐使用原生安装脚本（Native Install），不再首推 npm 安装。原生安装是独立的二进制文件，不依赖 Node.js，并且支持后台自动更新。

一、Claude Code 是什么

Claude Code 是 Anthropic 官方推出的 AI 编程助手 CLI 工具，可以直接在终端中与 Claude 对话，让它阅读代码、修改文件、执行命令、操作 Git 等。除了终端 CLI，Claude Code 还提供：

• Web 版：claude.ai/code
• 桌面应用：macOS / Windows
• IDE 插件：VS Code、JetBrains 系列
• CI/CD 集成：GitHub Actions、GitLab
• Slack 集成

本文重点介绍终端 CLI 的安装与配置。

二、系统要求

项目	要求
操作系统	macOS 13.0+ / Windows 10 1809+（或 Windows Server 2019+）/ Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+
硬件	4 GB 以上内存，x64 或 ARM64 处理器
网络	需要联网
Shell	Bash、Zsh、PowerShell 或 CMD
依赖	ripgrep（通常已内置，无需单独安装）

注意：原生安装方式不需要 Node.js。只有选择 npm 方式安装时才要求 Node.js 18+。

三、安装方式

3.1 原生安装脚本（官方推荐）

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

原生安装的优点：

• 独立二进制，不依赖 Node.js
• 后台自动更新，始终保持最新版本
• 安装位置：~/.local/bin/claude（Windows 为 %USERPROFILE%\.local\bin\claude.exe）

小技巧：如果在 Windows 上看到报错 The token '&&' is not a valid statement separator，说明你在 PowerShell 里执行了 CMD 的命令；反之，如果看到 'irm' is not recognized，说明你在 CMD 里执行了 PowerShell 的命令。提示符以 PS C:\ 开头的是 PowerShell，只有 C:\ 的是 CMD。

3.2 Homebrew（macOS / Linux）

brew install --cask claude-code

Homebrew 提供两个 cask：

Cask	说明
claude-code	跟踪 stable 稳定通道，通常比最新版晚一周左右，会跳过有重大回归的版本
claude-code@latest	跟踪 latest 通道，新版本发布后立即可用

注意：Homebrew 安装不会自动更新，需要手动执行 brew upgrade claude-code（或 brew upgrade claude-code@latest）。另外 Homebrew 升级后会保留旧版本文件，可定期执行 brew cleanup 释放磁盘空间。

3.3 WinGet（Windows）

winget install Anthropic.ClaudeCode

WinGet 安装同样不会自动更新，需定期执行：

winget upgrade Anthropic.ClaudeCode

3.4 npm 安装（需要 Node.js 18+）

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

npm 包安装的也是同一个原生二进制（通过平台相关的 optional dependency 拉取，如 @anthropic-ai/claude-code-darwin-arm64），安装后的 claude 命令本身并不依赖 Node 运行。

升级 npm 安装时使用：

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

注意：

• 不要使用 sudo npm install -g，会导致权限和安全问题；
• 不要用 npm update -g 升级，它受最初安装时 semver 范围限制，可能升不到最新版；
• 包管理器必须允许 optional dependencies，否则二进制会缺失。

四、Windows 安装建议

Windows 上有两种运行方式，按项目所在位置和功能需求选择：

方案	前置条件	沙箱（Sandboxing）	适用场景
原生 Windows	无（Git for Windows 可选）	不支持	Windows 原生项目和工具链
WSL 2	启用 WSL 2	支持	Linux 工具链、需要沙箱执行命令
WSL 1	启用 WSL 1	不支持	无法使用 WSL 2 时

方案一：原生 Windows

直接在 PowerShell 或 CMD 中执行安装命令即可，不需要管理员权限。建议安装 Git for Windows：

• 安装了 Git for Windows：Claude Code 使用 Git Bash 提供 Bash 工具；
• 未安装：Claude Code 改用 PowerShell 作为 shell 工具。

如果 Claude Code 找不到 Git Bash，可在 settings.json 中手动指定路径：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

方案二：WSL

打开 WSL 发行版终端，按 Linux 方式安装（curl -fsSL https://claude.ai/install.sh | bash）。注意安装和启动 claude 都在 WSL 终端内进行，而不是在 PowerShell / CMD 中。

五、验证安装

安装完成后检查版本：

claude --version

更详细的安装与配置体检（包括最近一次自动更新结果）：

claude doctor

如果提示 command not found（Windows 上为 'claude' 不是内部或外部命令 或 The term 'claude' is not recognized），通常是 PATH 未包含安装目录，按系统添加后重开终端即可。

macOS / Linux / WSL（安装目录为 ~/.local/bin）：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

使用 Bash 的系统（多数 Linux 发行版）把上面的 ~/.zshrc 换成 ~/.bashrc。

Windows（安装目录为 %USERPROFILE%\.local\bin），任选一种方式：

方式一：在 PowerShell 中执行命令，永久写入用户级 PATH：

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.local\bin",
  "User"
)

方式二：图形界面操作：

1. 按 Win + R，输入 sysdm.cpl 回车；
2. 切到「高级」选项卡 →「环境变量」；
3. 在上方「用户变量」中选中 Path → 点「编辑」→「新建」；
4. 填入 %USERPROFILE%\.local\bin，一路确定保存。

注意：不建议在 CMD 中使用 setx PATH "%PATH%;..." 来追加——setx 会把系统 PATH 和用户 PATH 合并后整体写入用户变量，且超过 1024 字符会被截断，容易弄坏原有配置。

修改后需要关闭并重新打开终端（已打开的窗口不会读取新的环境变量），再执行 claude --version 验证。

六、更新与版本管理

6.1 自动更新

• 原生安装：启动时及运行期间定期检查更新，后台下载安装，下次启动生效；
• Homebrew / WinGet：默认不自动更新，需手动升级。

如果希望 Claude Code 代为执行 Homebrew / WinGet 的升级命令，可设置环境变量 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1。

6.2 手动更新

不想等后台检查时，可立即更新：

claude update

6.3 发布通道（latest / stable）

通过 autoUpdatesChannel 设置控制自动更新跟踪哪个通道：

• "latest"（默认）：新功能发布后立即接收；
• "stable"：使用约一周前的版本，跳过有重大回归的版本。

可在会话中通过 /config → Auto-update channel 修改，或写入 settings.json：

{
  "autoUpdatesChannel": "stable"
}

还可以用 minimumVersion 锁定版本下限，防止切到 stable 通道时被降级：

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

6.4 禁用自动更新

在 settings.json 中设置：

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

DISABLE_AUTOUPDATER 只停止后台检查，claude update 仍然可用；如需禁止一切更新（包括手动），改用 DISABLE_UPDATES。

6.5 安装指定版本

原生安装脚本支持指定版本号或通道：

# 安装 stable 通道
curl -fsSL https://claude.ai/install.sh | bash -s stable

# 安装指定版本
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89

Windows PowerShell 对应写法：

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89

安装时选择的通道会成为之后自动更新的默认通道。

七、卸载

按安装方式选择对应的卸载命令。卸载后如果 claude 仍可运行，说明存在第二份安装或旧安装器留下的 shell alias。

原生安装（macOS / Linux / WSL）：

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

原生安装（Windows PowerShell）：

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew：

brew uninstall --cask claude-code        # 或 claude-code@latest

WinGet：

winget uninstall Anthropic.ClaudeCode

npm：

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

清理配置文件（可选，慎用）：

警告：删除配置文件会清空所有设置、工具白名单、MCP 服务器配置和会话历史。另外 VS Code 扩展、JetBrains 插件和桌面应用也会写入 ~/.claude/，如需彻底清除，先卸载它们再删除目录。

# 用户级配置
rm -rf ~/.claude
rm ~/.claude.json

# 项目级配置（在项目目录中执行）
rm -rf .claude
rm -f .mcp.json

八、常见问题

1. 安装后提示 command not found: claude

原生安装的二进制在 ~/.local/bin，确认该目录已加入 PATH（见第五节）。Windows 检查 %USERPROFILE%\.local\bin 是否在系统 PATH 中。

2. npm 全局安装遇到 EACCES 权限错误

不要用 sudo。推荐改用原生安装脚本；或者将 npm 全局目录改到用户目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3. 卸载后 claude 还能运行

机器上存在多份安装（例如先 npm 装过、后来又用原生脚本装过）。用 which -a claude（Windows：where claude）找出所有路径，逐一清理。

4. 自动更新失败

运行 claude doctor 查看最近一次更新结果。npm 全局安装如果因目录不可写而无法自动更新，启动时会有一次性提示，claude doctor 中会列出修复方案。

5. 免费账号能用吗？

不能。Claude Code 需要 Pro / Max / Team / Enterprise 订阅或 Console（API）账号，免费版 Claude.ai 不包含 Claude Code 权限。