# Claude Code 完整教程

本文是一篇面向中国开发者的 **Claude Code 完整教程**，从安装配置到高级技巧，带你全面掌握这款 2026 年最强的 AI 编程助手。无论你是第一次接触 AI 编程工具，还是从其他工具迁移而来，这篇教程都适合你。

---

## 一、Claude Code 是什么

### 不是代码补全，而是代理式编程助手

Claude Code 是 Anthropic 推出的官方 CLI（命令行界面）**代理式编程助手**（Agentic Coding Assistant）。与传统的代码补全工具（如 GitHub Copilot）不同，Claude Code 能像一位经验丰富的开发者一样：

- **自主理解任务**：你描述需求，它制定执行计划
- **直接操作代码**：读取、编辑、创建项目中的任意文件
- **执行终端命令**：运行测试、安装依赖、执行构建
- **深度理解项目**：默认 20 万 token 上下文窗口（`claude-opus-5` / `claude-sonnet-5` 等支持扩展至 100 万）
- **调度子代理**：将复杂任务分解给多个专门的子代理并行处理

### 谁在使用 Claude Code

自 2025 年 5 月发布以来，Claude Code 已成为全球领先企业的核心开发工具，包括 Netflix、Spotify、KPMG、欧莱雅、Salesforce 等。仅用 6 个月就达到了 10 亿美元年收入的里程碑。

### 2025-2026 年核心更新

| 更新 | 说明 |
|------|------|
| **Plan Mode** | 先分析研究，再制定方案，减少错误 |
| **Agent Teams** | 多 Agent 并行协作，git worktree 隔离 |
| **Voice Mode** | 语音交互，按住空格说话 |
| **Computer Use** | 操作桌面、浏览器、开发工具 |
| **Hooks 系统** | 17 种生命周期事件，自动化工作流 |
| **MCP 协议** | 连接外部工具和服务 |
| **Skills** | 知识模块，可共享的工作流模板 |
| **Extended Thinking** | 复杂问题先在内部深度推理 |
| **Opus 5 / Sonnet 5** | 当前旗舰与日常默认（4.8 / 4.6 仍在售） |
| **1M Context Beta** | `claude-sonnet-5` / `claude-opus-5` 等支持 100 万 token 上下文 |

### 为什么通过 QCode.cc 使用

在中国大陆直接使用 Claude Code 存在两个问题：网络不可达和费用高昂。通过 QCode.cc：

- **亚太节点低延迟**，无需翻墙或自建代理
- **成本降低高达 80%**，相比官方价格大幅节省
- **Claude Code 与 Codex 共享套餐配额**，一份套餐两个工具
- **多节点高可用**（HK / 北美 / 欧洲 / 全球 Route 53）

---

## 二、安装与环境配置

### 系统要求

| 要求 | 说明 |
|------|------|
| 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+（WSL2） |
| Node.js | 18.0 或更高（推荐 22 LTS） |
| Git | 2.x 或更高版本 |
| 磁盘空间 | 约 200MB |

### 安装 Claude Code

```bash
# npm 安装（推荐）
npm install -g @anthropic-ai/claude-code

# 中国用户使用淘宝镜像加速
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
```

### 配置 QCode.cc

在终端中设置环境变量：

```bash
# 添加到 ~/.bashrc 或 ~/.zshrc
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api
export ANTHROPIC_AUTH_TOKEN=cr_你的API密钥
```

> **为什么用 `ANTHROPIC_AUTH_TOKEN` 而不是 `ANTHROPIC_API_KEY`**：QCode.cc 的 `cr_` 开头密钥是**第三方网关密钥**，不是 Anthropic 官方密钥。Claude Code 看到 `ANTHROPIC_AUTH_TOKEN` 会用 `Authorization: Bearer <token>` 头发给网关；用 `ANTHROPIC_API_KEY` 则发 `x-api-key`，并可能与已登录的 Anthropic 账号产生 OAuth 冲突。**用 `ANTHROPIC_AUTH_TOKEN` 是 QCode 官方推荐**。

