<!-- title: Claude Code零基础入门实战教程 -->

# Claude Code 零基础入门实战教程

> **学习目标**：从零开始掌握 Claude Code 的安装、配置和项目开发，完成你的第一个 AI 辅助编程项目。
>
> **适用人群**：没有 AI 编程工具使用经验的开发者、学生、技术爱好者。不需要你之前用过 Cursor、Copilot 或任何 AI 编程工具，只要你会打开终端、能运行基本命令就行。

---

## 一、Claude Code 是什么

Claude Code 是 Anthropic 公司推出的**命令行 AI 编程代理**。它不是一个自动补全工具，而是一个能够**理解整个项目**、**自主读写文件**、**执行终端命令**、**管理 Git 工作流**的完整开发伙伴。

简单对比一下你可能听过的工具：

| 特性 | Claude Code | GitHub Copilot | Cursor |
|------|------------|----------------|--------|
| 运行方式 | 终端命令行 | IDE 插件 | 独立 IDE |
| 能力范围 | 读写文件、执行命令、Git 操作 | 代码补全、聊天 | 代码编辑、聊天 |
| 上下文理解 | 整个项目 | 当前文件 | 整个项目 |
| 自主性 | 高（可独立完成任务） | 低（辅助补全） | 中（需引导） |
| 学习曲线 | 中等 | 低 | 中低 |

核心能力一览：

- **文件操作**：读取、创建、编辑项目中任意文件
- **命令执行**：运行测试、构建、部署等终端命令
- **Git 集成**：提交、创建分支、发起 PR
- **代码搜索**：在代码库中搜索函数、类、模式
- **MCP 扩展**：连接外部工具和数据源
- **Skills 系统**：安装和使用社区开发的工作流技能

---

## 二、环境准备

### 2.1 系统要求

| 项目 | 最低要求 |
|------|---------|
| 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+（需 WSL 2） |
| 内存 | 至少 4GB RAM |
| 磁盘空间 | 约 100MB |
| 网络 | 稳定的互联网连接 |

### 2.2 安装前检查

打开你的终端（macOS/Linux 打开 Terminal，Windows 打开 WSL 终端），运行以下命令检查环境：

```bash
# 检查 Node.js 版本（npm 安装方式需要）
node --version
# 期望输出：v18.x.x 或更高

# 检查 npm 版本
npm --version
# 期望输出：9.x.x 或更高

# 检查 Git 是否安装
git --version
# 期望输出：git version 2.x.x
```

如果 Node.js 没有安装，你可以选择两种路径：

- **路径 A（推荐 2026）**：使用原生安装器，**不需要 Node.js**
- **路径 B（经典方式）**：先安装 Node.js，再用 npm 安装

---

## 三、安装 Claude Code

### 方法一：原生安装器（2026 年推荐）

这是 Anthropic 在 2026 年推出的新方式，**零依赖**，一条命令搞定：

**macOS / Linux：**

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

**Windows（PowerShell 管理员模式）：**

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

安装完成后验证：

```bash
claude --version
# 期望输出类似：Claude Code v2.1.x
```

原生安装器的优势：

- 不需要 Node.js、npm 或任何运行时
- 自动管理版本更新（`claude update`）
- 安装速度更快
- 自动配置 PATH

### 方法二：npm 安装（经典方式）

如果你已经有 Node.js 18+ 环境：

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

验证安装：

```bash
claude --version
```

### 方法三：Homebrew 安装（macOS）

```bash
brew install claude-code
```

> **注意**：Homebrew 版本可能滞后于最新版。如果需要最新功能，推荐使用原生安装器。当发现版本落后时，可以运行 `claude update` 手动更新。

### 常见安装问题

**问题 1：命令找不到 `claude: command not found`**

```bash
# 检查 claude 是否在 PATH 中
which claude

# 如果为空，手动添加 PATH（原生安装器通常安装在 ~/.local/bin）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**问题 2：npm 权限错误 `EACCES`**

```bash
# 方案一：使用 nvm 管理 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
npm install -g @anthropic-ai/claude-code

# 方案二：修改 npm 全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

**问题 3：Windows WSL 未安装**

```powershell
# 在 PowerShell（管理员）中运行
wsl --install
# 重启后，在 Ubuntu 终端中继续安装 Claude Code
```

---

## 四、认证与启动

### 4.1 首次启动

在终端中输入：

```bash
claude
```

首次运行会进入认证流程，有两种认证方式：

**方式一：Anthropic 账号登录（推荐）**

Claude Code 会显示一个链接和验证码：

```
Please visit https://console.anthropic.com/device
and enter code: XXXX-XXXX
```

在浏览器中打开链接，登录你的 Anthropic 账号，输入验证码即可。

**方式二：API Key**

如果你有 API Key：

```bash
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
claude
```

