## 概述
本教程面向零编程经验或从未接触过AI编程工具的开发者，手把手带你完成 Claude Code 的安装、认证、基础配置，并最终构建一个可运行的 Web 应用项目。学完本教程，你将掌握 Claude Code 的核心工作流，理解 CLAUDE.md 记忆系统，能够独立使用 AI 辅助完成日常开发任务。
**适用人群**：零基础开发者、从 ChatGPT 迁移的用户、想尝试 AI 编程工具的在职工程师。预计学习时长 60-90 分钟。
---
## 一、Claude Code 是什么
Claude Code 是 Anthropic 推出的 AI 编程智能体（Agentic Coding Tool），与 Copilot、Cursor 的"自动补全"模式根本不同——它不是一个插件，而是一个运行在你终端里的 **自主编码 Agent**。
### 1.1 核心能力对比
| 能力 | Copilot | Cursor | Claude Code |
|------|---------|--------|-------------|
| 代码补全 | ✅ 内联 | ✅ 内联 | ❌ 无补全 |
| 聊天对话 | ✅ 侧边栏 | ✅ 内置 | ✅ 终端对话 |
| 读取整个项目 | ❌ 仅当前文件 | ⚠️ 有限 | ✅ 全项目扫描 |
| 主动编辑多文件 | ❌ | ⚠️ 需确认 | ✅ 自动多文件编辑 |
| 运行终端命令 | ❌ | ❌ | ✅ 可执行任意命令 |
| 搜索代码库 | ❌ | ⚠️ 有限 | ✅ grep/glob 全搜索 |
| MCP 工具扩展 | ❌ | ❌ | ✅ 自定义工具协议 |
| 自定义 Skill | ❌ | ❌ | ✅ 完整 Skill 体系 |
简而言之：**Copilot 是副驾驶，Claude Code 是搭档程序员**。它不只是建议代码——它会读你的项目、理解架构、修改文件、运行测试、修复 Bug，全程自主完成。
### 1.2 工作原理
```mermaid
graph TD
A[你在终端输入需求] --> B[Claude Code 分析项目上下文]
B --> C{需要什么操作?}
C -->|读代码| D[Read/Grep/Glob 工具]
C -->|写代码| E[Edit/Write 工具]
C -->|跑命令| F[Bash 工具]
C -->|搜索信息| G[WebSearch 工具]
D --> H[综合分析并生成方案]
E --> H
F --> H
G --> H
H --> I[呈现结果 + 等待你的反馈]
I -->|继续指令| A
I -->|确认完成| J[任务结束]
```
---
## 二、环境准备
### 2.1 系统要求
| 项目 | 最低要求 |
|------|---------|
| 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+（需 WSL2） |
| Node.js | 18.x 或更高版本 |
| npm | 随 Node.js 一起安装 |
| 磁盘空间 | 约 200MB |
| 网络 | 需要访问 Anthropic API（支持代理） |
### 2.2 安装 Node.js（如果还没装）
**macOS（推荐 Homebrew）：**
```bash
brew install node@20
```
**Ubuntu/Debian：**
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```
**Windows（WSL2）：**
```bash
# 在 WSL2 Ubuntu 终端中执行同样的 Linux 命令
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```
验证安装：
```bash
node --version # 应输出 v20.x.x 或更高
npm --version # 应输出 10.x.x 或更高
```
### 2.3 获取 Anthropic API Key
1. 访问 [console.anthropic.com](https://console.anthropic.com)
2. 注册/登录 Anthropic 账号
3. 进入 **Settings → API Keys**
4. 点击 **Create Key**，复制生成的 Key（以 `sk-ant-` 开头）
5. 妥善保存，此 Key 仅显示一次
> **费用说明**：Claude Code 按 Token 计费，使用 Claude Sonnet 模型大约 $3/M 输入 Token、$15/M 输出 Token。一个典型的小型项目会话约消耗 $0.1-0.5。
---
## 三、安装 Claude Code
### 3.1 一键安装
```bash
npm install -g @anthropic-ai/claude-code
```
安装完成后验证：
```bash
claude --version
# 应输出类似: 1.0.x
```
### 3.2 其他安装方式
**方式二：使用 npx 免安装运行**
```bash
npx @anthropic-ai/claude-code
```
这种方式每次运行会检查更新，适合不想全局安装的用户。
**方式三：Desktop App（桌面版）**
如果你更偏好图形界面，Anthropic 提供了桌面应用：
- macOS：从 [claude.ai/download](https://claude.ai/download) 下载
- 桌面版功能与 CLI 版完全一致，但提供系统托盘和可视化配置界面
> **本教程全程使用 CLI 版本**，因为终端操作是 Claude Code 的核心体验。
### 3.3 首次认证
```bash
claude
```
首次运行会启动认证流程：
```
Welcome to Claude Code!
Please choose an authentication method:
1. Anthropic API Key
2. Claude App (claude.ai subscription)
3. Amazon Bedrock
4. Google Vertex AI
Select (1-4):
```
**选择 1（API Key）**，粘贴你之前保存的 `sk-ant-...` 密钥：
```
Enter your API key: sk-ant-xxxxx...
✓ Authentication successful!
```
如果你有 Claude Pro/Max 订阅，也可以选择 **2（Claude App）**，通过浏览器 OAuth 登录，无需 API Key。
### 3.4 验证认证成功
```bash
claude "say hello"
```
预期输出：
```
Hello! I'm Claude Code, your AI coding assistant. How can I help you today?
```
看到这句话，说明安装和认证全部完成。
---
## 四、核心概念速览
在开始项目之前，先掌握 Claude Code 的五个核心概念。
### 4.1 交互模式
| 模式 | 启动方式 | 说明 |
|------|---------|------|
| 交互式对话 | `claude` | 进入持续对话，适合复杂任务 |
| 单次命令 | `claude "你的指令"` | 执行一条指令后自动退出 |
| 管道模式 | `cat file.txt \| claude "分析这个文件"` | 将内容通过管道传入 |
| 恢复会话 | `claude --resume` | 恢复上次未完成的对话 |
### 4.2 斜杠命令
在交互模式中，使用 `/` 开头的命令可以触发特殊功能：
| 命令 | 功能 |
|------|------|
| `/help` | 查看所有可用命令 |
| `/clear` | 清空当前对话上下文 |
| `/compact` | 压缩上下文（长对话时节省 Token） |
| `/cost` | 查看当前会话的 Token 消耗 |
| `/memory` | 打开 CLAUDE.md 编辑器 |
| `/model` | 切换模型（Sonnet/Opus/Haiku） |
| `/plan` | 进入 Plan 模式（先规划再执行） |
| `/status` | 查看当前状态 |
### 4.3 CLAUDE.md 记忆系统
CLAUDE.md 是 Claude Code 的"项目说明书"，分为三个层级：
```mermaid
graph TB
A[~/.claude/CLAUDE.md
全局指令] --> B[项目根目录/CLAUDE.md
项目指令]
B --> C[子目录/CLAUDE.md
模块指令]
D[~/.claude/settings.json
全局配置] --> E[项目/.claude/settings.json
项目配置]
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#e8f5e9
```
- **全局 CLAUDE.md**（`~/.claude/CLAUDE.md`）：对所有项目生效的个人偏好
- **项目 CLAUDE.md**（项目根目录）：项目级别的编码规范和架构说明
- **目录 CLAUDE.md**（任意子目录）：模块级别的特殊规则
### 4.4 权限与安全
Claude Code 默认采用**确认模式**——每次执行写操作（修改文件、运行命令）都会先请求你的许可：
```
Claude wants to edit src/app.js:
+ const greeting = "Hello World";
- const greeting = "Hi";
Allow? (y/n/e=edit)
```
你可以逐次确认（`y`），也可以对特定操作设置"始终允许"以减少打断。
### 4.5 上下文窗口
每次会话 Claude Code 都会读取项目文件来理解上下文。它的上下文窗口为 200K Token，大约相当于 15 万字的文本。当对话过长时，使用 `/compact` 命令压缩历史对话。
---
## 五、实战：构建你的第一个项目
现在我们来完成一个完整的项目——用 Claude Code 从零构建一个 **Markdown 待办事项 Web 应用**。
### 5.1 创建项目结构
```bash
mkdir ~/my-first-claude-project
cd ~/my-first-claude-project
```
### 5.2 创建 CLAUDE.md
在项目根目录创建 `CLAUDE.md` 文件：
```bash
cat > CLAUDE.md << 'EOF'
# Project: Todo App
## Tech Stack
- Pure HTML/CSS/JavaScript (no frameworks)
- Node.js for serving static files
## Code Style
- Use Chinese comments
- Use ES6+ syntax
- Prefer const over let, never use var
## File Structure
- index.html - main page
- style.css - styles
- app.js - application logic
- server.js - development server
## Rules
- All UI text must be in Chinese
- Use semantic HTML5 elements
- Mobile-responsive design
EOF
```
> **为什么 CLAUDE.md 这么重要？** 它相当于一份"项目入职手册"。Claude Code 每次启动时都会读取它，确保 AI 的所有操作都符合你的规范。不用每次重复说明"用中文注释"。
### 5.3 启动 Claude Code
```bash
claude
```
你会看到欢迎界面：
```
╭──────────────────────────────────────────╮
│ Claude Code │
│ Model: claude-sonnet-4-20250514 │
│ Working: ~/my-first-claude-project │
╰──────────────────────────────────────────╯
>
```
### 5.4 第一步：让 Claude 创建项目骨架
输入你的第一条指令：
```
> 帮我创建一个待办事项 Web 应用。功能包括：添加任务、标记完成、删除任务、本地存储持久化。UI 要简洁美观，支持移动端。
```
Claude Code 会：
1. 读取你的 CLAUDE.md 了解项目规范
2. 规划文件结构
3. 逐个创建文件并展示给你确认
**预期交互过程**：
```
Claude wants to create index.html:
[full file content preview]
Allow? (y/n/e) y
✓ Created index.html
Claude wants to create style.css:
[full file content preview]
Allow? (y/n/e) y
✓ Created style.css
Claude wants to create app.js:
[full file content preview]
Allow? (y/n/e) y
✓ Created app.js
Claude wants to create server.js:
[full file content preview]
Allow? (y/n/e) y
✓ Created server.js
```
> **Tips**：第一次使用时建议逐个确认（按 `y`），这样你可以检查 Claude 写的每一行代码。熟练后可以选择"始终允许"来加速。
### 5.5 第二步：启动开发服务器
```
> 启动开发服务器
```
Claude Code 会执行：
```bash
node server.js
# 输出: Server running at http://localhost:3000
```
在浏览器打开 `http://localhost:3000`，你应该能看到一个漂亮的待办事项界面。
### 5.6 第三步：迭代改进
Claude Code 的强大在于迭代。继续提需求：
```
> 给完成的任务加上删除线效果，并且加一个统计栏显示"已完成/总数"
```
Claude Code 会精确修改 `style.css` 和 `app.js` 中的相关部分，而不是重写整个文件。
### 5.7 第四步：添加新功能
```
> 添加一个"清除已完成"按钮，点击时弹出确认对话框，确认后删除所有已完成的任务
```
### 5.8 第五步：代码审查
```
> 审查 app.js 的代码质量，看看有没有性能问题或可以改进的地方
```
Claude Code 会给出专业的代码审查意见，并主动询问是否要修复。
### 5.9 最终项目结构
```
my-first-claude-project/
├── CLAUDE.md # 项目规范文件
├── index.html # 主页面
├── style.css # 样式表
├── app.js # 应用逻辑
└── server.js # 开发服务器
```
---
## 六、六大核心工作流详解
### 6.1 代码问答
```bash
claude "解释 app.js 中 localStorage 的使用方式"
```
Claude Code 会读取文件，定位相关代码，给出详细解释。
### 6.2 Bug 修复
```bash
claude "我的待办事项刷新页面后数据丢失了，帮我排查修复"
```
Claude Code 会：
1. 读取 app.js 中 localStorage 相关代码
2. 定位 Bug（比如没有在页面加载时读取数据）
3. 修复代码
4. 验证修复
### 6.3 重构代码
```bash
claude "把 app.js 重构为 ES6 Class 风格"
```
### 6.4 添加测试
```bash
claude "用 Jest 为 app.js 中的核心函数编写单元测试"
```
### 6.5 代码解释
```bash
claude "这个项目用了哪些设计模式？画出架构图"
```
### 6.6 Git 操作
```bash
claude "帮我创建 git 仓库并提交初始代码，commit message 要描述清楚"
```
```mermaid
flowchart LR
A[输入需求] --> B{分析类型}
B -->|问答| C[读文件 → 解释]
B -->|修 Bug| D[定位 → 修复 → 验证]
B -->|新功能| E[规划 → 编码 → 测试]
B -->|重构| F[分析 → 重写 → 对比]
C --> G[输出结果]
D --> G
E --> G
F --> G
```
---
## 七、CLAUDE.md 深度配置指南
### 7.1 全局配置（所有项目共享）
```bash
cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences
## 语言
- 默认使用中文回复
- 代码注释可用英文
## 代码风格
- 使用 2 空格缩进
- 优先使用 TypeScript
- 组件使用函数式写法
## 工作流
- 不要自动 commit
- 修改代码后主动运行测试
- 始终先读取文件再编辑
EOF
```
### 7.2 项目级配置示例
```bash
# 在项目根目录
cat > CLAUDE.md << 'EOF'
# Project: My E-commerce App
## Architecture
- Frontend: React 19 + Vite
- Backend: Express.js + PostgreSQL
- State: Zustand
## Conventions
- API 路由以 /api/v1/ 开头
- 组件文件用 PascalCase 命名
- CSS 使用 CSS Modules
- 测试文件放在 __tests__/ 目录
## Database
- 迁移文件在 /migrations
- 使用 Knex.js 作为查询构建器
- 连接信息在 .env 中（不要读取）
## 重要规则
- 不要修改 .env 文件
- 不要删除 migration 文件
- API 返回统一格式 { code, data, message }
EOF
```
### 7.3 Auto Memory（自动记忆）
在对话中使用 `/memory` 命令，Claude Code 会根据对话内容自动将学到的信息写入 `~/.claude/CLAUDE.md`：
```
> /memory
# Claude Code 会显示当前记忆内容，你可以手动编辑或让 AI 自动添加
```
---
## 八、常见问题与解决方案
### 8.1 安装问题
| 问题 | 解决方案 |
|------|---------|
| `npm install -g` 权限错误 | 使用 `sudo npm install -g` 或配置 npm 全局路径 |
| Node.js 版本太低 | 用 `nvm install 20` 切换到 Node 20 |
| 网络超时 | 配置 npm 镜像：`npm config set registry https://registry.npmmirror.com` |
### 8.2 认证问题
| 问题 | 解决方案 |
|------|---------|
| API Key 无效 | 检查是否完整复制，是否有过期时间 |
| 401 Unauthorized | 确认账户余额充足，Key 未被撤销 |
| OAuth 登录失败 | 清除浏览器缓存后重试 |
### 8.3 使用问题
| 问题 | 解决方案 |
|------|---------|
| 对话太长变慢 | 使用 `/compact` 压缩上下文 |
| Token 消耗太快 | 切换到 Haiku 模型：`/model` 选择 haiku |
| Claude 修改了不该改的文件 | 检查 CLAUDE.md 中的规则，用 `git diff` 回滚 |
| 输出质量不稳定 | 在 CLAUDE.md 中增加更明确的示例和约束 |
### 8.4 性能优化建议
```bash
# 1. 在大型项目中，让 Claude 专注于特定目录
claude "只分析 src/components/ 目录下的代码质量"
# 2. 使用 Plan 模式先规划再执行，避免浪费 Token
claude --plan "重构整个认证模块"
# 3. 用 .claudeignore 排除不相关文件
cat > .claudeignore << 'EOF'
node_modules/
dist/
.git/
*.min.js
*.map
EOF
```
---
## 九、从零到一的完整工作流总结
```mermaid
flowchart TD
A[安装 Node.js] --> B[npm install -g @anthropic-ai/claude-code]
B --> C[获取 API Key]
C --> D[claude 启动首次认证]
D --> E[创建项目目录]
E --> F[编写 CLAUDE.md]
F --> G[启动 Claude Code]
G --> H[描述需求]
H --> I[审查 Claude 的代码]
I --> J{满意?}
J -->|是| K[确认修改]
J -->|否| L[提供反馈]
L --> H
K --> M[运行测试]
M --> N[继续迭代]
style A fill:#e3f2fd
style F fill:#fff3e0
style K fill:#e8f5e9
style N fill:#fce4ec
```
### 关键心态转变
| 传统开发 | Claude Code 开发 |
|---------|-----------------|
| 你写代码 | 你描述需求，AI 写代码 |
| 你调试 | 你描述症状，AI 排查修复 |
| 你搜索文档 | AI 直接读取并应用 |
| 逐行理解每行代码 | 审查 AI 输出的关键逻辑 |
| 重复写样板代码 | 专注于架构和业务逻辑 |
---
## 十、下一步学习路径
掌握基础后，建议按以下顺序深入学习：
1. **Plan 模式**：学会先让 Claude 规划方案再执行，避免走弯路
2. **MCP 服务器**：为 Claude Code 添加自定义工具（数据库操作、API 调用等）
3. **Skills 体系**：将常用工作流封装为可复用的 Skill
4. **Hooks 自动化**：在特定事件触发时自动执行脚本
5. **多 Agent 协作**：用 SubAgent 并行处理复杂任务
---
## 延伸阅读
- [Claude Code 官方文档 - Quickstart](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速上手指南
- [Claude Code 官方文档 - Best Practices](https://code.claude.com/docs/en/best-practices) — 官方最佳实践
- [Claude Code 官方文档 - Memory](https://code.claude.com/docs/en/memory) — CLAUDE.md 记忆系统完整说明
- [Claude Code 官方文档 - Setup](https://code.claude.com/docs/en/setup) — 高级安装配置指南
---
## 参考来源
1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速入门文档，涵盖安装、认证、基础命令
2. [Advanced Setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 系统要求、平台安装、版本管理详细说明
3. [Best Practices - Claude Code Docs](https://code.claude.com/docs/en/best-practices) — 官方最佳实践，从环境配置到并行会话扩展
4. [Claude Code Tutorial for Beginners - CodeWithMukesh](https://codewithmukesh.com/blog/claude-code-for-beginners/) — 2026 年完整入门教程，含 CLAUDE.md 配置和 Plan Mode 详解
5. [Claude Code: Complete Guide to Installation - NeuroHive](https://neurohive.io/en/guides/claude-code-getting-started-guide/) — 终端 CLI 和桌面应用安装全流程指南
---
## 训练营适用性评估
| 评估维度 | 说明 |
|---------|------|
| 适合训练营类型 | AI 编程入门营、前端开发训练营、企业内训数字化转型营 |
| 教学时长 | 半天（3-4 小时），含实操练习 |
| 学员基础要求 | 会使用终端/命令行即可，无需 AI 工具经验 |
| 实操占比 | 70% 实操 + 30% 讲解 |
| 硬件要求 | 每人一台笔记本（macOS/Linux/Windows+WSL2），能联网 |
| 课程节奏 | 安装30分钟 → 认证15分钟 → CLAUDE.md讲解20分钟 → 项目实战90分钟 → 总结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 等场景全覆盖。
