Claude Code 安装最简流程：三端命令、自动更新与彻底卸载一次说清

传统的 AI 编码工具往往需要手动配置 Node.js 环境、解决 npm 权限错误、维护 PATH 变量，整个流程对初学者并不友好。Claude Code 作为 Anthropic 推出的命令行 AI 编码助手，2025 年 10 月起官方将原生安装器（native installer）确立为推荐安装方式，零依赖、自动配置 PATH、后台自动更新，把 Claude Code 安装流程压缩到一行命令。

Claude Code 支持 macOS 13.0+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+，覆盖 x64 与 ARM64 主流架构。本指南按”使用价值—系统要求—安装方法—问题排查—验证使用—获取方式”六段，详细说明在不同设备上完成 Claude Code 安装的最简流程，覆盖标准账号、企业部署、第三方推理服务等多种场景。

为什么要使用原生安装器

原生安装器作为 Anthropic 当前的官方推荐方式，相比 npm 等传统路径有几项实际价值：

零依赖部署：不需要 Node.js 运行时，不需要 npm 全局权限配置。一行 curl 或 irm 命令完成下载、PATH 配置与首次启动准备，整个过程通常在 30 秒内结束。

后台自动更新：原生安装是唯一获得 Claude Code 内置更新机制的安装方式。启动时与运行中后台检查新版本，下次启动生效，无需手动维护。Anthropic 官方文档明确指出 Homebrew、WinGet、apt、dnf、apk 与 npm 安装均不参与该机制，这是选择安装路径时最容易被忽略却最关键的差异。

跨平台一致：macOS、Linux、WSL 共用同一条 install.sh 脚本，Windows PowerShell 与 CMD 各有对应版本但安装结果一致，二进制本身在所有平台行为相同。

发布通道可控：通过 autoUpdatesChannel 设置在 latest（即时收到新版本）与 stable（约滞后一周、跳过有重大回退的版本）之间切换。企业部署可追加 minimumVersion 字段防止版本回滚。

统一卸载路径：所有原生安装的二进制都位于 ~/.local/bin/claude（Windows 为 %USERPROFILE%\.local\bin\claude.exe），卸载只需删除两个目录，无包管理器残留。

系统要求与前置检查

根据 Claude Code 官方安装文档，运行 Claude Code 需满足以下条件：

• 操作系统：macOS 13.0+、Windows 10 1809+ 或 Windows Server 2019+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+
• 系统架构：x64 或 ARM64
• 硬件：4 GB 以上内存
• Shell：Bash、Zsh、PowerShell 或 CMD（原生 Windows 推荐安装 Git for Windows 以便调用 Bash 工具）
• 账号：Claude Pro、Max、Team、Enterprise 或 Anthropic Console（API 计费）账号之一，免费版 Claude.ai 不包含 Claude Code 访问权限
• 网络：稳定连接到 Anthropic 服务端点，国内用户可能需要配置代理

也可通过 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 接入第三方推理服务，适合企业自有云资源或合规要求场景。

检查是否已安装 Claude Code 的方法：打开终端执行：

claude --version

如果返回版本号（如 2.1.xxx），说明已安装。如果提示 command not found，按下文方法安装。

安装方法

方法一：原生安装器（推荐）

最简单且官方推荐的方式，零依赖、自动 PATH 配置、后台自动更新，覆盖三大平台。

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

二进制将安装到 ~/.local/bin/claude（Windows 为 %USERPROFILE%\.local\bin\claude.exe），PATH 由安装脚本自动配置。完成后运行 claude –version 验证。

区分 PowerShell 与 CMD 的小技巧：提示符为 PS C:\ 是 PowerShell，仅 C:\ 是 CMD。若执行 irm 命令报 ‘irm’ is not recognized，说明当前是 CMD；若执行 CMD 命令报 The token ‘&&’ is not a valid statement separator，说明当前是 PowerShell。