或将 Key 写入配置文件（永久生效）：

```bash
# 写入 shell 配置文件
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc
```

> **安全提醒**：永远不要把 API Key 提交到 Git 仓库。确保 `.gitignore` 中包含 `.env` 文件。

### 4.2 启动成功

认证成功后，你会看到 Claude Code 的交互界面：

```
╭───────────────────────────────────────╮
│  Claude Code                          │
│  Model: claude-sonnet-4-6             │
│  cwd: /home/user/my-project           │
╭───────────────────────────────────────╮
>
```

这表示 Claude Code 已经就绪，等待你的指令。`>` 提示符后面输入你的需求。

---

## 五、核心操作速览

在开始实战项目之前，先掌握 Claude Code 最常用的操作。这些是你日常开发中 80% 时间在用的功能。

### 5.1 基本对话

直接在提示符后输入自然语言：

```
> 列出当前项目的文件结构
```

```
> 这个项目用了什么技术栈？
```

```
> 解释一下 src/auth/login.ts 的逻辑
```

### 5.2 重要斜杠命令

在会话中输入 `/` 可以看到所有可用命令。以下是新手必须掌握的：

| 命令 | 作用 | 使用场景 |
|------|------|---------|
| `/init` | 自动生成 CLAUDE.md 项目说明 | 进入新项目时第一步 |
| `/help` | 显示帮助信息 | 忘了怎么用的时候 |
| `/clear` | 清除当前会话上下文 | 切换任务时 |
| `/compact` | 压缩上下文，释放空间 | 对话很长时 |
| `/plan` | 进入计划模式 | 复杂任务先规划再执行 |
| `/model` | 切换 AI 模型 | 需要更强/更快模型时 |
| `/undo` | 撤销上一次操作 | Claude 做错了 |
| `/cost` | 查看当前会话费用 | 控制预算 |

### 5.3 键盘快捷键

| 快捷键 | 作用 |
|--------|------|
| `Escape` | 中断当前操作 |
| `Ctrl+C` | 取消当前输入 |
| `↑` / `↓` | 浏览历史输入 |
| `Tab` | 自动补全文件路径 |

---

## 六、实战：从零创建第一个项目

现在来做一件真正的事——用 Claude Code 从零搭建一个完整的 Web 项目。我们创建一个个人任务管理应用（Todo App），技术栈用 Node.js + Express + SQLite。

### 6.1 创建项目目录

```bash
mkdir my-todo-app && cd my-todo-app
```

### 6.2 初始化项目

启动 Claude Code：

```bash
claude
```

在 Claude Code 中运行初始化命令：

```
> /init
```

`/init` 命令会扫描当前目录并生成一个 `CLAUDE.md` 文件。由于目录是空的，它会创建一个基础模板。

### 6.3 编写 CLAUDE.md（项目的灵魂）

`CLAUDE.md` 是 Claude Code 最重要的配置文件。它告诉 AI 你的项目规则、偏好和约定。手动编辑它，加入以下内容：

```markdown
# 项目：个人任务管理应用

## 技术栈
- 后端：Node.js + Express
- 数据库：SQLite（better-sqlite3）
- 前端：HTML + CSS + 原生 JavaScript

## 项目结构
- server.js — 主服务入口
- db/ — 数据库初始化和操作
- public/ — 静态前端文件
- routes/ — API 路由

## 编码规范
- 使用 CommonJS 模块（require/module.exports）
- 函数和变量使用驼峰命名
- API 返回 JSON 格式
- 错误处理统一返回 { error: "错误信息" }

## 开发命令
- 启动开发服务器：node server.js
- 安装依赖：npm install
```

**CLAUDE.md 的层级体系**：

```
~/.claude/CLAUDE.md          ← 全局配置（所有项目共享）
项目根目录/CLAUDE.md          ← 项目配置（团队成员共享）
项目根目录/.claude/CLAUDE.md  ← 项目私有配置（不提交到 Git）
```

这个层级意味着你可以：
- 在全局 CLAUDE.md 中设置个人偏好（如"用中文回复"）
- 在项目 CLAUDE.md 中设置团队规范
- 在私有 CLAUDE.md 中设置个人临时配置

### 6.4 让 Claude Code 生成项目骨架

在 Claude Code 中输入：

```
> 根据CLAUDE.md中的技术栈，帮我创建完整的项目结构。包括：
> 1. package.json
> 2. server.js 主入口
> 3. SQLite 数据库初始化脚本
> 4. RESTful API（增删改查任务）
> 5. 简洁的前端页面
```

Claude Code 会自动：

1. 创建目录结构
2. 编写所有文件
3. 生成 package.json 并安装依赖

预期输出类似：

