01-Claude Code 快速上手

本指南帮助你在 30 分钟内掌握 Claude Code CLI 的基本使用。

---

一、安装与配置

1.1 环境要求

• Node.js 18.0 或更高版本
• npm 或 yarn 包管理器
• Git (可选，用于代码管理)

1.2 安装 Claude Code

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

# 验证安装
claude --version

1.3 配置 API Key

# 方式1：环境变量
export ANTHROPIC_API_KEY=your-api-key-here

# 方式2：配置文件
# 创建 ~/.config/claude/settings.json (Claude Code 2.1.81+ 新路径)
# Windows: %APPDATA%\claude\settings.json
# macOS/Linux: ~/.config/claude/settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "your-api-key-here"
  }
}

---

二、启动与基本操作

2.1 启动方式

# 方式1：在项目目录启动
cd /path/to/your/project
claude

# 方式2：指定项目路径启动
claude /path/to/your/project

# 方式3：指定模型启动
claude --model claude-sonnet-4-20250514

2.2 首次启动配置

首次启动时会询问：
1. 是否同意使用条款 → 输入 yes
2. API Key 设置（如未设置环境变量）
3. 项目初始化确认

2.3 基本界面

┌─────────────────────────────────────────────────┐
│  Claude Code v2.1.81                             │
│  Project: /path/to/project                     │
│  Model: claude-sonnet-4-20250514               │
├─────────────────────────────────────────────────┤
│  > 你的输入在这里                                │
│                                                 │
│  Claude:                                        │
│  这里是 AI 的回复内容                            │
│                                                 │
├─────────────────────────────────────────────────┤
│  命令: /help /status /clear /compact /exit       │
└─────────────────────────────────────────────────┘

---

三、在 VSCode 中使用 Claude Code

Claude Code 2.1.81+ 支持与 VSCode 深度集成，提供更便捷的编辑体验。

3.1 安装 VSCode 扩展

# 方式1：通过 VSCode 扩展市场
# 在 VSCode 中按 Ctrl+Shift+X (Cmd+Shift+X on macOS)
# 搜索 "Claude Code"
# 点击安装 Anthropic 官方扩展

# 方式2：命令行安装
> code --install-extension anthropic.claude-code

3.2 启动 Claude Code 面板

# 方式1：命令面板
Ctrl+Shift+P (Cmd+Shift+P) → 输入 "Claude Code: Open"

# 方式2：快捷键
Ctrl+Shift+C (Cmd+Shift+C) - 打开 Claude Code 面板

# 方式3：侧边栏
点击左侧活动栏的 Claude Code 图标

3.3 VSCode 集成特性