> **API 密钥**在 [QCode.cc 控制台](https://qcode.cc/dashboard) 获取，以 `cr_` 开头。

> **接入点选择**：默认 `https://api.qcode.cc/api`（全球 Route 53 自动就近）。中国大陆用户推荐 `asia.qcode.cc`（亚洲节点，HK/JP 就近，延迟最低）。更多接入域（`us` / `eu` / `asia`）和 BASE_URL 规则参见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

使配置生效：

```bash
source ~/.bashrc  # 或 source ~/.zshrc
```

### 验证安装

```bash
# 查看版本
claude --version
# 应打印版本号（以本机为准，见 https://github.com/anthropics/claude-code/releases）

# 快速测试
claude -p "你好，请介绍一下自己"
```

如果正常返回 Claude 的回复，说明安装和配置成功。

### Shell 自动补全（可选）

```bash
# Bash
claude completion bash >> ~/.bashrc

# Zsh
claude completion zsh >> ~/.zshrc

# Fish
claude completion fish > ~/.config/fish/completions/claude.fish
```

---

## 三、第一次使用 Claude Code

### 启动

在任意项目目录中运行：

```bash
cd ~/my-project
claude
```

Claude Code 会自动扫描项目结构，进入交互式对话模式。

### 理解界面

```text
╭─────────────────────────────────────────╮
│ claude                                   │
│                                          │
│ 项目: my-project                         │
│ 模型: claude-sonnet-5                    │
│ 上下文: 12,345 / 1,000,000 tokens        │
╰─────────────────────────────────────────╯

> _
```

你可以直接输入自然语言，Claude 会理解并执行。

### 第一个任务：理解项目

```text
> 分析这个项目的架构，告诉我主要模块和它们之间的关系
```

Claude 会自动：
1. 读取 `package.json`、`README.md`、目录结构
2. 浏览关键源文件
3. 给出结构化的架构分析

### 权限确认

当 Claude 需要执行操作时，会请求你的确认：

```text
Claude 想要执行：
  工具: Bash
  命令: npm test

  [y] 允许  [n] 拒绝  [a] 本次会话始终允许
```

- **y**：允许本次执行
- **n**：拒绝
- **a**：本次会话中始终允许此类操作（推荐日常开发使用）

### 常用权限模式

| 模式 | 说明 | 适用场景 |
|------|------|---------|
| 默认 | 每次操作需确认 | 初次使用、敏感项目 |
| `--allowedTools` | 指定允许的工具 | 限制范围的自动化 |
| `--dangerously-skip-permissions` | 跳过所有确认 | Docker 隔离环境、CI/CD |

---

## 四、核心功能详解

### 4.1 Plan Mode（规划模式）

Plan Mode 让 Claude 先分析研究，再制定执行方案，适合复杂任务。

```bash
# 进入规划模式
> /plan

# 或在提示中触发
> 请先分析需求，制定实施方案，不要直接改代码
```

**工作流程**：
1. Claude 分析代码库和需求
2. 提出实施方案（创建/修改哪些文件、步骤顺序）
3. 你审核方案，提出修改意见
4. 确认后 Claude 按方案执行

**示例**：

```text
> /plan
> 我想给项目添加用户认证功能，使用 JWT

Claude: 我来分析当前项目结构并制定方案...

📋 实施方案：
1. 创建 src/middleware/auth.ts — JWT 验证中间件
2. 创建 src/services/auth-service.ts — 认证业务逻辑
3. 修改 src/routes/index.ts — 添加登录/注册路由
4. 创建 src/models/user.ts — 用户数据模型
5. 添加依赖：jsonwebtoken, bcrypt
6. 创建测试文件

方案是否可以？需要调整吗？
```

### 4.2 Extended Thinking（扩展思考）

Opus 5（以及仍在售的 4.8 / 4.7）内置扩展思考能力（推荐使用 adaptive thinking + effort 参数，详见 [Adaptive Thinking 配置指南](/docs/usage/adaptive-thinking)），面对复杂问题时会先进行深度内部推理。

```text
> 这个并发 bug 已经排查了两天了，请帮我分析 src/worker.ts 中的竞态条件

[Claude 内部进行数千 token 的推理，分析执行路径、锁机制、时序问题]

Claude: 我找到了问题。在 worker.ts 第 127 行...
```

**何时自动触发**：
- 复杂的调试任务
- 架构级别的分析
- 多步骤推理链

### 4.3 子代理（Sub-agents）

Claude 可以生成专门的子代理处理特定任务：

```text
> 帮我 review 这个 PR，同时检查是否有安全漏洞

Claude: 我会启动两个子代理并行处理：
  - 子代理 1：代码质量审查
  - 子代理 2：安全漏洞扫描
```

子代理运行在独立的上下文中，不会污染主会话。

### 4.4 关键命令速查表

| 命令 | 功能 | 示例 |
|------|------|------|
| `/model` | 切换模型 | `/model opus` |
| `/plan` | 进入规划模式 | `/plan` |
| `/compact` | 压缩上下文 | `/compact` |
| `/cost` | 查看当前费用 | `/cost` |
| `/clear` | 清空上下文 | `/clear` |
| `/init` | 生成 CLAUDE.md | `/init` |
| `/review` | 代码审查 | `/review` |
| `/help` | 帮助信息 | `/help` |
| `Esc` | 取消当前操作 | |
| `Ctrl+C` | 中断响应 | |

### 4.5 上下文管理

Claude Code 有 200K token 的上下文窗口。长会话中需要管理上下文：

```bash
# 查看当前上下文使用量
/cost

# 压缩上下文（保留关键信息，释放空间）
/compact

# 开始全新会话
/clear
```

**最佳实践**：
- 上下文使用超过 70% 时，执行 `/compact`
- 不同任务之间用 `/clear` 开始新会话
- 复杂项目在 CLAUDE.md 中记录背景信息（不会被 `/compact` 删除）

---

## 五、CLAUDE.md — 让 Claude 理解你的项目

### 为什么需要 CLAUDE.md

每次启动 Claude Code，它会自动读取项目中的 `CLAUDE.md`，了解项目架构、编码规范和特殊约定。没有它，你需要每次重复解释项目背景。

### 快速创建

```bash
# Claude 自动分析项目生成
/init
```

### 文件层级

| 位置 | 作用范围 | Git 管理 |
|------|---------|---------|
| `~/.claude/CLAUDE.md` | 全局（所有项目） | 不纳入 |
| `项目根/CLAUDE.md` | 本项目 | 提交到 Git |
| `.claude/CLAUDE.md` | 本项目（私有） | 加入 .gitignore |
| `子目录/CLAUDE.md` | 仅该子目录 | 按需 |

### 实战模板：React + TypeScript 项目

```markdown
# MyApp

## 技术栈
- React 19 + TypeScript 5.x + Vite
- 样式：Tailwind CSS v4
- 状态管理：Zustand
- 测试：Vitest + Testing Library

## 常用命令
- 开发：`pnpm dev`
- 测试：`pnpm test`
- 构建：`pnpm build`
- Lint：`pnpm lint`

## 编码规范
- 组件使用函数式写法，Props 用 interface 定义
- 禁止使用 any 类型
- CSS 只用 Tailwind utility class
- 提交格式：feat: / fix: / docs:

## 项目结构
- src/components/ — 可复用组件
- src/pages/ — 页面组件
- src/hooks/ — 自定义 Hooks
- src/lib/ — 工具函数
- src/api/ — API 请求封装

## 注意事项
- Node.js 22+，包管理器用 pnpm
- 所有 API 请求经过 src/api/client.ts 统一处理
```

> 完整的 CLAUDE.md 配置指南请查看 [CLAUDE.md 配置指南](/docs/usage/claude-md)。

---

## 六、模型选择实战指南

### 三大模型对比

单价是 2026-08-16 从 [qcode.cc/models](https://qcode.cc/models) 读到的快照，**以该页为准**。4.x 仍在售，只是不再当默认。

| 对比项 | Opus 5 | Sonnet 5 | Haiku 4.5 |
|--------|----------|------------|-----------|
| **定位** | 当前旗舰 | 日常默认 | 轻量快速 |
| **推理能力** | 极强 | 强 | 一般 |
| **代码质量** | 极高 | 高 | 中等 |
| **响应速度** | 较慢 | 中等 | 快 |
| **上下文** | 1M / 128K | 1M / 128K | 200K |
| **输入价格** | $5.00/M | $2.00/M | $1.00/M |
| **输出价格** | $25.00/M | $10.00/M | $5.00/M |

### 切换模型

```bash
# 交互模式中切换
/model opus    # 切换到 Opus
/model sonnet  # 切换到 Sonnet
/model haiku   # 切换到 Haiku

# 启动时指定
claude --model claude-opus-5
```

### 场景推荐

| 场景 | 推荐模型 | 理由 |
|------|---------|------|
| 架构设计 | **Opus** | 深度推理，考虑全局 |
| 日常编码 | **Sonnet** | 性价比最佳 |
| Bug 修复 | **Sonnet** | 够用且快 |
| 复杂调试 | **Opus** | Extended Thinking |
| 代码格式化 | **Haiku** | 简单任务用最便宜的 |
| PR Review | **Sonnet** | 速度和质量平衡 |
| 大规模重构 | **Opus** | 需要全局理解 |
| 文档撰写 | **Sonnet** | 够用 |

### 混合策略（推荐）

```text
一天的模型使用：
├── Sonnet 5（70%）— 日常开发、Bug 修复、写测试
├── Opus 5 （15%）— 架构决策、复杂问题
└── Haiku 4.5（15%）— 格式化、简单问答、批量操作
```

对话中可以随时切换：

```bash
# 先用 Opus 制定方案
/model opus
> 分析这个模块的架构，制定重构方案

# 方案确认后切到 Sonnet 执行
/model sonnet
> 按照方案执行第一步
```

---

## 七、高级技巧

### Hooks 系统

在 `.claude/settings.json` 中配置自动化钩子：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILEPATH"
          }
        ]
      }
    ]
  }
}
```

> 完整指南见 [Hooks 系统](/docs/advanced/hooks)。

### MCP 服务器

通过 Model Context Protocol 连接外部工具：

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    }
  }
}
```

