第 2 章：安装与配置

系统要求与安装方式

macOS / Windows / Linux

Claude Code 是 Anthropic 推出的终端原生 AI 编程助手，其安装过程在 2026 年已经大幅简化。本章将系统梳理各平台的安装方法、系统要求、常见问题排查，以及国内用户的特殊注意事项，帮助你从零开始完成环境搭建。

一、系统要求总览

1.1 操作系统兼容性

平台	最低版本要求	架构支持
macOS	13.0 (Ventura) 及以上	Intel x64 / Apple Silicon ARM64
Windows	Windows 10 1809 或 Windows Server 2019 及以上	x64 / ARM64
Ubuntu	20.04 及以上	x64 / ARM64
Debian	10 及以上	x64 / ARM64
Alpine Linux	3.19 及以上	x64 / ARM64
Fedora / RHEL	36 及以上（社区验证）	x64 / ARM64

1.2 硬件要求

内存：最低 4 GB RAM，推荐 8 GB 及以上
处理器：x64 或 ARM64 架构
磁盘空间：安装包小于 100 MB，预留 500 MB 空间足够
网络：稳定的互联网连接（用于下载和 API 通信）

1.3 前置依赖

Shell 环境：Bash、Zsh、PowerShell 或 CMD 均可
Git：
- macOS / Linux：通常已预装，可通过 git --version 验证
- Windows 原生安装：必须先安装 Git for Windows，否则安装会失败或运行异常
ripgrep：通常随 Claude Code 内置。若搜索功能异常，需手动安装

1.4 账户要求

Claude Code 不支持免费版 Claude.ai 账户，需要以下任一付费账户：

账户类型	月费	适用场景
Claude Pro	$20/月（年付 $17/月）	个人开发者入门
Claude Max 5x	$100/月	高频使用者
Claude Max 20x	$200/月	团队核心开发者
Teams Standard	$25/人/月	小型团队
Anthropic Console	按量付费	CI/CD 或低频使用

国内用户可通过 API 中转站或国产模型替代方案绕过订阅限制，详见后文「国内访问注意事项」章节。

二、macOS 安装

2.1 方式一：curl 一键安装（推荐）

这是官方推荐的方式，零依赖、自动更新、启动最快。

# 打开终端（Terminal.app 或 iTerm2），执行：
curl -fsSL https://claude.ai/install.sh | bash

安装过程约 30 秒，脚本会自动：

检测你的系统架构（Intel 或 Apple Silicon）
下载对应平台的原生二进制文件
放置到 ~/.local/bin/ 目录
更新 Shell 的 PATH 环境变量

安装完成后，新开一个终端窗口（或执行 source ~/.zshrc）使 PATH 生效。

# 验证安装
claude --version

# 详细诊断
claude doctor

2.2 方式二：Homebrew 安装

适合已使用 Homebrew 管理工具链的开发者。

# 安装稳定版（约滞后最新版一周，跳过有严重回归的版本）
brew install --cask claude-code

# 或安装最新版（跟随最新发布通道）
brew install --cask claude-code@latest

注意：Homebrew 安装的版本不会自动更新，需要手动执行：

brew upgrade claude-code

2.3 方式三：npm 安装（遗留方式）

npm 安装方式已官方弃用，仅建议在需要锁定特定版本时使用。

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

要求 Node.js 18.0 或更高版本。npm 包实际安装的是与原生安装器相同的二进制文件，但启动时需要初始化 Node.js 运行时，比原生安装慢 500-1500 毫秒。

2.4 macOS 常见问题

问题 1：command not found: claude

# 方案 A：新开终端窗口使 PATH 生效
# 方案 B：手动加载 Shell 配置
source ~/.zshrc        # macOS 默认使用 Zsh
source ~/.bashrc       # 如使用 Bash

# 方案 C：检查 PATH 是否包含 ~/.local/bin
echo $PATH | grep ".local/bin"
# 如缺失，手动添加：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题 2：安装脚本安全顾虑

# 先下载脚本，审阅后再执行
curl -fsSL https://claude.ai/install.sh -o install-claude.sh
less install-claude.sh    # 审阅脚本内容
bash install-claude.sh    # 确认无误后执行

