本节目标

完成本节后，你将能够：

1. 在你的操作系统上（Windows / macOS / Linux）成功安装 Claude Code

2. 正确配置 Anthropic API Key

3. 为中国大陆用户完成网络代理配置

4. 使用 claude doctor 验证安装完整性

5. 理解安装过程中每个步骤的"为什么"

---

核心知识点

系统要求（截至 2026 年 5 月，Claude Code v2.1.x）

在开始安装之前，确保你的系统满足以下最低要求：

组件	最低要求	推荐配置	为什么需要
Node.js	18.0+	20 LTS 或更新	Claude Code 是 Node.js 应用，通过 npm 分发
Git	2.40+	最新稳定版	Claude Code 需要 Git 来进行版本控制和差异对比
操作系统	macOS 12+ / Windows 10+ / Ubuntu 20.04+	最新稳定版	终端兼容性和 Node.js 运行时支持
内存	无特殊要求	4GB+	Claude Code 本身轻量，主要消耗在 Node 进程
磁盘空间	约 200MB	500MB+	npm 全局包 + 依赖缓存
网络	稳定的 HTTPS 连接	低延迟连接	所有 AI 推理都在云端进行，需要持续 API 通信

关键理解：Claude Code 不在你本地运行 AI 模型。所有推理都通过 HTTPS 在 Anthropic 的服务器上完成，然后结果流式返回你的终端。这意味着：

• 你不需要 GPU

• 你的电脑风扇不会狂转

• 但你需要一个稳定的网络连接

Anthropic API Key 的本质

Claude Code 使用的是 Anthropic 的 API（而非网页版 Claude.ai 的订阅）。你需要一个 API Key 来验证身份和计费。

关键区别：

• Claude.ai 订阅（$20/月）：在网页/App 上使用 Claude，不能用于 Claude Code

• Anthropic API Key：按量计费，可以在 Claude Code、API 调用、第三方工具中使用

• 获取地址：https://console.anthropic.com/

API 的计费基于 token 消耗。截至 2026 年 5 月：

• Claude Sonnet 4：输入 $3/百万 token，输出 $15/百万 token（带缓存输入 $0.30/百万 token）

• Claude Opus 4：输入 $15/百万 token，输出 $75/百万 token

• Claude Haiku 3.5：输入 $0.80/百万 token，输出 $4/百万 token

对于个人开发者日常使用，Sonnet 模型是性价比最优的选择。一个中等复杂度的开发任务通常消耗 $0.5-3。

---

实操步骤

步骤 1：检查前置依赖

打开终端，逐条运行以下命令检查：

# 检查 Node.js
node --version
# 期望输出: v20.x.x 或更高
​
# 检查 npm
npm --version
# 期望输出: 10.x.x 或更高
​
# 检查 Git
git --version
# 期望输出: git version 2.40.x 或更高

如果任一组件未安装或版本过低：

• Node.js：访问 https://nodejs.org/ 下载 LTS 版本安装

• Git：

  • Windows：下载 Git for Windows（https://git-scm.com/download/win）

  • macOS：brew install git（或系统自带，用 xcode-select --install 更新）

  • Linux：sudo apt install git（Debian/Ubuntu）或 sudo yum install git（RHEL/CentOS）

步骤 2：安装 Claude Code

根据你的操作系统选择对应方式：

方式 A：npm 全局安装（所有平台通用，推荐）

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

安装完成后验证：

claude --version
# 期望输出: v2.1.x 或类似版本号

方式 B：macOS 用 Homebrew

brew install anthropic/tap/claude-code

方式 C：Windows 用 winget

winget install Anthropic.ClaudeCode

三选一即可。npm 方式是最通用的，也是 Anthropic 官方首推的安装方式。

步骤 3：获取并配置 API Key

1. 访问 https://console.anthropic.com/

2. 注册或登录 Anthropic 账号（需要邮箱验证）

3. 进入 API Keys 页面，点击 "Create Key"

4. 复制生成的 Key（格式：sk-ant-xxxx...，注意它只显示一次）

配置 API Key 有两种方式：

方式 A：环境变量（推荐，更安全）

# macOS / Linux（添加到 ~/.bashrc 或 ~/.zshrc）
export ANTHROPIC_API_KEY="sk-ant-你的key"
​
# Windows PowerShell（添加到 $PROFILE）
$env:ANTHROPIC_API_KEY="sk-ant-你的key"

添加后重开终端或执行 source ~/.bashrc（macOS/Linux）使其生效。

