垦荒学园

简体中文

English

简体中文

English

切换主题

安装与配置 ​

系统要求 ​

在安装 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 安装（推荐） ​

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

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

# 验证安装
claude --version

方法 2：通过 Homebrew 安装（macOS/Linux） ​

优点： 系统级包管理、易于维护

bash
# macOS
brew install claude-code

# 验证安装
claude --version

方法 3：下载独立可执行文件 ​

优点： 无需 Node.js、开箱即用

Linux:

bash
# 下载最新版本
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64 -o claude

# 添加执行权限
chmod +x claude

# 移动到系统路径
sudo mv claude /usr/local/bin/

# 验证安装
claude --version

macOS:

bash
# Intel 芯片
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-macos-x64 -o claude

# Apple Silicon (M1/M2)
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-macos-arm64 -o claude

# 添加执行权限
chmod +x claude

# 移动到系统路径
sudo mv claude /usr/local/bin/

# 验证安装
claude --version

Windows (WSL2):

bash
# 在 WSL2 终端中执行
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64 -o claude
chmod +x claude
sudo mv claude /usr/local/bin/
claude --version

方法 4：从源码安装（开发者） ​

优点： 最新功能、可自定义修改

bash
# 克隆仓库
git clone https://github.com/anthropics/claude-code.git
cd claude-code

# 安装依赖
npm install

# 构建
npm run build

# 链接到全局
npm link

# 验证安装
claude --version

初次运行 ​

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

步骤 1：运行初始化命令 ​

bash
claude

首次运行时，Claude Code 会：

  1. 检查是否有 API Key 配置
  2. 引导你完成初始设置
  3. 创建配置文件

步骤 2：设置 API Key ​

你会看到类似以下提示：

Welcome to Claude Code! 🎉

No API key found. Please enter your Anthropic API key:
(You can get one from https://console.anthropic.com/)

API Key: _

输入你的 API Key 后按回车。

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

步骤 3：选择默认模型 ​

Which model would you like to use by default?

› Claude Sonnet 4.5 (Recommended - balanced performance and cost)
  Claude Opus 4.5 (Most capable, higher cost)
  Claude Haiku (Fast and economical)

推荐选择 Sonnet 4.5，它在性能和成本之间取得了良好平衡。

步骤 4：配置完成 ​

✓ Configuration saved to ~/.config/claude-code/config.json
✓ Setup complete!

You can now start using Claude Code:
  claude "your task here"

Or enter interactive mode:
  claude

For help, type: claude --help

配置文件位置 ​

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

Linux/macOS ​

~/.config/claude-code/
├── config.json          # 主配置文件
├── mcp-servers.json     # MCP 服务器配置
├── plugins.json         # 插件配置
└── .env                 # 环境变量（可选）

Windows (WSL) ​

/home/username/.config/claude-code/
├── config.json
├── mcp-servers.json
├── plugins.json
└── .env

查看配置文件位置 ​

bash
claude --config-path

编辑配置文件 ​

bash
# 使用默认编辑器打开
claude --edit-config

# 或手动编辑
nano ~/.config/claude-code/config.json

基础配置选项 ​

打开 config.json，你会看到类似以下内容：

json
{
  "api": {
    "key": "sk-ant-xxx",
    "baseUrl": "https://api.anthropic.com"
  },
  "model": {
    "default": "claude-sonnet-4-5",
    "temperature": 0.7,
    "maxTokens": 4096
  },
  "ui": {
    "colorScheme": "auto",
    "showLineNumbers": true,
    "syntaxHighlighting": true
  },
  "security": {
    "sandboxMode": true,
    "confirmCommands": true,
    "allowedDomains": []
  },
  "editor": {
    "default": "nano",
    "openFilesInEditor": false
  }
}

主要配置项说明 ​

配置项说明默认值
api.keyAnthropic API Key无
api.baseUrlAPI 端点 URLhttps://api.anthropic.com
model.default默认使用的模型claude-sonnet-4-5
model.temperature生成温度（0-1）0.7
model.maxTokens最大令牌数4096
ui.colorScheme颜色方案（auto/light/dark）auto
ui.showLineNumbers显示行号true
security.sandboxMode沙盒模式true
security.confirmCommands命令执行前确认true
editor.default默认编辑器nano

常见问题排查 ​

问题 1：命令未找到 ​

错误信息：

claude: command not found

解决方案：

bash
# 检查是否正确安装
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. 重新输入 API Key：
bash
claude --set-api-key

问题 3：网络连接问题 ​

错误信息：

Error: Failed to connect to API

解决方案：

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

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

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

问题 4：权限问题 ​

错误信息：

Error: EACCES: permission denied

解决方案：

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

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

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

错误信息：

Error: Claude Code requires Node.js 18 or higher

解决方案：

bash
# 检查当前版本
node --version

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

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

验证安装 ​

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

bash
# 1. 检查版本
claude --version

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

# 3. 运行简单测试
claude "echo Hello from Claude Code"

# 4. 检查配置
claude --show-config

# 5. 测试 API 连接
claude --test-connection

预期输出：

bash
$ claude --version
Claude Code v1.5.0

$ claude --test-connection
✓ API connection successful
✓ Model: claude-sonnet-4-5 is available
✓ Configuration valid

更新 Claude Code ​

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

npm 安装更新 ​

bash
# 检查当前版本
claude --version

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

# 验证更新
claude --version

Homebrew 更新 ​

bash
brew upgrade claude-code

独立可执行文件更新 ​

bash
# 下载新版本（替换旧版本）
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64 -o claude
chmod +x claude
sudo mv claude /usr/local/bin/

查看更新日志 ​

bash
claude --changelog

卸载 ​

如果需要卸载 Claude Code：

npm 卸载 ​

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

Homebrew 卸载 ​

bash
brew uninstall claude-code

手动卸载 ​

bash
# 删除可执行文件
sudo rm /usr/local/bin/claude

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

# 删除缓存（可选）
rm -rf ~/.cache/claude-code

小结 ​

在本章中，我们学习了：

  • ✅ Claude Code 的系统要求和运行环境
  • ✅ 四种安装方法：npm、Homebrew、独立可执行文件、源码安装
  • ✅ 初次运行配置流程
  • ✅ 配置文件位置和基础选项
  • ✅ 常见问题的排查和解决
  • ✅ 安装验证、更新和卸载方法

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