特性	说明	快捷键
内联编辑	直接在编辑器中接收 AI 建议	Alt+C
文件引用	使用 @ 引用当前工作区文件	@文件名
代码选择	选中代码后右键发送到 Claude	右键菜单
终端集成	在 VSCode 终端中运行 Claude	Ctrl+`
diff 查看	自动显示代码修改对比	自动弹出

3.4 VSCode 配置示例

// .vscode/settings.json
{
  "claude-code.enabled": true,
  "claude-code.autoStart": false,
  "claude-code.defaultModel": "claude-sonnet-4-20250514",
  "claude-code.editor": "vscode",
  "claude-code.confirmDestructiveOperations": true
}

---

四、基础命令

4.1 内置命令

命令	功能	示例
/help	显示帮助信息	/help
/status	查看当前配置	/status
/clear	清除对话历史	/clear
/compact	压缩对话历史	/compact
/exit	退出 Claude Code	/exit 或 Ctrl+C

4.2 文件操作命令

# 读取文件
> 读取 src/main.py 的内容

# 查看目录
> 列出 src/ 目录下的所有文件

# 文件搜索
> 搜索项目中所有使用 User 类的地方

4.3 代码操作命令

# 解释代码
> 解释 src/utils.py 中的 process_data 函数

# 生成代码
> 在 src/models/ 下创建一个 User 类，包含 id, name, email 字段

# 修改代码
> 将 src/main.py 中的 print 语句改为 logging

4.4 终端命令

# Claude Code 可以直接执行终端命令
> 运行 npm install
> 执行 pytest
> 查看 git status

---

五、斜杠命令详解（Claude Code 2.1.81 完整版）

Claude Code 的斜杠命令是效率神器，以下命令按使用频率和用途分类整理。

5.1 基础常用命令 - 日常开发高频使用

命令	功能	使用场景
/help	查看所有命令用法	新手入门、忘记命令时
/clear	一键清空对话历史	切换项目、清理杂乱对话
/cost	查看 Token 消耗和预估费用	使用 Opus 等高阶模型时把控成本
/status	查会话状态、模型、上下文长度	排查卡顿、忘需求问题

示例:

# 查看费用（使用 Opus 时特别重要）
> /cost

# 输出示例：
# 当前会话 Token: 15,234 / 200,000
# 预估费用: $0.023
# 模型: claude-sonnet-4-20250514

5.2 模型与上下文管理 - 让 AI 代码不跑偏

命令	功能	使用场景
/model [名称]	按任务选模型	复杂架构用 Opus，简单任务用 Sonnet
/compact [说明]	压缩上下文保留核心内容	对话太长、AI 卡顿
/context	查看 AI 记住的需求	防止遗漏关键要求
/rewind	回退上一步撤销回答	代码出错、逻辑不对
/forget	删除无关测试代码、无效对话	避免干扰当前开发

示例:

# 切换模型
> /model opus
已切换到 claude-opus-4-20250514

# 压缩上下文
> /compact 保留后端核心逻辑
对话已压缩。要点总结：
- 项目：FastAPI Web 应用
- 当前任务：添加用户认证
- 下一步：JWT 集成

# 回退错误
> /rewind
已回退到上一步。请重新描述需求。

5.3 项目与代码核心命令 - 程序员必学

命令	功能	使用场景
/init	初始化项目结构，生成记忆文件	新建项目第一步
/memory	更新记忆文件中的项目需求、技术栈	需求变更时同步
/diff	查看代码修改差异	确认改动是否合规
/review	自动审查代码，找语法错误、逻辑漏洞	代码审查阶段
/simplify	一键精简代码，剔除无用代码	代码冗余、嵌套复杂
/test	自动生成测试用例并运行	验证功能是否正常
/todo	生成项目待办清单	梳理开发任务
/doctor	自动诊断项目问题	环境报错、依赖缺失

示例:

# 初始化项目
> /init
已创建 CLAUDE.md 记忆文件
已配置项目结构
已记录技术栈偏好

# 代码审查
> /review src/auth.py
代码审查报告：
✓ 语法检查：通过
⚠ 建议优化：第 45 行可简化
✗ 问题发现：第 78 行缺少异常处理

# 生成待办
> /todo 实现用户注册功能
待办清单：
☐ 1. 设计 User 数据模型
☐ 2. 实现注册 API 路由
☐ 3. 添加邮箱验证逻辑
☐ 4. 编写单元测试

5.4 辅助配置命令 - 用着更顺手

命令	功能	使用场景
/btw [问题]	开发中途问小问题，不打断主线任务	临时查询
/break	暂停任务，回来直接接续	中途有事、开会
/config	自定义代码缩进、字体、默认模型	个性化设置
/vim	开启 Vim 键位	Vim 用户适用

示例:

# 临时提问
> /btw Python 中 datetime 怎么转字符串？
（回答后自动回到主线任务）

# 配置编辑器
> /config editor vscode
已设置默认编辑器为 VSCode

# 开启 Vim 模式
> /vim
已启用 Vim 键位绑定

5.5 自定义命令 - 打造专属工具

Claude Code 支持自定义斜杠命令。将常用的代码规范写成 .md 文件，存到指定目录，输入 /文件名 即可一键调用。

配置步骤:

# 1. 创建自定义命令目录
mkdir -p ~/.config/claude/commands/

# 2. 创建自定义命令文件
cat > ~/.config/claude/commands/api.md << 'EOF'
---
name: api
---

# 生成标准 API 接口模板

按照以下规范生成代码：
1. 使用 RESTful 风格
2. 添加异常处理
3. 包含输入验证
4. 生成对应的测试用例
EOF

# 3. 使用自定义命令
> /api 创建一个用户管理接口

---

六、核心交互模式

6.1 自然语言交互

Claude Code 的核心优势是支持自然语言指令：

# 不需要记特定命令，直接用自然语言
> 帮我分析这个项目的主要功能

> 为所有 API 路由添加错误处理

> 重构 utils.py 使其更符合 PEP8 规范

6.2 上下文引用

# 引用文件
> 分析 @src/main.py 的结构

# 引用多个文件
> 比较 @src/v1/api.py 和 @src/v2/api.py 的区别

# 引用代码行
> 优化 @src/utils.py#45-60 这段代码的性能

6.3 多轮对话

# 第一轮
> 创建一个处理 CSV 数据的 Python 脚本

# 第二轮（基于上一轮）
> 为这个脚本添加异常处理

# 第三轮
> 再添加命令行参数支持

---

七、快速示例

示例1：初始化项目

> 帮我创建一个 Python 项目结构，包含：
  - src/ 目录存放源代码
  - tests/ 目录存放测试
  - requirements.txt
  - README.md

AI 会：
1. 创建所有目录和文件
2. 生成基础代码
3. 创建 .gitignore

示例2：生成代码

> 在 src/models.py 中创建一个 User 类：
  - 字段：id(int), username(str), email(str), created_at(datetime)
  - 方法：to_dict(), validate_email()
  - 使用 Pydantic BaseModel

# AI 生成的代码
from datetime import datetime
from pydantic import BaseModel, EmailStr, Field

class User(BaseModel):
    id: int = Field(..., description="用户ID")
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    created_at: datetime = Field(default_factory=datetime.now)
    
    def to_dict(self) -> dict:
        return self.model_dump()
    
    def validate_email(self) -> bool:
        return "@" in self.email and "." in self.email.split("@")[1]

示例3：批量修改

> 将项目中所有 Python 文件的 print 语句替换为 logging：
  1. 在文件顶部添加 logging 导入和初始化
  2. 将所有 print("xxx") 改为 logger.info("xxx")
  3. 保持原有缩进

示例4：Git 操作

> 查看当前有哪些未提交的更改

> 提交所有更改，消息是："添加用户认证功能"

> 创建一个新分支 feature/auth，并切换过去

---

六、常用场景速查

场景1：代码理解

# 快速了解项目
> 这个项目的主要功能是什么？

# 了解具体模块
> 解释 src/auth.py 的作用

# 了解代码逻辑
> src/utils.py 中的 validate_token 函数是如何工作的？

场景2：代码生成

# 生成基础代码
> 创建一个 FastAPI 的路由文件，包含 CRUD 操作

# 生成测试
> 为 src/models/user.py 生成 pytest 测试

# 生成文档
> 为 src/api/ 下的所有模块生成 API 文档

场景3：代码重构

# 单文件重构
> 重构 src/main.py，使用类来组织代码

# 批量重构
> 将所有使用了旧 API 的文件更新到新 API

# 性能优化
> 优化 src/processor.py 中数据处理函数的性能

场景4：问题排查

# 查找问题
> 为什么 tests/test_api.py 会失败？

# 分析错误
> 解释这个错误信息：ImportError: cannot import name 'User'

# 修复 Bug
> 修复 src/calc.py 中的除零错误

---

七、配置与个性化

7.1 配置文件位置

平台	路径 (Claude Code 2.1.81+)
Windows	%APPDATA%\claude\settings.json
macOS	~/.config/claude/settings.json
Linux	~/.config/claude/settings.json

7.2 常用配置项

{
  "env": {
    "ANTHROPIC_API_KEY": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  },
  "preferences": {
    "auto_execute_commands": false,
    "confirm_destructive_operations": true,
    "editor": "cursor"
  }
}

7.3 设置编辑器

# 配置默认编辑器（用于编辑文件）
> 设置编辑器为 cursor

# 或 vim
> 设置编辑器为 vim

# 或 vscode
> 设置编辑器为 code

---

八、常见问题

Q1: Claude Code 启动失败

解决:

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

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

Q2: API Key 无效

解决:

• 检查环境变量 ANTHROPIC_API_KEY 是否设置
• 确认 API Key 有余额
• 检查网络连接

Q3: 对话历史太长

解决:

> /compact    # 压缩历史
> /clear      # 清除历史

Q4: 如何切换模型

解决:

# 查看当前模型
> /status

# 使用环境变量切换
export ANTHROPIC_MODEL=claude-opus-4-20250514

---

九、下一步学习

完成本指南后，建议继续学习：

1. 02-CLI交互技巧.md - 掌握高效 CLI 交互
2. 08-ClaudeCode独有技巧.md - 学习自然语言 Git 操作等特色功能

---