### Skills 系统

Skills 是可复用的知识模块：

```bash
# 查看可用 skills
/skills

# 使用特定 skill
> /commit    # 使用 commit skill 生成提交
> /review    # 使用 review skill 审查代码
```

### --bare 模式

脚本化调用，跳过所有交互式功能：

```bash
claude --bare -p "列出所有 TODO 注释" --output-format json
```

---

## 八、实战示例

### 示例 1：理解一个新项目

```bash
cd ~/unfamiliar-project
claude
```

```text
> 请分析这个项目：
> 1. 使用了哪些技术栈
> 2. 核心模块及其职责
> 3. 数据流方向
> 4. 画一个简单的架构图（ASCII）
```

Claude 会自动浏览 package.json、源码目录、配置文件，给出完整的项目地图。

### 示例 2：用 Plan Mode 实现新功能

```text
> /plan
> 我要给 API 添加速率限制功能，要求：
> - 每个用户每分钟最多 60 次请求
> - 使用 Redis 存储计数
> - 超限时返回 429 状态码和 Retry-After 头

Claude:
📋 实施方案：
1. 安装依赖：ioredis
2. 创建 src/middleware/rate-limiter.ts
3. 创建 src/config/rate-limit.ts（配置项）
4. 修改 src/app.ts（注册中间件）
5. 创建 tests/rate-limiter.test.ts
6. 更新 docker-compose.yml（添加 Redis 服务）

确认后我开始执行。

> 方案没问题，请执行
```

