第 2 章安装与环境配置第 2 章安装与环境配置 ← 上一章 | 下一章 → 本章目标选择一个合适的安装方式完成

第 2 章安装与环境配置

本章目标

选择一个合适的安装方式完成 Claude Code 安装
获取并正确配置 Anthropic API Key
安装 IDE 扩展（VS Code / JetBrains）
验证安装成功并完成首次运行
排查常见安装问题

2.1 三种安装方式

Claude Code 提供三种官方安装途径，按推荐顺序排列。

方式一：npm 全局安装（推荐）

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

前置条件：Node.js 18+ 和 npm 9+。如果尚未安装，先到 nodejs.org 下载 LTS 版本。

安装完成后验证：

claude --version

预期输出类似：claude-code/1.0.x (darwin-arm64, node v20.x.x)

⚠️ 在 Windows 上使用 npm 全局安装时，如果遇到 PowerShell 执行策略限制，请切换到 Git Bash 或 WSL 终端。详见本章 2.5 节。

方式二：Homebrew 安装（macOS / Linux）

brew install claude-code

Homebrew 会自动处理依赖关系。更新到最新版本时使用：

brew upgrade claude-code

方式三：Docker 安装

docker pull anthropic/claude-code
docker run -it --rm -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY anthropic/claude-code

Docker 方式的好处是完全隔离，不会影响宿主机环境。适合试用的场景。但要注意，容器内默认无法访问宿主机的项目文件，需要通过 Volume 挂载：

docker run -it --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/workspace \
  -w /workspace \
  anthropic/claude-code

2.2 获取 API Key

Claude Code 需要 Anthropic API Key 才能工作。

步骤：

访问 Anthropic Console
注册或登录 Anthropic 账号
进入 API Keys 页面
点击 Create Key，填入名称（如 claude-code-local）
立即复制生成的 Key —— 关闭页面后将无法再次查看

⚠️ API Key 一旦离开控制台就无法再次查看。务必在生成时立即保存到安全的位置。

配置 API Key

方式一：环境变量（推荐）

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

将上述命令添加到 Shell 配置文件中以持久化：

Bash: ~/.bashrc 或 ~/.bash_profile
Zsh: ~/.zshrc
Fish: ~/.config/fish/config.fish

方式二：Claude Code 配置

Claude Code 启动后会自动检测以下位置的 API Key：

环境变量 ANTHROPIC_API_KEY
环境变量 ANTHROPIC_AUTH_TOKEN（向后兼容）
交互式登录（claude login）

💡 如果你同时使用多个 Anthropic API 项目，可以用不同的环境变量切换，或者在不同项目目录下使用 .env 文件（需配合 direnv 等工具）。

2.3 IDE 扩展安装

Claude Code 支持在 VS Code 和 JetBrains 系列 IDE 中直接使用。

VS Code 扩展

打开 VS Code，进入扩展面板（Ctrl+Shift+X / Cmd+Shift+X）
搜索 "Claude Code"
点击 Install
安装后，使用 Ctrl+Shift+P / Cmd+Shift+P 打开命令面板
输入 "Claude Code" 查看可用命令

主要功能入口：

Toggle Claude Code Panel：打开/关闭 Claude Code 侧边面板
Claude Code: Inline Edit：选中代码后内联编辑
Claude Code: Open in Terminal：在终端中打开 Claude Code

💡 VS Code 扩展模式下，Claude Code 可以直接读取你在 IDE 中打开的文件和光标位置，无需手动描述"帮我改第 x 行"。

JetBrains 扩展

打开 IDE（IntelliJ IDEA / PyCharm / WebStorm 等）
进入 Settings → Plugins → Marketplace
搜索 "Claude Code"
点击 Install
安装完成后，IDE 右侧会出现 Claude Code 工具窗口

2.4 验证安装

运行以下命令确认安装成功：

# 检查版本
claude --version

# 在项目目录中启动
cd /path/to/your/project
claude

首次启动时，Claude Code 会：

检测 API Key 是否有效
在当前项目目录创建 .claude/ 配置目录（如果不存在）
读取项目文件，建立上下文
显示对话界面，等待你的第一条消息

试试第一条消息：

请帮我了解一下这个项目：它是什么技术栈，主要目录结构是怎样的？

如果 Claude Code 能正常分析并回复，恭喜，安装成功。

2.5 常见安装问题

Windows 平台

问题	解决方案
PowerShell 执行策略阻止 npm 全局安装	切换到 Git Bash 或 WSL 终端
中文路径导致编码错误	设置终端编码 `chcp 65001`（UTF-8）
`claude` 命令不识别	检查 npm 全局安装路径是否在 `PATH` 中
Git 未安装	Claude Code 依赖 Git，安装 Git for Windows

macOS 平台

问题	解决方案
Homebrew 找不到 `claude-code`	运行 `brew update` 更新 formula 索引
npm 权限不足	不要用 `sudo npm install`，配置 npm 前缀目录
终端权限弹窗	在系统设置中允许终端访问文件系统

Linux 平台

问题	解决方案
Node.js 版本过低	使用 `nvm` 安装 Node.js 18+ 版本
npm 全局安装后命令不识别	检查 `~/.npm-global/bin` 是否在 `PATH` 中
缺少 build-essential	Ubuntu/Debian 运行 `sudo apt install build-essential`

API 连接问题

问题	解决方案
`401 Unauthorized`	API Key 无效或已过期，去 Console 重新生成
`403 Forbidden`	API Key 没有 Claude Code 访问权限（检查 Workspace 权限设置）
`Connection timeout`	检查网络是否需要代理
`SSL certificate error`	检查系统时间和代理证书配置

代理配置

如果处于需要代理的网络环境：

# HTTP 代理
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

# 或者直接配置在 Claude Code 配置中
# ~/.claude/settings.json
{
  "env": {
    "HTTP_PROXY": "http://proxy.example.com:8080",
    "HTTPS_PROXY": "http://proxy.example.com:8080"
  }
}

💡 安装完成后，建议立即写一个简单的 CLAUDE.md（哪怕只有两行），让 Claude Code 了解你的项目背景。这会显著提升后续对话的质量。

本章要点回顾

Claude Code 提供 npm（推荐通用方式）、Homebrew（macOS/Linux）和 Docker（隔离环境）三种安装方式
API Key 需在 Anthropic Console 生成并通过环境变量或配置文件注入
VS Code 和 JetBrains 均有官方扩展，IDE 模式下能更好地理解编辑上下文
安装后运行 claude --version 和一条简单对话即可验证安装
Windows 用户推荐使用 Git Bash 或 WSL；需代理的环境通过 HTTP_PROXY 配置

第 2 章 安装与环境配置