首次启动 claude 时浏览器会自动打开 OAuth 授权页面，登录 Anthropic 账号后令牌本地存储。无浏览器环境（服务器、容器、CI Pipeline）改用环境变量：

export ANTHROPIC_API_KEY=sk-ant-...

方法二：Homebrew（仅 macOS）

适合习惯 Homebrew 工作流的 macOS 用户。Homebrew 提供两个 cask，对应不同发布通道：

# 稳定通道（约滞后一周，跳过有重大回退的版本）
brew install --cask claude-code
 
# 最新通道（新版本发布时立即收到）
brew install --cask claude-code@latest

注意 Homebrew 安装不参与 Claude Code 的后台自动更新，需手动执行 brew upgrade claude-code 或 brew upgrade claude-code@latest。两个 cask 不能同时安装，重新选择通道前需先卸载现有 cask。

方法三：WinGet（仅 Windows）

通过 Windows Package Manager 安装：

winget install Anthropic.ClaudeCode

WinGet 路径有两个已确认的已知问题，部署前需了解：

问题 1：永久”Update available”提示。GitHub Issue 33155 显示 Claude Code 的更新检查比对的是 npm 注册表版本，而 winget 包审核流程比 npm 慢 1-2 个版本，导致 winget 用户长期看到黄色更新横幅但 winget upgrade 报 No applicable update found。当前没有官方修复。

问题 2：升级可能破坏 PATH。GitHub Issue 27867 显示执行 winget upgrade Anthropic.ClaudeCode 后二进制被移到 C:\Users\<username>\.local\bin\claude.exe 但 PATH 未自动更新，claude 命令找不到。修复方式是在 PowerShell profile 中追加：

$env:PATH += ";$env:USERPROFILE\.local\bin"
. $PROFILE

鉴于这两个问题，Windows 用户除非有强烈包管理器统一偏好，否则建议直接用方法一的 PowerShell 原生安装器。

方法四：Linux 包管理器（apt / dnf / apk）

适合团队规范要求所有软件经包管理器分发的场景。Anthropic 提供官方签名仓库，密钥指纹为 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE，建议在信任前手动校验。

Debian / Ubuntu（apt）：

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Fedora / RHEL（dnf）：

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

Alpine Linux（apk）：

wget -O /etc/apk/keys/claude-code.rsa.pub \
  https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

将 URL 中的 stable 替换为 latest 即切换到最新通道。这些路径同样不参与 Claude Code 后台自动更新，依赖系统包管理器升级流程。

Alpine 与其他 musl 发行版的额外步骤：原生安装器需先安装 libgcc、libstdc++、ripgrep，并在 ~/.claude/settings.json 中配置：

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

否则会因 musl 与 glibc 链接器差异导致搜索功能失效。

方法五：npm 安装（仅特定场景适用）

npm 不再是默认推荐方式，仅在 CI/CD 中需要固定版本、团队工作流以 npm 为标准、或与 Node.js 项目共用版本管理时使用：

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

要求 Node.js 18 或更高。该 npm 包安装的与原生安装器是同一个二进制——通过 @anthropic-ai/claude-code-darwin-arm64 等 optional dependency 拉取对应平台 binary，postinstall 阶段链接到 PATH。已安装的 claude 二进制本身不调用 Node.js 运行时。

禁止使用 sudo npm install -g，会导致权限污染与安全风险。遇到 EACCES 错误的正确处理方式是配置用户级 npm prefix：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

或改用 nvm 管理 Node.js 版本。

方法六：Windows 用户的 WSL 路径

WSL 适合需要 Linux 工具链或沙盒（sandboxing）命令执行的开发场景。WSL 2 支持沙盒，WSL 1 不支持。原生 Windows 路径与 WSL 路径的选择标准：

• 原生 Windows：Windows 原生项目与工具链，不支持 sandboxing
• WSL 2：Linux 工具链或需要沙盒命令执行，推荐
• WSL 1：仅在 WSL 2 不可用时使用

