01-Claude-Code入门指南-安装与配置

原创已于 2026-03-06 21:04:02 修改 · 951 阅读

8 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#人工智能 #大模型 #AIGC #Claude #AI

于 2026-03-06 20:55:05 首次发布

Claude Code 专栏收录该内容

10 篇文章

订阅专栏

AI 时代程序员必备技能

Codex、Claude Code、Cursor、Hermes Agent、OpenClaw等工程化实战专栏，讲透 AI 如何接管脏活累活

一键订阅

Claude Code 入门指南：安装与配置

📚 免费专栏全套教程： Claude Code 从入门到精通
✦ 开篇总览｜最新目录： Claude Code 从入门到精通 —带你玩转Claude Code！！

本教程将带你快速了解 Claude Code，从安装配置到实际使用，助你掌握这款强大的 AI 编程助手。

什么是 Claude Code

Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手，基于 Claude 大语言模型构建。它不仅能进行对话问答，还能直接操作你的代码库、执行命令、修改文件，是一个真正意义上的 AI 编程伙伴。

与其他工具的对比

特性	Claude Code	GitHub Copilot	Cursor	ChatGPT
运行环境	命令行	IDE 插件	IDE	网页/App
文件操作	✅ 直接操作	❌	✅	❌
命令执行	✅	❌	✅	❌
全项目理解	✅	部分	✅	❌
自定义工具	✅ MCP 协议	❌	部分	❌
多模型支持	❌ 仅 Claude	❌	✅	❌

核心功能

1. 💬 智能对话

理解代码上下文，提供精准的编程建议
支持多轮对话，记忆上下文信息
支持 Markdown 格式输出

2. 📁 文件操作

读取、创建、编辑文件
自动理解项目结构
支持多种文件格式

3. 🔧 命令执行

执行 Shell 命令
运行测试、构建项目
Git 操作自动化

4. 🧠 上下文记忆

记忆项目约定和风格
理解代码依赖关系
保持会话连续性

5. 🔌 MCP 工具扩展

MCP (Model Context Protocol) 是 Claude Code 的工具扩展协议，允许：

连接数据库
调用外部 API
集成开发工具
自定义工作流

安装步骤

系统要求

系统	最低版本
macOS	12.0 (Monterey)
Linux	Ubuntu 20.04+ / Debian 11+
Windows	Windows 10+ (WSL2 推荐)

前置条件

Node.js 18.0 或更高版本
npm 或 pnpm 包管理器
Anthropic API Key（获取地址）

macOS 安装

方式一：使用 npm（推荐）

# 检查 Node.js 版本
node --version  # 需要 >= 18.0.0

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

# 验证安装
claude --version

方式二：使用 Homebrew

# 添加 tap
brew tap anthropics/claude-code

# 安装
brew install claude-code

# 验证安装
claude --version

方式三：手动下载

# 下载最新版本
curl -fsSL https://claude.ai/code/install.sh | sh

# 或从 GitHub Releases 下载
# https://github.com/anthropics/claude-code/releases

Linux 安装

Ubuntu/Debian

# 安装 Node.js（如果未安装）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

CentOS/RHEL/Fedora

# 安装 Node.js
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

Arch Linux

# 使用 AUR helper
yay -S claude-code

# 或手动安装
npm install -g @anthropic-ai/claude-code

Windows 安装

方式一：WSL2（强烈推荐）

WSL2 提供更好的兼容性和性能：

# 在 PowerShell（管理员）中启用 WSL
wsl --install

# 重启电脑后，安装 Ubuntu
wsl --install -d Ubuntu

# 进入 WSL
wsl

# 在 WSL 中按 Linux 步骤安装
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

方式二：原生 Windows

# 安装 Node.js（使用 winget）
winget install OpenJS.NodeJS.LTS

# 或使用 Chocolatey
choco install nodejs-lts

# 刷新环境变量
refreshenv

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

方式三：使用安装包

访问 GitHub Releases
下载 .msi 安装包
双击安装，按提示完成

配置方法

1. API Key 配置

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

# macOS/Linux - 添加到 ~/.zshrc 或 ~/.bashrc
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your-api-key-here", "User")

# Windows CMD
setx ANTHROPIC_API_KEY "your-api-key-here"

方式二：交互式配置

# 首次运行会引导配置
claude

# 或使用配置命令
claude config set apiKey your-api-key-here

方式三：配置文件

# 创建配置目录
mkdir -p ~/.claude

# 创建配置文件
cat > ~/.claude/config.json << 'EOF'
{
  "apiKey": "your-api-key-here",
  "model": "claude-3-5-sonnet-20241022",
  "maxTokens": 4096
}
EOF

2. 环境变量详解

变量名	说明	默认值
`ANTHROPIC_API_KEY`	Anthropic API 密钥	必填
`CLAUDE_MODEL`	使用的模型	claude-3-5-sonnet-20241022
`CLAUDE_MAX_TOKENS`	最大输出 token 数	4096
`CLAUDE_TEMPERATURE`	生成温度 (0-1)	1.0
`CLAUDE_SYSTEM_PROMPT`	自定义系统提示	-
`CLAUDE_MCP_SERVERS`	MCP 服务器配置	-

完整配置示例

# ~/.zshrc 或 ~/.bashrc

# 必需：API Key
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 可选：模型选择
export CLAUDE_MODEL="claude-3-5-sonnet-20241022"

