检查是否已安装#

打开终端，输入：

1
node --version

如果输出 v18.x.x 或更高版本，可以跳过此步骤。

macOS 安装 Node.js#

方法一：使用 Homebrew（推荐）

1
# 安装 Homebrew（如果没有）
2
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3

4
# 安装 Node.js LTS 版本
5
brew install node@22

方法二：直接下载安装包

访问 Node.js 官网 下载 macOS 安装包（.pkg），双击安装即可。

Windows 安装 Node.js#

Claude Code 已原生支持 Windows 10/11，直接在 PowerShell 或 cmd 中使用即可。

方法一：官网下载安装（推荐）

1. 访问 Node.js 官网，下载 Windows 安装包（.msi）
2. 双击运行安装程序，一路点击 Next 即可
3. 安装完成后打开 命令提示符（cmd） 或 PowerShell，验证安装：

1
node --version
2
npm --version

macOS 安装 Claude Code#

方法一：使用 npm（通用）

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

如果遇到权限错误，加 sudo：

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

方法二：使用 Homebrew

1
brew install claude-code

Homebrew 安装的好处是后续更新可以直接 brew upgrade claude-code，统一管理。

Windows 安装 Claude Code#

以 管理员身份 打开 PowerShell，执行：

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

如果遇到权限问题，请确认是以管理员身份运行的 PowerShell。

Linux 安装 Claude Code#

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

如果遇到权限错误（EACCES），加 sudo：

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

验证安装#

安装完成后验证：

1
claude --version

如果输出版本号，说明安装成功。

更新 Claude Code#

Claude Code 更新频繁，建议定期更新：

1
# npm 用户
2
npm update -g @anthropic-ai/claude-code
3

4
# macOS Homebrew 用户
5
brew upgrade claude-code

方案对比#

建议：如果你每天大量使用 Claude Code 进行编程，建议直接上 Max 5x（$100/月），Pro 订阅在高强度使用时会频繁触发限流，体验较差。

如何订阅#

开通 Claude Pro/Max 订阅，推荐直接去闲鱼购买成品号或代充服务，省去外币信用卡的麻烦。

如果想自己操作：

1. 访问 claude.ai
2. 登录你的 Anthropic 账号（没有就注册一个）
3. 点击左下角 头像 → Settings → Subscription
4. 选择 Pro 或 Max 方案，完成支付（需要外币信用卡 Visa / Mastercard）

📱 注册 Claude 需要海外手机号接收验证码。如果没有海外号码，可以使用接码服务：闲鱼接码

登录方式一：浏览器 OAuth 登录（推荐）#

这是最简单的登录方式，适用于 Pro / Max 订阅用户：

1. 终端运行 claude 后，会显示一个 URL
2. 按回车键自动打开浏览器（或手动复制 URL 到浏览器）
3. 在浏览器中登录你的 Claude 账号
4. 授权 Claude Code 访问你的账号
5. 浏览器显示「Authorization successful」，回到终端即可使用

1
┌──────────────────────────────────────────┐
2
│ ✻ Welcome to Claude Code!               │
3
│                                          │
4
│   To get started, log in to your         │
5
│   Anthropic account.                     │
6
│                                          │
7
│   Press Enter to open the browser...     │
8
└──────────────────────────────────────────┘

登录方式二：API Key 登录#

如果你使用 API Key（按量付费），可以通过环境变量设置：

1
# 临时设置（当前终端会话有效）
2
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
3
claude
4

5
# 或者写入配置文件永久生效
6
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx' >> ~/.bashrc
7
source ~/.bashrc

API Key 在 Anthropic Console → API Keys 页面创建。

⚠️ 注意：API Key 是按 token 计费的，大量使用可能产生较高费用。建议先在 Console 设置 Usage Limit（用量上限）。

基础对话#

直接用自然语言描述你想做的事情：

1
> 帮我看看这个项目的整体结构
2

3
> 找到所有处理用户认证的代码
4

5
> src/api/auth.ts 这个文件是做什么的？

代码编辑#

Claude Code 可以直接修改你的文件：

1
> 给 login 函数添加参数校验
2

3
> 把这个组件从 class 组件重构为 hooks
4

5
> 修复 useEffect 的依赖项警告

修改前 Claude Code 会展示 diff，你确认后才会写入文件。

终端命令#

Claude Code 可以执行终端命令：

1
> 运行测试看看有没有失败的
2

3
> 安装 axios 依赖
4

5
> 构建项目并检查是否有报错

Git 操作#

1
> 提交当前的修改，写一个合适的 commit message
2

3
> 创建一个新分支叫 feature/user-auth
4

5
> 帮我创建一个 PR，描述这次的改动

命令行参数#

Claude Code 也支持直接在终端中传入参数执行单次任务：

1
# 非交互模式：执行单条指令后退出
2
claude -p "解释这个项目的目录结构"
3

4
# 继续上次的对话
5
claude --continue
6

7
# 从上次对话继续，并追加新指令
8
claude --continue "接着上次的，现在把测试也写了"
9

10
# 指定模型
11
claude --model opus
12
claude --model sonnet

1. 大型任务分步执行#

不要一次给出过于复杂的指令，拆分成多个小步骤效果更好：

1
# ❌ 不推荐
2
> 帮我重构整个认证系统，加上 JWT、刷新令牌、权限管理、日志记录
3

4
# ✅ 推荐
5
> 先帮我看看当前的认证逻辑是怎么实现的
6
> 现在把 session 认证改为 JWT
7
> 加上 refresh token 机制
8
> 最后给关键操作加上日志

2. 提供上下文#