方式 B：Claude Code 内置认证

claude login

这个命令会引导你通过 OAuth 流程认证，自动配置 API Key。适合不想手动管理环境变量的用户。

步骤 4：网络连通性说明

Anthropic API 的服务器部署在海外。如果你在访问 api.anthropic.com 时遇到连接超时或无法访问的情况，需要自行解决网络连通性问题。

验证 API 是否可达：

# 在终端中测试 API 连通性
curl -I https://api.anthropic.com/v1/messages

如果收到 HTTP 响应（无论状态码是什么），说明网络连通。如果长时间无响应或提示连接失败，说明当前网络环境无法直接访问，你需要自行解决网络访问问题后再继续。

网络配置属于个人环境问题，不在本教程范围内展开。

步骤 5：验证安装完整性

Claude Code 自带一个诊断命令，可以检查所有配置是否正确：

claude doctor

你会看到类似以下的输出：

Claude Code Doctor
==================
Node.js: v20.11.0 (OK)
npm: v10.2.4 (OK)
Git: v2.43.0 (OK)
API Key: Configured (OK)
API Connectivity: Connected (OK)
Model Access: claude-sonnet-4-20250514 (OK)

确保所有项都显示 (OK)。如果有红色标注的 (FAIL)，根据提示修复对应项目。

常见 doctor 报错和修复：

• API Key: Not configured → 检查环境变量是否正确设置，尝试 echo $ANTHROPIC_API_KEY

• API Connectivity: Connection failed → 检查网络连接，确认能否访问 api.anthropic.com

• Node.js: Version too low → 升级 Node.js 到 18+

---

避坑指南

坑 1：混淆 Claude.ai 订阅和 API Key

这是最高频的新手坑。Claude.ai 的 $20/月 Pro 订阅只适用于网页端使用，API 是完全独立的计费系统。你需要在 console.anthropic.com 单独注册并充值。

识别方法：如果你的 Key 以 sk-ant- 开头，这是 API Key；如果你只有网页登录密码，那不是 API Key。

坑 2：npm 全局安装权限问题

macOS 和 Linux 用户经常会遇到 EACCES 权限错误。

错误信息示例：

npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules

解决方案（推荐使用 nvm 管理 Node.js）：

# 先安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# 重开终端，然后安装 Node
nvm install 20
nvm use 20
# 再安装 Claude Code
npm install -g @anthropic-ai/claude-code

使用 nvm 的好处是 npm 全局包安装在用户目录下，不需要 sudo 权限。

坑 3：Windows 终端编码问题

Windows 用户在 Git Bash 或 PowerShell 中使用 Claude Code 时，偶尔会遇到中文显示乱码。

解决方案：

# 在 PowerShell 中执行
[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

或者在 Windows Terminal（而非 CMD 或旧版 PowerShell）中运行 Claude Code，它对 UTF-8 的支持更好。

坑 4：Windows 终端权限问题

Windows 用户在 PowerShell 中执行 claude login 时，可能会遇到执行策略（Execution Policy）限制。

错误信息示例：

claude : 无法加载文件，因为在此系统上禁止运行脚本

解决方案：以管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

此操作允许运行本地脚本和经过数字签名的远程脚本，是安全的默认设置。

---

课后作业

1. 安装验证：成功运行 claude doctor 并截图保存。确保所有项目显示 (OK)。

2. API 连通性测试：运行 claude --model claude-sonnet-4-20250514 -p "请用一句话介绍你自己"，确认能收到正常回复。

3. 网络排查练习：故意断开网络后运行 claude doctor，观察"API Connectivity"报错信息。然后恢复网络，再次验证。熟悉网络连通性问题的排查流程。

4. 文档阅读：浏览 Anthropic Console 的 Usage 页面（https://console.anthropic.com/settings/usage），了解你的 API 使用量统计界面。

---

总结

Claude Code 的安装本身很简单——本质上就是 npm install -g 加一个 API Key。但对初学者来说，最容易卡住的三个地方是：

1. API Key 获取：需要区分 Claude.ai 订阅和 API 控制台

2. 网络连通性：部分网络环境可能无法直接访问 Anthropic API，需要自行解决

3. 权限问题：npm 全局安装时可能遇到权限错误，nvm 是最佳解决方案

安装完成后运行 claude doctor 验证，确保所有配置正确。如果一切正常，你已经准备好了——下一节我们将进行第一次真正的对话，体验 Claude Code 的核心工作流。