在 WSL 终端内执行方法一的 Linux 安装命令即可。注意所有依赖必须在 WSL 环境内安装而非 Windows 侧——一个常见误区是 Windows 已装 Node.js 但 WSL 内没装，npm 路径会因此报 command not found。

更新方式：每个平台不同，搞错会一直收到提醒

这是 Claude Code 安装中最容易踩坑的环节，不同安装路径的更新机制完全不同：

• 原生安装器：启动时与运行中后台自动检查，下次启动生效，零干预；可执行 claude update 立即触发
• Homebrew：brew upgrade claude-code 或 brew upgrade claude-code@latest（取决于安装的 cask）
• WinGet：winget upgrade Anthropic.ClaudeCode
• apt：sudo apt update && sudo apt upgrade claude-code
• dnf：sudo dnf upgrade claude-code
• apk：apk update && apk upgrade claude-code
• npm：重新执行 npm install -g @anthropic-ai/claude-code

切换发布通道编辑 ~/.claude/settings.json：

{
  "autoUpdatesChannel": "stable"
}

完全禁用自动更新设置 DISABLE_AUTOUPDATER=1；需彻底封锁包括 claude update 在内所有更新路径时设置 DISABLE_UPDATES，适用于企业自有分发场景。

常见问题排查

问题 1：claude –version 提示 command not found

原因：PATH 未自动更新，或终端会话未重载。

解决方案：

• 关闭当前终端，开新终端窗口
• macOS/Linux 执行 source ~/.zshrc 或 source ~/.bashrc
• Windows 关闭并重开 PowerShell 窗口
• 仍找不到执行 which claude（Linux/macOS）或 where claude（Windows）确认实际路径

问题 2：npm 安装报 EACCES 权限错误

原因：npm 全局目录归 root 所有，或之前用过 sudo 安装。

解决方案：不要使用 sudo。改用方法一的原生安装器，或按方法五配置用户级 npm prefix。

问题 3：Node.js 版本过旧

原因：npm 安装路径要求 Node.js 18+。

解决方案：执行 node –version 检查。低于 18 时通过 nvm install –lts 升级，或改用原生安装器（不需要 Node.js）。

问题 4：Git Bash 报 “Raw mode is not supported”

原因：Git Bash 不完整支持 Claude Code 交互式 CLI 所需的 TTY 功能。

解决方案：在 Windows PowerShell 或 Windows Terminal 中启动 claude。Git for Windows 仅作为 Bash 工具的执行后端，启动 Claude Code 本身应使用 PowerShell。

问题 5：WinGet 永久显示 “Update available”

原因：Claude Code 的更新检查比对的是 npm 注册表版本，与 winget 包注册表存在 1-2 个版本的滞后。

解决方案：当前无官方修复。可忽略提示等待 winget 包追上，或卸载 winget 安装改用方法一的原生安装器。

问题 6：WinGet 升级后 claude 命令找不到

原因：升级后二进制被移动但 PATH 未更新。

解决方案：在 PowerShell profile 中追加 $env:PATH += “;$env:USERPROFILE\.local\bin”，执行 . $PROFILE 重载。

问题 7：asdf 用户从 npm 迁移后仍调用旧版本

原因：asdf shim 优先级高于原生安装路径，which claude 仍指向 ~/.asdf/shims/claude。

解决方案：对 asdf 管理过的每个 Node.js 版本逐一卸载：

for version in $(asdf list nodejs | tr -d ' *'); do
  echo "Uninstalling from nodejs $version..."
  ASDF_NODEJS_VERSION=$version npm uninstall -g @anthropic-ai/claude-code 2>/dev/null
done

如果 shim 仍残留，手动删除 ~/.asdf/shims/claude。

问题 8：OAuth 浏览器回调失败

原因：远程 SSH、devcontainer 或严格防火墙环境下 localhost 回调被阻断。