问题 3：从 npm 迁移到原生安装

# 1. 确认当前是 npm 安装
which claude    # 如路径包含 node_modules，则为 npm 安装

# 2. 卸载 npm 版本
npm uninstall -g @anthropic-ai/claude-code

# 3. 确认已卸载
which claude    # 应返回 "not found"

# 4. 安装原生版本
curl -fsSL https://claude.ai/install.sh | bash

# 5. 验证
claude --version

配置和认证信息存储在 ~/.claude/ 目录，迁移过程中会被保留，无需重新登录。

三、Windows 安装

Windows 用户需要首先做一个关键决策：原生 Windows 安装还是 WSL 安装？

方案	前置要求	沙箱支持	适用场景
原生 Windows	Git for Windows	不支持	Windows 原生项目、.NET、PowerShell 脚本
WSL 2	WSL 2 已启用	支持	Linux 工具链、Docker、需要隔离命令执行
WSL 1	WSL 1 已启用	不支持	WSL 2 不可用时降级使用

3.1 原生 Windows 安装（推荐大多数用户）

前置条件：安装 Git for Windows

访问 git-scm.com 下载安装包
运行安装程序，保持默认选项（确保 "Add Git to PATH" 已勾选）
安装完成后重启终端
验证：git --version

方式 A：PowerShell 一键安装（推荐）

# 在 PowerShell 中执行（非 CMD）
irm https://claude.ai/install.ps1 | iex

安装完成后，完全关闭 PowerShell 再重新打开，使 PATH 更新生效。

# 验证
claude --version
claude doctor

方式 B：WinGet 安装

# WinGet 内置于 Windows 11 和 Windows 10 22H2+
winget install Anthropic.ClaudeCode

# 手动更新
winget upgrade Anthropic.ClaudeCode

WinGet 安装的版本不会自动更新。

方式 C：CMD 安装（PowerShell 受限时使用）

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

常见错误提示：
The token '&&' is not a valid statement separator → 你当前在 PowerShell 中，应使用 PowerShell 安装命令
'irm' is not recognized as an internal or external command → 你当前在 CMD 中，应使用 CMD 安装命令

3.2 PATH 问题排查（Windows 最常见问题）

安装成功后如果提示 claude 不是可识别命令：

# 1. 检查 PATH 是否包含 ~/.local/bin
echo $env:PATH

# 2. 如缺失，手动添加（将 YourName 替换为你的用户名）
# Win + R → sysdm.cpl → 高级 → 环境变量
# 在用户变量的 Path 中新建：C:\Users\YourName\.local\bin

# 3. 或通过 PowerShell 添加（谨慎操作，先备份）
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Users\YourName\.local\bin",
    "User"
)

# 4. 完全关闭并重新打开终端

3.3 WSL 安装（Linux 优先开发者）

如果你主要开发面向 Linux 部署的项目（Node.js 后端、Python、Docker），WSL 是更干净的选择。

# 步骤 1：在管理员 PowerShell 中启用 WSL
wsl --install

# 步骤 2：按提示重启计算机
# 步骤 3：重启后 Ubuntu 自动启动，创建用户名和密码
# 步骤 4：在 Ubuntu 终端中更新系统
sudo apt update && sudo apt upgrade -y

# 步骤 5：安装 Claude Code（使用 Linux 安装命令）
curl -fsSL https://claude.ai/install.sh | bash

WSL 最佳实践：

项目文件存放在 WSL 文件系统内（~/projects/），而非 Windows 挂载路径（/mnt/c/...）
跨文件系统操作显著更慢，可能导致 Claude Code 超时
WSL 内需要独立安装 Node.js（如有 npm 安装需求），Windows 侧的 Node.js 对 WSL 不可见

3.4 Windows 特有配置

Git Bash 路径配置

Claude Code 在 Windows 上内部使用 Git Bash 执行命令。如果找不到 Git Bash，在 ~/.claude/settings.json 中手动指定：

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

PowerShell 原生工具（实验性）

Claude Code 正在逐步推出 PowerShell 原生工具支持。可通过环境变量启用或禁用：