### 示例 3：复杂 Bug 调试

```text
/model opus
> 用户报告说"并发下单时偶尔出现库存变为负数"。
> 请分析 src/services/order-service.ts 和 src/services/inventory-service.ts，
> 找出并发 bug 并修复。

[Opus 启用 Extended Thinking，分析执行路径、锁机制、事务隔离级别]

Claude: 我找到了问题。inventory-service.ts 第 45 行的库存检查和扣减不在同一个事务中，
存在 TOCTOU 竞态条件。修复方案是使用 SELECT FOR UPDATE...
```

### 示例 4：批量重构

```text
> 项目中所有的 class 组件需要重构为函数式组件 + Hooks。
> 请逐个文件处理 src/components/ 下的所有 .tsx 文件。

Claude 会：
1. 扫描所有 class 组件
2. 逐个转换为函数式组件
3. 将 lifecycle 方法转为 useEffect
4. 将 this.state 转为 useState
5. 运行测试确认不 break
```

### 示例 5：编写完整测试套件

```text
> 为 src/services/user-service.ts 编写完整的单元测试：
> - 覆盖所有公开方法
> - 包含正常路径和异常路径
> - Mock 外部依赖（数据库、缓存）
> - 目标覆盖率 90%+
```

### 示例 6：CI/CD 自动化

