#安装与配置

#系统要求

在安装 Claude Code 之前，请确保你的系统满足以下要求：

#操作系统

• ✅ Linux（推荐）
• ✅ macOS（推荐）
• ✅ Windows（通过 WSL2）

#运行环境（二选一）

方案 1：Node.js 环境

• Node.js 18.0.0 或更高版本
• npm 或 yarn 包管理器

方案 2：独立可执行文件

• 无需 Node.js
• 直接下载对应平台的二进制文件

#其他要求

• 至少 2GB 可用内存
• 稳定的网络连接（用于 API 调用）
• 命令行终端（Terminal/iTerm2/Windows Terminal 等）
• Anthropic API Key（第三章详细说明）

#安装方法

Claude Code 提供多种安装方式，选择最适合你的方法：

#方法 1：通过 npm 安装（推荐）

优点： 易于更新、跨平台、自动管理依赖

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

# 验证安装
claude --version

#方法 2：原生安装脚本（无需 Node.js）

优点： 不依赖 Node.js、自动选择对应平台的二进制、自带自更新

macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash

# 验证安装
claude --version

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

# 验证安装
claude --version

#方法 3：IDE 扩展与桌面应用

除了命令行，Claude Code 还提供：

• VS Code 扩展： 在 VS Code 扩展市场搜索 "Claude Code" 安装，可在编辑器侧边栏中直接使用
• JetBrains 插件： 支持 IntelliJ IDEA、PyCharm、WebStorm 等
• 桌面应用： macOS 和 Windows 桌面客户端，适合管理多个并行会话

提示： 不存在官方的 brew install claude-code 安装方式，也无法从源码构建（仓库 anthropics/claude-code 主要用于问题反馈与文档）。请使用 npm 或上面的原生安装脚本。

#初次运行

安装完成后，让我们进行初次运行配置：

#步骤 1：在项目目录中启动

cd your-project
claude

首次运行时，Claude Code 会引导你完成：

1. 选择界面主题（深色/浅色等）
2. 登录账号：可以选择 Claude 订阅账号（Pro/Max 套餐，浏览器 OAuth 登录）或 Anthropic Console 账号（按 API 用量计费）
3. 信任当前目录：确认是否允许 Claude Code 读取该项目的文件

#步骤 2：登录方式说明

两种登录方式的区别：

也可以跳过登录流程，直接通过环境变量提供 API Key：

export ANTHROPIC_API_KEY=sk-ant-xxx
claude

注意： 如果还没有 API Key，请查看下一章（第三章）了解如何获取。

#步骤 3：开始使用

# 交互模式
claude

# 直接执行一次性任务（打印结果后退出）
claude -p "解释这个项目的结构"

# 会话内随时可用 /help 查看可用命令

#配置文件位置

Claude Code 的配置文件存储在以下位置：

~/.claude/                    # 用户级配置目录
├── settings.json             # 用户设置（模型、权限、环境变量等）
├── CLAUDE.md                 # 全局记忆/指令文件
├── commands/                 # 自定义斜杠命令
└── agents/                   # 自定义子代理

项目目录/
├── .claude/settings.json        # 项目共享设置（可提交到 git）
├── .claude/settings.local.json  # 项目个人设置（不提交）
├── .mcp.json                    # 项目 MCP 服务器配置
└── CLAUDE.md                    # 项目记忆/指令文件

#编辑配置

# 会话内使用 /config 打开设置界面
claude
> /config

# 或手动编辑
nano ~/.claude/settings.json

#基础配置选项

打开 ~/.claude/settings.json，常见配置如下：

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Bash(npm run test:*)"],
    "deny": ["Read(./.env)"]
  },
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

#主要配置项说明

完整配置项参考官方设置文档。

#常见问题排查

#问题 1：命令未找到

错误信息：

claude: command not found

解决方案：

# 检查是否正确安装
npm list -g @anthropic-ai/claude-code

# 检查 PATH 环境变量
echo $PATH

# 如果使用独立可执行文件，确保在正确位置
which claude

# 重新安装
npm install -g @anthropic-ai/claude-code

#问题 2：API Key 无效

错误信息：

Error: Invalid API key

解决方案：

1. 验证 API Key 格式（应以 sk-ant- 开头）
2. 检查 Key 是否已过期
3. 确认账户余额充足
4. 重新登录或更新 Key：

# 会话内重新登录
claude
> /login

# 或更新环境变量中的 Key
export ANTHROPIC_API_KEY=sk-ant-new-key

#问题 3：网络连接问题

错误信息：

Error: Failed to connect to API

解决方案：

# 检查网络连接
ping api.anthropic.com

# 检查代理设置（如果使用代理）
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 设置代理（如需要）
export HTTPS_PROXY=http://proxy.example.com:8080

#问题 4：权限问题

错误信息：

Error: EACCES: permission denied

解决方案：

# Linux/macOS - 修复权限
sudo chown -R $(whoami) ~/.claude

# 或使用 npx 运行（不需要全局安装）
npx @anthropic-ai/claude-code "your task"

#问题 5：Node.js 版本过低

错误信息：

Error: Claude Code requires Node.js 18 or higher

解决方案：

# 检查当前版本
node --version

# 使用 nvm 更新 Node.js
nvm install 18
nvm use 18

# 或下载独立可执行文件（无需 Node.js）

#验证安装

完成安装后，运行以下命令验证一切正常：

# 1. 检查版本
claude --version

# 2. 查看帮助信息
claude --help

# 3. 运行简单测试（一次性任务）
claude -p "say hello"

# 4. 检查配置
claude config list

# 5. 健康检查（诊断安装与连接问题）
claude doctor

预期输出：

$ claude --version
2.x.x (Claude Code)

$ claude doctor
✓ Installation healthy
✓ Auth configured

#更新 Claude Code

保持 Claude Code 更新以获得最新功能和修复：

#npm 安装更新

# 检查当前版本
claude --version

# 更新到最新版本
npm update -g @anthropic-ai/claude-code

# 验证更新
claude --version

#原生安装更新

# 原生安装脚本版本自带自更新，也可手动触发
claude update

#查看更新日志

参考官方仓库的 CHANGELOG。

#卸载

如果需要卸载 Claude Code：

#npm 卸载

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

#原生安装卸载

# 删除可执行文件与安装目录
rm -rf ~/.local/bin/claude ~/.local/share/claude

# 删除配置文件（可选）
rm -rf ~/.claude ~/.claude.json

#小结

在本章中，我们学习了：

• ✅ Claude Code 的系统要求和运行环境
• ✅ 安装方法：npm、原生安装脚本、IDE 扩展与桌面应用
• ✅ 初次运行配置流程
• ✅ 配置文件位置和基础选项
• ✅ 常见问题的排查和解决
• ✅ 安装验证、更新和卸载方法

现在你已经成功安装了 Claude Code！