# 可选：输出限制
export CLAUDE_MAX_TOKENS=8192

# 可选：调试模式
export CLAUDE_DEBUG=true

# 可选：代理设置
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

3. MCP 工具配置

MCP (Model Context Protocol) 允许扩展 Claude Code 的能力：

// ~/.claude/mcp_servers.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/project"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/db"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxx"
      }
    }
  }
}

4. 项目级配置

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

your-project/
├── .claude/
│   ├── CLAUDE.md          # 项目说明给 Claude 看
│   ├── commands/          # 自定义命令
│   └── tools/             # 自定义工具
├── src/
└── package.json

CLAUDE.md 示例

# 项目说明

这是一个 Next.js 电商项目。

## 技术栈
- Next.js 14
- TypeScript
- Tailwind CSS
- Prisma + PostgreSQL

## 代码规范
- 使用函数组件和 Hooks
- 组件文件使用 PascalCase 命名
- 工具函数放在 utils/ 目录

## 注意事项
- 所有 API 路由需要错误处理
- 数据库迁移需要先备份

快速开始

1. 启动 Claude Code

# 在项目目录中启动
cd your-project
claude

# 或指定工作目录
claude --cwd /path/to/project

2. 基础使用示例

示例一：理解项目

你: 请分析这个项目的结构

Claude: 我来帮你分析项目结构...
[读取 package.json, 目录结构等]

这个项目是一个 Next.js 应用，包含以下主要部分：
- /src/app - Next.js App Router 页面
- /src/components - React 组件
- /src/lib - 工具函数和共享代码
...

示例二：创建功能

你: 创建一个用户登录表单组件

Claude: 我来创建登录表单组件...

[创建文件: src/components/LoginForm.tsx]

import { useState } from 'react';

export function LoginForm({ onSubmit }) {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  // ... 组件实现
}

示例三：调试问题

你: 运行测试，如果有失败帮我修复

Claude: 运行测试中...
[执行: npm test]

发现 2 个测试失败，问题在于...

[修复文件: src/utils/validation.ts]
[修复文件: src/components/Form.tsx]

重新运行测试... 全部通过！

示例四：重构代码

你: 将这个组件重构为使用 TypeScript 和自定义 Hooks

Claude: 好的，我来重构...

[修改文件: src/components/UserList.jsx → UserList.tsx]
[创建文件: src/hooks/useUsers.ts]

重构完成：
1. 添加了 TypeScript 类型定义
2. 抽取了 useUsers 自定义 Hook
3. 改进了错误处理

3. 常用命令

命令	说明
`claude`	启动交互式会话
`claude --help`	显示帮助信息
`claude --version`	显示版本号
`claude --model <name>`	指定模型
`claude --no-tools`	禁用工具
`claude --mcp`	启用 MCP 服务器
`/help`	会话内帮助
`/clear`	清除对话
`/exit`	退出会话

4. 快捷键

快捷键	功能
`Ctrl+C`	取消当前输入/操作
`Ctrl+D`	退出会话
`Ctrl+L`	清屏
`↑` / `↓`	浏览历史输入
`Tab`	自动补全

常见问题解答

Q1: API Key 在哪里获取？

A: 访问 Anthropic Console，注册账号后在 API Keys 页面创建新的密钥。

Q2: 如何选择模型？

A: 根据任务选择：

模型	适用场景	相对成本
Claude 3.5 Sonnet	日常开发、复杂推理	中等
Claude 3.5 Haiku	快速响应、简单任务	低
Claude 3 Opus	最高质量、复杂分析	高

# 临时使用其他模型
claude --model claude-3-opus-20240229

Q3: 如何处理网络代理问题？

A: 设置代理环境变量：

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"

Q4: 出现权限错误怎么办？

# macOS/Linux 修复 npm 全局权限
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# 或使用 nvm 管理 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Q5: 如何查看对话历史？

A: 对话历史保存在 ~/.claude/history/ 目录：

# 查看最近的会话
ls -lt ~/.claude/history/

# 查看特定会话
cat ~/.claude/history/session_xxx.json

Q6: Claude Code 会修改我的代码吗？

A: 默认情况下，Claude Code 会：

创建新文件前询问
修改现有文件前询问
执行命令前询问

可以通过 --dangerously-skip-permissions 跳过确认（不推荐）。

Q7: 如何限制 Claude Code 的访问范围？

工作目录限制：只在项目目录中启动
文件权限：配置 .claudeignore 文件

# .claudeignore 示例
.env
*.secret
node_modules/
.git/
*.key

Q8: 如何在 CI/CD 中使用？

# GitHub Actions 示例
- name: Run Claude Code
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    npm install -g @anthropic-ai/claude-code
    claude --non-interactive "Review the PR and suggest improvements"

Q9: 出现 “rate limit exceeded” 错误？

A: API 调用频率超限，解决方案：

等待一段时间后重试
升级 API 套餐
使用退避重试策略

# 配置重试
export CLAUDE_MAX_RETRIES=5
export CLAUDE_RETRY_DELAY=2000  # 毫秒

Q10: 如何更新到最新版本？

# npm 安装的
npm update -g @anthropic-ai/claude-code

# Homebrew 安装的
brew upgrade claude-code

# 查看版本
claude --version

参考资源

AI 时代程序员必备技能

Codex、Claude Code、Cursor、Hermes Agent、OpenClaw等工程化实战专栏，讲透 AI 如何接管脏活累活

一键订阅