```
让我创建项目结构...
  ✓ 创建 package.json
  ✓ 创建 server.js
  ✓ 创建 db/init.js
  ✓ 创建 routes/tasks.js
  ✓ 创建 public/index.html
  ✓ 创建 public/style.css
  ✓ 创建 public/app.js
  ✓ 运行 npm install
```

### 6.5 运行并测试

在 Claude Code 中继续对话：

```
> 启动开发服务器并测试 API 是否正常
```

Claude Code 会执行：

```bash
node server.js
# 输出：Server running on http://localhost:3000
```

然后它会用 curl 测试 API：

```bash
# 创建任务
curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"学习 Claude Code","description":"完成入门教程"}'

# 获取所有任务
curl http://localhost:3000/api/tasks
```

### 6.6 迭代改进

现在你已经有了一个能运行的应用。继续让 Claude Code 帮你改进：

```
> 给任务添加优先级字段（高/中/低），前端加一个优先级筛选下拉框
```

```
> 添加任务完成状态切换功能，完成后显示删除线
```

```
> 写一个简单的测试文件
```

### 6.7 Git 版本控制

当你对当前状态满意时：

```
> 初始化 Git 仓库，创建 .gitignore，提交初始代码
```

Claude Code 会：

```bash
git init
# 创建 .gitignore（包含 node_modules, .env 等）
git add .
git commit -m "Initial commit: Todo app with Express + SQLite"
```

---

## 七、工作流程全景图

下面这张流程图展示了从安装到日常开发的完整工作流：

```text
flowchart TD
    A[安装 Claude Code] --> B[首次认证]
    B --> C[打开项目目录]
    C --> D[运行 claude 启动]
    D --> E[运行 /init 生成 CLAUDE.md]
    E --> F[编辑 CLAUDE.md 设定规则]
    F --> G{任务类型}

    G -->|新功能| H[用自然语言描述需求]
    G -->|修 Bug| I[描述问题现象]
    G -->|重构| J[说明重构目标]

    H --> K[Claude Code 执行]
    I --> K
    J --> K

    K --> L{满意？}
    L -->|是| M[git commit 提交]
    L -->|否| N[/undo 撤销或补充指令]
    N --> K

    M --> O[继续下一个任务]

    style A fill:#4A90D9,color:#fff
    style B fill:#4A90D9,color:#fff
    style K fill:#E8A838,color:#fff
    style M fill:#5CB85C,color:#fff
```

### CLAUDE.md 配置决策图


![图表2](images/claude-code-tutorial-2135-mermaid-1.png)

> *图表 2*


---

## 八、权限系统详解

Claude Code 执行操作时需要你的授权。理解权限系统可以让你更高效地工作。

### 8.1 权限模式

启动时可以指定权限模式：

```bash
# 默认模式：每次危险操作都询问
claude

# 接受所有读取操作，写入和命令仍需确认
claude --allowedTools Read,Glob,Grep

# 自动接受所有操作（仅用于可信环境）
claude --dangerouslySkipPermissions
```

### 8.2 操作类型

| 操作类型 | 示例 | 默认行为 |
|---------|------|---------|
| 读取文件 | 查看代码内容 | 自动允许 |
| 搜索文件 | 查找文件、搜索代码 | 自动允许 |
| 编辑文件 | 修改代码 | 需要确认 |
| 创建文件 | 新建文件 | 需要确认 |
| 执行命令 | 运行测试、安装依赖 | 需要确认 |

### 8.3 权限配置

你可以通过 `.claude/settings.json` 持久化权限：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(node *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)"
    ]
  }
}
```

这样你不需要每次都手动确认 `npm test` 之类的安全命令。

---

## 九、Plan 模式：先规划再动手

对于复杂任务，Claude Code 提供了 Plan 模式。在这个模式下，Claude 只分析和规划，**不执行任何修改操作**。

### 使用方式

```
> /plan
已进入计划模式。我会分析并制定方案，但不会修改任何文件。

> 重构整个认证模块，支持 OAuth2 和 JWT 两种方式
```

Claude Code 会输出：

```
## 实施计划

### 第一阶段：数据模型设计
1. 创建 User 模型（支持 OAuth 账号关联）
2. 创建 Session 模型（JWT Token 管理）
...

### 第二阶段：OAuth2 集成
1. 添加 OAuth2 客户端配置
2. 实现 GitHub/Google 登录流程
...

### 第三阶段：JWT 认证
1. 实现 JWT 签发和验证
2. 添加 Token 刷新机制
...

### 预计影响文件
- src/auth/ 目录（重写）
- src/routes/login.ts（修改）
- src/middleware/auth.ts（新建）