```bash
# 在 GitHub Actions 中使用
claude -p "审查这个 PR 的代码变更，重点关注安全和性能" \
  --output-format json \
  --max-turns 3 \
  --allowedTools Read,Glob,Grep
```

> 更多 CI/CD 实战见 [自动化与 CI/CD](/docs/advanced/headless)。

---

## 九、Claude Code 与 Codex 配合使用

Claude Code 和 OpenAI Codex CLI 是 2026 年最强的两个 AI 编程工具，各有所长：


**最佳配合**：Claude Code 做规划和审查，Codex 做执行和批量操作。

```bash
# 1. Claude Code 制定方案
claude
> /plan
> 设计用户权限系统的实施方案

# 2. Codex 按方案执行
codex "按照 PLAN.md 中的方案，实现步骤 1-3"
```

> **QCode.cc 一份套餐，两个工具共享配额**，切换零成本。
> 详细对比见 [Codex vs Claude Code 深度对比](/docs/getting-started/codex-vs-claude-code)。
> Codex 使用教程见 [Codex 完整教程](/docs/ide/codex)。

---

> **团队使用？** 3 人以上团队推荐 [企业团队版](https://qcode.cc/enterprise) — 独立域名 `e-xxx.qcode.cc`、子 API Key 管理、封号保障、支持对公转账和发票。详见 [企业版指南](/docs/reference/enterprise-guide)。

## 十、常见问题

### 安装失败

**Q: `npm install -g` 报权限错误**

```bash
# 方法 1：使用 sudo
sudo npm install -g @anthropic-ai/claude-code

# 方法 2：使用 nvm 管理 Node.js（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
npm install -g @anthropic-ai/claude-code
```

### 网络连接问题

**Q: 连接超时或拒绝**

```bash
# 检查配置是否正确
echo $ANTHROPIC_BASE_URL    # 应为 https://api.qcode.cc/api
echo $ANTHROPIC_AUTH_TOKEN  # 应以 cr_ 开头

# 测试连通性
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models
# → 200 + JSON 模型清单 = 地址、密钥、网络三者都通
```

### 费用控制

**Q: 担心费用过高**

- 日常使用 **Sonnet**（比 Opus 便宜 60%）
- 用 `/cost` 随时查看费用
- 用 `/compact` 压缩上下文减少 token 消耗
- 简单任务用 **Haiku**（最便宜）
- 查看 [费用优化指南](/docs/usage/cost-optimization)

### Claude 不理解项目

**Q: Claude 总是误解项目结构或规范**

创建 `CLAUDE.md` 文件（见第五章），把项目背景、规范、常用命令写进去。Claude 每次启动自动读取。

### 与其他工具的区别

**Q: Claude Code 和 Cursor/Copilot 有什么区别？**

| 工具 | 类型 | 特点 |
|------|------|------|
| **Claude Code** | CLI Agent | 自主规划执行，项目级理解 |
| **Cursor** | IDE | 编辑器深度集成，实时补全 |
| **Copilot** | IDE 插件 | 行级补全，简单建议 |

Claude Code 是 Agent 级别的助手（能自主完成复杂任务），而非行级补全工具。两者可以配合使用：Cursor 做实时编辑补全，Claude Code 做复杂任务规划和执行。

> **注意**：QCode.cc 同一把 `cr_` 密钥可以接入 Claude Code、Codex CLI，以及大量 IDE / CLI / 桌面端 —— Cursor 的配置方式（自定义 Base URL + API Key）见 [Cursor 编辑器接入](/docs/ide/cursor)，协议兼容矩阵与完整清单见 [工具兼容总览](/docs/ide/tool-compatibility)。

---

## 相关文档

- [安装教程](/docs/getting-started/installation) — 详细的安装步骤
- [CLAUDE.md 配置指南](/docs/usage/claude-md) — 完整的项目配置指南
- [Hooks 系统](/docs/advanced/hooks) — 自动化钩子详解
- [自动化与 CI/CD](/docs/advanced/headless) — 无头模式使用
- [模型选择指南](/docs/usage/model-selection) — 详细的模型对比
- [费用优化](/docs/usage/cost-optimization) — 控制成本的技巧
- [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code) — 两大工具对比
- [Codex 完整教程](/docs/ide/codex) — Codex 的完整使用指南
- [套餐定价](https://qcode.cc/pricing) — QCode.cc 套餐方案