$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"   # 启用
$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "0"   # 禁用

PowerShell 执行策略

如遇到执行策略错误：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# 输入 Y 确认

四、Linux 安装

4.1 通用安装（Ubuntu / Debian / 大多数发行版）

# 一键安装（与 macOS 相同命令）
curl -fsSL https://claude.ai/install.sh | bash

安装器自动检测架构（x64 或 ARM64）并下载对应二进制文件。

4.2 包管理器安装

Claude Code 提供官方签名的 apt、dnf 和 apk 仓库。包管理器安装的版本不会通过 Claude Code 自动更新，更新走系统正常的升级流程。

apt（Debian / Ubuntu）

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

# 验证 GPG 指纹（应为 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE）
gpg --show-keys /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

# 后续更新
sudo apt update && sudo apt upgrade claude-code

dnf（Fedora / RHEL）

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

# 验证指纹后确认安装
# 后续更新
sudo dnf upgrade claude-code

apk（Alpine Linux）

Alpine 和其他 musl/uClibc 发行版需要额外安装依赖：

# 安装依赖
apk add libgcc libstdc++ ripgrep

# 添加仓库密钥
wget -O /etc/apk/keys/claude-code.rsa.pub \
  https://downloads.claude.ai/keys/claude-code.rsa.pub

# 验证密钥（sha256sum 应为 395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6）
sha256sum /etc/apk/keys/claude-code.rsa.pub

echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

# 配置使用系统 ripgrep
echo '{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}' > ~/.claude/settings.json

# 后续更新
apk update && apk upgrade claude-code

4.3 npm 安装

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

需要 Node.js 18+。npm 包通过平台特定的可选依赖（如 @anthropic-ai/claude-code-linux-x64）拉取原生二进制文件。

支持的 npm 平台：darwin-arm64、darwin-x64、linux-x64、linux-arm64、linux-x64-musl、linux-arm64-musl、win32-x64、win32-arm64。

五、网络要求与国内访问注意事项

5.1 安装阶段的网络问题

Claude Code 的安装脚本和更新检查需要从 claude.ai 和 downloads.claude.ai 下载文件。国内直接访问可能遇到超时或失败。

解决方案 1：使用 npm + 国内镜像源安装

# 配置淘宝 npm 镜像
npm config set registry https://registry.npmmirror.com/

# 验证配置
npm config get registry
# 应输出：https://registry.npmmirror.com/

# 全局安装
npm install -g @anthropic-ai/claude-code

解决方案 2：配置代理后执行 curl 安装

export HTTPS_PROXY=http://your-proxy:port
export HTTP_PROXY=http://your-proxy:port
curl -fsSL https://claude.ai/install.sh | bash

解决方案 3：先下载安装脚本，再本地执行

# 通过浏览器或其他工具下载 install.sh
# 然后本地执行
bash install.sh

5.2 使用阶段的网络问题

Claude Code 运行时需要连接 Anthropic API（api.anthropic.com）。国内用户有以下选择：

路线 A：API 中转站（使用 Claude 原版模型）

通过第三方 API 中转站代理请求，支持支付宝/微信付款，按量计费。

配置方式（在 ~/.claude/settings.json 中）：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key",
    "ANTHROPIC_BASE_URL": "https://your-router-domain.com"
  }
}

路线 B：接入国产模型（零成本方案）

使用 claude-code-router 等开源工具，将请求转发给硅基流动、DeepSeek、火山引擎等国内模型服务。

# 安装 router
npm install -g @musistudio/claude-code-router

# 配置 ~/.claude-code-router/config.json
# 然后使用 ccr code 启动

路线 C：企业代理配置

# 设置环境变量（当前会话有效）
export HTTPS_PROXY=http://proxy.company.com:8080

# 或在 settings.json 中持久化配置
{
  "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080"
  }
}

5.3 国内安装检查清单

npm 已配置国内镜像源（推荐淘宝镜像）
终端以管理员身份运行（Windows）
安装完成后关闭并重新打开终端
claude --version 能正常输出版本号
网络代理配置正确（如使用代理）

六、验证安装

6.1 基础验证