是否开始执行？
```

审查计划后，你可以：
- 说"开始执行"——Claude 按计划逐步实施
- 说"修改第三阶段"——调整计划
- 说"先只做第一阶段"——分步执行

---

## 十、模型选择策略

Claude Code 支持多个模型，不同场景选择不同模型可以优化成本和速度：

| 模型 | 特点 | 适用场景 |
|------|------|---------|
| Claude Sonnet 4.6 | 均衡性能，速度快 | 日常编码、文件编辑、问答 |
| Claude Opus 4.6 | 最强能力，较慢 | 复杂架构设计、难题调试 |
| Claude Haiku 4.5 | 最快速度，低成本 | 简单查询、格式化、翻译 |

在会话中切换模型：

```
> /model claude-opus-4-6
```

或通过命令行参数：

```bash
claude --model claude-opus-4-6
```

**实战建议**：

- 日常编码用 Sonnet，性价比最高
- 遇到架构级难题或复杂 Bug 时切 Opus
- 批量简单任务用 Haiku 节省成本

---

## 十一、上下文管理技巧

Claude Code 的对话上下文有容量限制。以下技巧帮你高效利用上下文窗口：

### 11.1 及时压缩

```
> /compact
```

当对话超过几十轮后，执行 `/compact` 可以压缩历史信息，保留关键上下文，释放空间继续对话。

### 11.2 任务切换清空

```
> /clear
```

完成一个任务后、开始新任务前，执行 `/clear` 清除无关上下文。

### 11.3 用 CLAUDE.md 持久化知识

与其每次对话重复说明项目背景，不如写到 CLAUDE.md 中。Claude Code 每次启动都会读取这个文件。

### 11.4 精准引用文件

```
> 查看 src/utils/helpers.js 中的 formatDate 函数，帮它加上时区支持
```

比"帮我改一下时间格式化"这种模糊指令高效得多。

---

## 十二、常见使用模式

### 12.1 代码审查

```
> 审查最近一次 Git 提交的代码，指出潜在问题
```

### 12.2 Bug 调试

```
> 运行测试，如果失败了分析原因并修复
```

### 12.3 文档生成

```
> 为 src/api/ 目录下的所有路由生成 API 文档
```

### 12.4 代码重构

```
> 将 src/utils.js 拆分成独立的模块文件，保持功能不变
```

### 12.5 技术选型

```
> /plan
> 我需要给这个项目添加缓存层，比较 Redis 和 Memcached 的优劣，给出推荐方案
```

---

## 十三、避坑指南（新手必读）

### 坑 1：盲目信任 AI 输出

Claude Code 能力很强但不是万能的。**始终审查它生成的代码**，尤其是：
- 涉及安全性的代码（认证、加密）
- 数据库操作（可能丢数据）
- 第三方库的使用（可能用过时 API）

### 坑 2：不做 Git 提交

让 Claude Code 每完成一个有意义的步骤就提交一次：

```
> 提交当前更改，commit message 用中文描述
```

这样如果 AI 后续操作搞砸了，你可以轻松回滚。

### 坑 3：CLAUDE.md 太简陋

一个差的 CLAUDE.md：

```markdown
# My Project
这是一个 Web 应用
```

一个好的 CLAUDE.md 应包含：技术栈、目录结构、编码规范、常用命令、特殊约定。

### 坑 4：不会用 /undo

Claude Code 做了你不满意的修改？不要手动改回来：

```
> /undo
```

一步撤销，干净利落。

### 坑 5：在项目根目录启动

始终 `cd` 到项目目录再启动 `claude`。Claude Code 的工作范围基于当前目录：

```bash
# 正确
cd ~/projects/my-app && claude

# 错误（在 home 目录启动，上下文太大）
cd ~ && claude
```

---

## 十四、进阶路线图

完成本教程后，建议按以下顺序继续深入：


![图表3](images/claude-code-tutorial-2135-mermaid-2.png)

> *图表 3*


**下一步学习资源**：

- [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code) — 最权威的参考
- [Claude Code 官方命令参考](https://code.claude.com/docs/en/commands) — 所有命令详解
- [Claude Code 最佳实践](https://code.claude.com/docs/en/best-practices) — 官方推荐的用法
- [GitHub 仓库](https://github.com/anthropics/claude-code) — 源码和 Issue 追踪
- [Claude Code Deep Dive 系列](https://the-gigi.github.io/gigi-zone/posts/2026/01/cc-deep-dive-02-slash-commands/) — 社区深度教程

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | AI 编程入门营、前端/后端开发集训、全栈工程师速成 |
| **建议教学时长** | 3-4 小时（含实操练习） |
| **学员前置要求** | 基本的终端操作能力，了解至少一门编程语言 |
| **硬件要求** | 任何能运行终端的电脑（4GB+ RAM） |
| **网络要求** | 需要稳定的网络（调用 Anthropic API） |
| **推荐练习项目** | Todo App（本教程）、个人博客、API 网关 |
| **成本预估** | 约 $5-15/人（取决于模型选择和使用量） |

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)