告诉 Claude Code 相关的文件和背景，能让它更准确地完成任务：

1
> 参考 src/api/users.ts 的风格，给 products 写一套类似的 CRUD API

3. 让 Claude Code 先分析再动手#

对于不确定的修改，先让它分析方案：

1
> 不要改代码，先告诉我你打算怎么修复这个 bug

4. 善用 /compact#

长对话会消耗大量上下文窗口。当你觉得对话变长时，使用 /compact 压缩历史，Claude Code 会保留关键信息并释放空间。

400 Bad Request#

报错信息：

1
Error: 400 {"type":"error","error":{"type":"invalid_request_error",
2
"message":"model: invalid model id"}}

或：

1
Error: 400 invalid_request_error
2
  Could not process the request. Please check your input and try again.

原理解析：

400 表示 请求本身有问题，服务器收到请求也认你的身份，但请求内容不符合 API 规范。

解决方案：

1
# 1. 最常见原因：版本过旧，更新到最新版
2
npm update -g @anthropic-ai/claude-code
3

4
# 2. 确认模型名称正确
5
claude --model sonnet    # ✅
6
claude --model opus      # ✅
7
claude --model cluade    # ❌ 拼写错误
8

9
# 3. 清除缓存重新登录
10
rm -rf ~/.claude/projects/
11
claude login

401 Unauthorized#

报错信息：

1
Error: 401 Unauthorized
2

3
  Invalid authorization header. Please ensure your API key
4
  or session token is correct.

或：

1
Error: 401 {"type":"error","error":{"type":"authentication_error",
2
"message":"invalid x-api-key"}}

原理解析：

401 是 服务器不认你的身份，和 403（有身份但被拒绝访问）不同：

1
请求 ──→ Anthropic API
2
             │
3
        检查认证信息
4
             │
5
     ┌───────┴───────┐
6
   有凭据           无凭据/凭据无效
7
     │                    │
8
  继续处理(→403等)   直接拒绝(401)

解决方案：

1
# API Key 用户：检查 Key 是否正确
2
echo $ANTHROPIC_API_KEY
3
# 确认以 sk-ant- 开头，没有多余空格
4

5
# 测试 Key 是否有效
6
curl -s https://api.anthropic.com/v1/messages \
7
  -H "x-api-key: $ANTHROPIC_API_KEY" \
8
  -H "anthropic-version: 2023-06-01" \
9
  -H "content-type: application/json" \
10
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}' \
11
  | head -c 200
12

13
# OAuth 用户：重新登录
14
claude login
15

16
# 检查环境变量是否被多处覆盖
17
grep -n "ANTHROPIC_API_KEY" ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

403 Forbidden#

报错信息：

1
Error: 403 Forbidden
2

3
  API Error: Your request was rejected by our safety systems.

原理解析：

403 是国内用户遇到的 最高频报错。不是密码错、不是账号封禁，而是 IP 被风控拦截：

1
你的终端 ──→ 直连/机房IP ──→ Anthropic API
2
                                   │
3
                              风控检测 IP 类型
4
                                   │
5
                              判定为异常 → 403

解决方案：

开启 TUN 模式 + 使用 纯净住宅 IP。

完整原理分析和解决步骤见：Claude Code 报错 403 的原理与解决办法

429 Too Many Requests（限流）#

报错信息：

1
Error: 429 Too Many Requests
2

3
  Rate limit exceeded. You've sent too many requests.

或 Pro 用户常见的：

1
⚠ You've hit your usage limit. Your limit will reset in 3 hours.
2
  Upgrade to Max for higher limits: https://claude.ai/settings

原理解析：

Anthropic 对每个订阅等级设置了用量上限：

限流不是封号，等冷却期后自动恢复。

解决方案：

• Pro 用户：等待 reset（2-5 小时），或升级 Max
• Max 用户：等待 reset（1-2 小时），或 /model sonnet 切换模型（额度独立）
• API 用户：降低请求频率，或在 Console 申请提升限额

技巧：Pro 经常触发限流说明该升级了。$100/月的 Max 5x 性价比最高。

网络连接错误#

报错信息：

1
Error: fetch failed
2
  cause: ConnectTimeoutError: Connect Timeout Error

1
Error: getaddrinfo ENOTFOUND api.anthropic.com

1
Error: connect ETIMEDOUT 104.18.xx.xx:443

原理解析：

解决方案：

1
# 测试连通性
2
curl -v https://api.anthropic.com 2>&1 | head -20
3

4
# 确认出口 IP 是否走了代理
5
curl https://api.ip.sb/ip

国内 api.anthropic.com 大概率无法直连，必须代理。推荐 TUN 模式。

500 / 529 服务端错误#

报错信息：

1
Error: 500 Internal Server Error

1
Error: 529 API Overloaded
2
  The API is temporarily overloaded.

原理解析：

解决方案：

• 等几秒到几分钟重试
• 查看 Anthropic 状态页 确认是否服务异常
• 高峰期（北美工作时间）可换时段使用

报错速查表#

Q: 响应很慢或经常超时？#

• 检查网络连接是否稳定
• 使用 /fast 切换快速模式
• 如果使用代理，确保代理节点延迟较低
• 大文件或大项目首次分析会较慢，后续会利用缓存

Q: Max 订阅和 API Key 哪个划算？#

Max 订阅的优势是 费用可预测，不管用多少都是固定月费；API Key 灵活但可能在不注意时产生高额费用。

Q: Windows 上可以直接用吗？#

可以。Claude Code 已原生支持 Windows 10/11，在 PowerShell 或命令提示符中安装即可使用，无需额外配置。