解决方案：使用手动流程——复制终端打印的 URL，在任意浏览器完成登录，将返回码粘贴回终端。或在无浏览器环境直接设置 ANTHROPIC_API_KEY 环境变量。

问题 9：企业网络下载失败或证书错误

原因：下载主机被代理拦截，或公司注入了自己的 CA 证书。

解决方案：

• 设置代理：export HTTPS_PROXY=http://proxy.example.com:port 后重新执行安装命令
• 指向公司 CA 包：export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem
• 将以上变量加入 shell profile 持久化

问题 10：搜索功能失效或 @file 引用找不到文件

原因：内置 ripgrep 二进制在当前系统不兼容，常见于 Alpine、musl 发行版与部分 ARM 设备。

解决方案：通过包管理器安装 ripgrep（如 apk add ripgrep、apt install ripgrep），并在 ~/.claude/settings.json 设置 USE_BUILTIN_RIPGREP=0。

验证安装与基础使用

安装完成后，建议执行以下命令验证 Claude Code 是否正常工作：

# 检查版本
claude --version
 
# 详细环境检查（PATH、认证状态、MCP 服务器、文件权限）
claude doctor
 
# 启动 Claude Code（首次启动会触发 OAuth 授权）
claude

进入 Claude Code 后可使用以下内置命令：

# 完整健康检查
/doctor
 
# 查看所有 slash 命令
/help
 
# 生成项目级 CLAUDE.md（持久上下文）
/init
 
# 压缩对话历史（释放 context window）
/compact
 
# 清空当前会话
/clear
 
# 查看会话状态与上下文使用量
/status

装完之后的关键三步：

• 在项目根目录运行 /init 生成 CLAUDE.md，让 Claude Code 持久理解项目结构、技术栈与团队规范——后续每次会话质量都依赖这个文件
• 在终端内输入 /help 浏览内置 slash 命令清单，了解 /compact、/clear、/status 等常用工具
• 通过 ~/.claude/settings.json 配置 MCP（Model Context Protocol）服务器，把 Claude Code 从命令行助手扩展为可调用 GitHub、数据库、内部工具的完整 agent 平台

卸载方式：不同安装路径对应不同清理步骤

卸载按安装方式分别处理：

• 原生安装器（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
• apt：sudo apt remove claude-code，删除 /etc/apt/sources.list.d/claude-code.list 与 /etc/apt/keyrings/claude-code.asc
• dnf：sudo dnf remove claude-code，删除 /etc/yum.repos.d/claude-code.repo
• apk：apk del claude-code，删除仓库行与 /etc/apk/keys/claude-code.rsa.pub
• npm：npm uninstall -g @anthropic-ai/claude-code

仅删除二进制并不能完全清理 Claude Code。配置目录 ~/.claude/ 与 ~/.claude.json 包含设置、MCP 服务器配置、会话历史与已授权工具列表，会被保留以便重装。彻底清理执行：

# macOS / Linux / WSL
rm -rf ~/.claude
rm ~/.claude.json
 
# 项目级配置（在每个项目目录下）
rm -rf .claude
rm -f .mcp.json

Windows 对应 %USERPROFILE%\.claude 与 %USERPROFILE%\.claude.json。

容易被忽略的陷阱：VS Code 扩展、JetBrains 插件与 Claude Desktop 应用都会写入 ~/.claude/。若它们仍然安装，删除该目录后会被立即重建。彻底清理前必须先卸载所有相关 IDE 集成。

获取方式

官方文档：Claude Code 官方文档

安装与配置参考：Advanced setup

npm 包：@anthropic-ai/claude-code

故障排查中心：Claude Help Center

GitHub Issues：anthropics/claude-code

Claude Code 通过原生安装器把命令行 AI 编码工具的部署门槛压到了一行命令，但安装本身只是入口。对中文开发者而言，真正决定生产力的是后续 CLAUDE.md 上下文设计、MCP 服务器集成与 agent 工作流配置——掌握这些才是 Claude Code 实际价值所在。