Claude Code 安装配置完全指南

什么是 Claude Code

Claude Code 是 Anthropic 公司推出的命令行 AI 编程助手工具。与传统的 IDE 插件不同，它是一个独立运行的 CLI 工具，通过终端与开发者进行交互，能够直接操作文件、执行命令、生成代码。

核心特点

本地优先：代码在本地处理，隐私安全有保障
命令行驱动：通过终端交互，支持脚本自动化
多语言支持：支持主流编程语言和框架
工具集成：可调用文件操作、终端命令、Web 搜索等工具

适用场景

推荐使用：

代码重构和批量处理
CI/CD 自动化集成
远程服务器开发
企业级开发（私有部署）

其他选择：

日常开发可考虑 Cursor 等 IDE 集成工具
初学者建议先熟悉基础编程再使用

系统要求

基本要求

| 项目 | 最低配置 | 推荐配置 | |------|---------|---------| | 操作系统 | Windows 10 / macOS 10.15+ / Linux | Windows 11 / macOS 13+ | | 内存 | 4GB RAM | 8GB RAM | | 网络 | 能访问外网 | 稳定网络连接 |

快速检查

# 检查网络连通性
ping api.anthropic.com

安装方式

Claude Code 提供两种安装方式：原生安装和 npm 安装。

方式一：原生安装（推荐）

原生安装是官方推荐的安装方式，无需 Node.js 环境，安装过程更简单快捷。

macOS / Linux

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

Windows PowerShell

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

使用包管理器

Homebrew (macOS/Linux):

brew install --cask claude-code

WinGet (Windows):

winget install Anthropic.ClaudeCode

方式二：npm 安装

如果你已有 Node.js 18+ 环境，也可以通过 npm 安装：

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

验证安装

# 检查版本
claude --version

# 查看帮助
claude --help

API Key 配置

获取 API Key

访问 Anthropic Console
注册并登录账号
进入 Settings → API Keys
创建新的 API Key
复制并妥善保存（只显示一次）

配置环境变量

Windows (PowerShell)

# 永久配置
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-你的key', 'User')

# 验证
$env:ANTHROPIC_API_KEY

macOS / Linux

# 编辑配置文件
nano ~/.zshrc  # 或 ~/.bashrc

# 添加以下行
export ANTHROPIC_API_KEY="sk-ant-api03-你的key"

# 使配置生效
source ~/.zshrc

安全注意事项

✅ 使用环境变量存储 API Key
✅ 不要将 Key 提交到代码仓库
✅ 定期轮换 API Key
❌ 不要在代码中硬编码 Key
❌ 不要在公开场合分享 Key

PATH 环境变量配置

Windows 配置

原生安装后，需要将安装目录添加到 PATH：

方法一：PowerShell 命令

[System.Environment]::SetEnvironmentVariable(
    'Path',
    [System.Environment]::GetEnvironmentVariable('Path', 'User') + ';' + "$env:USERPROFILE\.local\bin",
    'User'
)

方法二：图形界面

Win + R → 输入 sysdm.cpl
高级 → 环境变量
用户变量 → Path → 编辑
新建 → 添加 %USERPROFILE%\.local\bin
确定保存

macOS / Linux 配置

# 添加到配置文件
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

首次启动

基本启动

# 进入项目目录
cd /path/to/your/project

# 启动 Claude Code
claude

启动参数

# 直接提问模式
claude -p "你的问题"

# 跳过权限确认（谨慎使用）
claude --dangerously-skip-permissions

# 指定模型
claude --model opus

初始化配置

首次启动时会进行交互式配置：

选择主题：Light / Dark / System
安全须知确认：了解权限范围
目录信任确认：确认工作目录
认证方式选择：API Key / App Login

IDE 集成

VS Code 集成

安装扩展

打开 VS Code 扩展市场
搜索 "Claude Code"
安装 Anthropic 官方扩展

配置 Tasks

创建 .vscode/tasks.json：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Claude Code: 启动",
      "type": "shell",
      "command": "claude",
      "problemMatcher": [],
      "presentation": {
        "reveal": "always",
        "focus": true
      }
    },
    {
      "label": "Claude Code: 审查文件",
      "type": "shell",
      "command": "claude \"Review ${relativeFile}\"",
      "problemMatcher": []
    }
  ]
}

配置快捷键

创建 .vscode/keybindings.json：

[
  {
    "key": "ctrl+shift+c",
    "command": "workbench.action.tasks.runTask",
    "args": "Claude Code: 启动"
  }
]

Cursor 集成

Cursor 的配置与 VS Code 完全相同，可以直接复用上述配置。

模型配置

可用模型

| 模型别名 | 说明 | 适用场景 | |---------|------|---------| | sonnet | 最新 Sonnet 模型 | 日常编码 | | opus | 最新 Opus 模型 | 复杂推理 | | haiku | 轻量快速模型 | 简单任务 | | opusplan | 规划用 Opus，执行用 Sonnet | 复杂任务 |

切换模型

# 启动时指定
claude --model opus

# 会话中切换
/model sonnet

配置文件

在项目根目录创建 .claude/config.json：

{
  "model": "sonnet",
  "effortLevel": "medium",
  "availableModels": ["sonnet", "opus", "haiku"]
}

常见问题

命令找不到

症状： claude: command not found

解决方案：

检查安装是否成功
确认 PATH 环境变量配置
重启终端窗口

API Key 无效

症状： authentication_error

解决方案：

检查 Key 格式是否正确
确认 Key 未过期或被删除
重新生成并配置新 Key

网络连接失败

症状： Failed to connect

解决方案：

检查网络连接
配置代理（如需要）
检查防火墙设置

权限被拒绝

症状： permission denied

解决方案：

Windows: 以管理员身份运行
macOS/Linux: 检查文件权限，避免使用 sudo

最佳实践

安全使用

目录隔离：在项目目录中启动，避免在系统目录使用
权限控制：谨慎使用 --dangerously-skip-permissions
代码备份：使用 Git 管理代码，随时可回滚
敏感数据：使用 .claudeignore 排除敏感文件

性能优化

减少上下文：使用 .claudeignore 排除无关文件
网络优化：配置代理提升访问速度
模型选择：根据任务复杂度选择合适模型

工作流建议

先规划后执行：复杂任务使用 opusplan 模型
分步验证：重要修改分步进行并验证
保持沟通：清晰描述需求，及时反馈结果

下一步

安装配置完成后，你可以：

学习 Claude Code 的基础使用方法
了解 Commands 系统和自定义命令
探索 MCP 集成和扩展功能
掌握 Hooks 系统实现自动化

参考资源

更新日期： 2026年4月29日
适用版本： Claude Code v2.1.92+

Claude Code 安装配置完全指南

分享这篇文章