# 检查 claude 命令是否可用
which claude          # macOS/Linux
where.exe claude      # Windows PowerShell

# 查看版本号
claude --version
# 预期输出类似：2.1.xxx

# 详细诊断（强烈推荐首次安装后运行）
claude doctor

claude doctor 会检查：

安装完整性（原生/npm/WinGet）
版本信息
认证状态
Git 健康度
PATH 配置
网络连通性

6.2 首次启动

# 进入你的项目目录
cd /path/to/your/project

# 启动 Claude Code
claude

首次启动会打开浏览器进行 OAuth 认证。使用 Claude Pro / Max / Teams 账户登录并授权后，会话令牌会保存在 ~/.claude/session.json，后续无需重复登录。

无浏览器环境（CI/CD、远程服务器）：

export ANTHROPIC_API_KEY="sk-ant-api03-your-key"
claude

七、升级与卸载

7.1 自动更新（原生安装）

原生安装的 Claude Code 会在启动时和运行期间自动检查更新，后台下载并在下次启动时生效。

配置更新通道：

# 通过交互式配置
claude /config
# 选择 Auto-update channel → latest 或 stable

或在 ~/.claude/settings.json 中：

{
  "autoUpdatesChannel": "stable"
}

latest（默认）：新功能发布后立即可用
stable：约滞后一周，跳过有严重回归的版本

禁用自动更新：

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

DISABLE_AUTOUPDATER 仅停止后台检查，claude update 和 claude install 仍然可用。如需完全阻止所有更新路径，使用 DISABLE_UPDATES。

7.2 手动更新

# 立即应用更新（不等待下次后台检查）
claude update

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

版本锁定：

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

minimumVersion 设置版本下限，防止从 latest 回退到 stable 时降级。

7.3 各平台卸载方法

原生安装

# 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

# 最新版
brew uninstall --cask claude-code@latest

WinGet

winget uninstall Anthropic.ClaudeCode

apt / dnf / apk

# apt
sudo apt remove claude-code
sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc

# dnf
sudo dnf remove claude-code
sudo rm /etc/yum.repos.d/claude-code.repo

# apk
apk del claude-code
sed -i '\|downloads.claude.ai/claude-code/apk|d' /etc/apk/repositories
rm /etc/apk/keys/claude-code.rsa.pub

npm

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

7.4 彻底清理配置

如需完全移除 Claude Code 的所有痕迹（包括用户设置、项目配置、缓存数据）：

# macOS / Linux / WSL
# 移除用户级设置和状态
rm -rf ~/.claude
rm ~/.claude.json

# 在项目目录中移除项目级设置
rm -rf .claude
rm -f .mcp.json

# Windows PowerShell
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force

注意：VS Code 扩展、JetBrains 插件和 Desktop 应用也会写入 ~/.claude/ 目录。如果其中任一工具仍安装，该目录会在下次运行时重新创建。

八、安装方法对比速查表

安装方式	平台	自动更新	依赖	适用人群
curl 原生安装	macOS / Linux / WSL	是	无	大多数用户首选
PowerShell 原生安装	Windows	是	Git for Windows	Windows 用户首选
Homebrew	macOS / Linux	否	Homebrew	Homebrew 用户
WinGet	Windows	否	WinGet	Windows 包管理用户
npm	全平台	否	Node.js 18+	需要版本锁定或国内镜像用户
apt/dnf/apk	Linux	否（系统升级）	对应包管理器	企业部署、服务器环境
WSL + Linux 安装	Windows	是（通过 Linux）	WSL 2	Linux 优先开发者

九、常见问题汇总（FAQ）

Q1：Claude Code 需要 Node.js 吗？

不需要。原生安装器和 Homebrew 方式零外部依赖。只有 npm 安装方式需要 Node.js 18+。

Q2：Apple Silicon Mac 支持吗？

支持。原生安装器自动检测架构并下载 ARM64 二进制文件。

Q3：安装成功但 claude 命令找不到？

最常见原因：终端会话未刷新 PATH。完全关闭终端并重新打开。如仍有问题，检查 ~/.local/bin 是否在 PATH 中。

Q4：npm 安装遇到 EACCES 权限错误？

切勿使用 sudo npm install -g。正确做法：

mkdir -p ~/.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

或更好：迁移到原生安装器。

Q5：Windows 上 Git 已安装但 Claude Code 仍报错？

确认 Git 在 PATH 中：where.exe git。如找不到，重新安装 Git for Windows 并确保 "Add to PATH" 已勾选。

Q6：企业网络代理导致安装/认证失败？

export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

某些企业防火墙会阻止 WebSocket 连接，需要 IT 部门将 claude.ai 和 api.anthropic.com 加入白名单。

Q7：可以免订阅使用 Claude Code 吗？

标准安装不行。需要 Claude Pro/Max/Teams/Enterprise 订阅，或 Anthropic Console API 账户。国内用户可通过 API 中转站或国产模型替代方案实现零成本使用。

Q8：Claude Code 有桌面应用或 IDE 插件吗？

有。除了终端 CLI，还提供 VS Code 扩展、JetBrains 插件和 Desktop 应用。IDE 扩展基于已安装的 CLI 二进制文件工作。

Q9：Windows 粘贴图片的快捷键是什么？

Windows 上使用 Alt+V 粘贴图片（而非 Ctrl+V，后者仅粘贴文本）。

Q10：如何验证下载的二进制文件完整性？

每个版本发布包含签名的 manifest.json，其中列出所有平台二进制文件的 SHA256 校验和。验证步骤：

# 1. 下载 manifest 和签名
curl -fsSL https://downloads.claude.ai/claude-code/manifest.json -o manifest.json
curl -fsSL https://downloads.claude.ai/claude-code/manifest.json.asc -o manifest.json.asc

# 2. 导入 Anthropic GPG 密钥并验证签名
gpg --keyserver keyserver.ubuntu.com --recv-keys BAA929FF1A7ECACE
gpg --verify manifest.json.asc manifest.json

# 3. 验证二进制文件 SHA256
shasum -a 256 ./claude    # macOS
sha256sum ./claude        # Linux
# 与 manifest.json 中对应平台的 checksum 比对

平台原生代码签名验证：

# macOS
codesign --verify --verbose ./claude

# Windows PowerShell
Get-AuthenticodeSignature .\claude.exe

十、参考来源

官方文档
- Claude Code 官方安装文档 - Advanced setup — Anthropic 官方维护的系统要求、安装方式、更新和卸载指南
- @anthropic-ai/claude-code - npm — npm 包官方页面
社区教程
- How to Install Claude Code in 2026 - LaoZhang AI Blog — 覆盖六种安装方式的综合指南
- Claude Code Installation Guide for Windows - DEV Community — Windows 安装深度指南，含 PATH 和环境变量详解
- Installing Claude Code on Windows - PQ.Hosting — Windows 原生安装、WinGet 和 WSL 方案
- How to Set Up Claude Code on Windows Using WSL - lowtouch.ai — WSL 完整配置指南
国内用户资源
- 中国大陆安装 Claude Code 完全指南 - hoopyAI — 不翻墙、零成本的国产模型接入方案
- 国内环境下 Claude Code 安装、更新与配置淘宝镜像 - CSDN — npm + 淘宝镜像的详细步骤
- Claude Code 国内直连教程 - 火山引擎开发者社区 — 含一键配置脚本
- 国内使用 Claude Code 教程 - 掘金 — API 中转站配置指南
- Claude Code Windows 安装与配置 - 博客园 — 国内模型避坑指南
GitHub 资源
- anthropics/claude-code — 官方仓库
- claude-code-chinese/claude-code-guide — 中文社区指南

Claude Code 的 Agentic Loop 全拆解

认证、登录与多账户管理

Claude Code 的认证体系远比表面上复杂。它同时支持订阅账户（Pro / Max / Team / Enterprise）、Anthropic Console API Key、以及三大云提供商（AWS Bedrock / Google Vertex AI / Microsoft Foundry）三种完全不同的认证路径。每种路径的计费方式、使用限制、适用场景各不相同。本章将系统梳理所有认证方式，帮助你选择最适合自己的方案，并掌握多账户切换、故障排查的实用技巧。