# Claude Code + React 19 全栈入门：从组件到部署全实战
## 概述
本教程面向零基础开发者，手把手教你用 **Claude Code** 驱动开发一个完整的 React 19 + Vite 项目。你将掌握 Claude Code 的安装认证、核心命令、权限管理、CLAUDE.md 配置，最终交付一个可部署的任务管理应用。适合希望用 AI 编程工具提升效率的前端新手和全栈初学者。
## 前置条件
| 条件 | 说明 |
|------|------|
| 操作系统 | macOS / Linux / Windows (WSL2) |
| Node.js | >= 18.x（推荐 LTS 版本） |
| 包管理器 | npm（随 Node.js 安装） |
| 编辑器 | VS Code（可选但推荐） |
| 账户 | Anthropic Claude Pro / Max / Team 或 API Key |
| 基础知识 | 了解 HTML/CSS/JavaScript 基础即可 |
---
## 第一步：安装 Claude Code
### 1.1 系统准备
确保 Node.js 和 npm 已安装：
```bash
node --version # 应输出 v18.x 或更高
npm --version # 应输出 9.x 或更高
```
如果没有安装 Node.js，推荐使用 `nvm` 管理版本：
```bash
# macOS / Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
```
Windows 用户建议先安装 WSL2（Windows Subsystem for Linux），在 WSL 内操作：
```powershell
wsl --install
# 重启后打开 Ubuntu 终端继续
```
### 1.2 安装 Claude Code CLI
Claude Code 有两种安装方式——npm 全局安装和原生安装器：
**方式一：npm 全局安装（推荐）**
```bash
npm install -g @anthropic-ai/claude-code
```
**方式二：macOS Homebrew 安装**
```bash
brew install claude-code
```
安装完成后验证：
```bash
claude --version
# 应输出类似 claude-code/1.x.x
```
**常见问题：**
| 问题 | 解决方案 |
|------|----------|
| `EACCES: permission denied` | 不要用 `sudo`，修复 npm 全局目录权限：`mkdir ~/.npm-global && npm config set prefix '~/.npm-global'`，然后添加到 PATH |
| `command not found: claude` | 确认 npm 全局 bin 目录在 PATH 中：`npm config get prefix` 检查路径 |
| WSL 内网络连接失败 | 确认 WSL2 可以访问外网：`ping google.com`，如不行检查 `/etc/resolv.conf` |
### 1.3 认证登录
```bash
claude
```
首次运行会启动浏览器进行 OAuth 认证。根据你的账户类型：
- **Claude Pro/Max/Team 订阅用户**：浏览器打开后登录即可，认证信息保存在本地 `~/.claude/` 目录
- **API Key 用户**：设置环境变量 `ANTHROPIC_API_KEY`：
```bash
export ANTHROPIC_API_KEY="sk-ant-api03-..."
```
为避免每次设置，写入 shell 配置文件：
```bash
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.bashrc
source ~/.bashrc
```
认证成功后，终端会显示 Claude Code 的交互式界面（REPL），光标闪烁等待输入。
---
## 第二步：创建 React 19 项目
### 2.1 用 Claude Code 初始化项目
在终端中创建项目目录并启动 Claude Code：
```bash
mkdir ~/taskflow && cd ~/taskflow
claude
```
在 Claude Code REPL 中输入：
```
> 帮我用 Vite 创建一个 React 19 项目，使用 TypeScript 模板，项目名叫 taskflow
```
Claude Code 会执行类似以下命令：
```bash
npm create vite@latest . -- --template react-ts
npm install
```
**预期输出：**
```
✔ 帮我用 Vite 创建一个 React 19 项目...
> Running: npm create vite@latest . -- --template react-ts
> Running: npm install
✅ 项目已创建，React 19 + TypeScript + Vite 就绪
```
Claude Code 在执行每一步之前都会请求你的确认。你会看到工具调用的审批提示——按 `y` 或 Enter 同意。
### 2.2 理解 Claude Code 的交互模式
Claude Code 的 REPL 有三种输入模式：
```text
graph TD
A[Claude Code REPL] --> B[普通输入模式]
A --> C[Shift+Enter: 多行输入]
A --> D[斜杠命令: /xxx]
B --> B1[直接提问或下指令]
C --> C1[粘贴代码块/多步指令]
D --> D1[执行内置命令]
D --> D2[/clear /compact /init]
D --> D3[/model /review /vim]
```
**核心快捷键速查：**
| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Shift+Enter` | 插入新行（多行输入） |
| `Escape` | 取消当前操作/中断生成 |
| `Ctrl+C` | 中断 Claude 正在执行的工具调用 |
| `↑` / `↓` | 浏览历史消息 |
| `Ctrl+L` | 清屏 |
> **提示：** 如果你的终端不支持 `Shift+Enter`（常见于某些终端模拟器），可以在 `~/.claude/settings.json` 中配置：
> ```json
> {
> "terminal": {
> "shiftEnterNewline": true
> }
> }
> ```
### 2.3 确认 React 19 版本
在 Claude Code 中验证 React 版本：
```
> 检查 package.json，确认 React 版本是 19.x，如果不是就升级
```
React 19 的关键特性包括：Actions、`useFormStatus`、`useOptimistic`、Server Components（需要框架支持）、改进的 `ref` 作为 prop 等。
---
## 第三步：CLAUDE.md 项目配置
### 3.1 为什么需要 CLAUDE.md
`CLAUDE.md` 是 Claude Code 的"项目说明书"。每次会话开始时，Claude Code 会自动读取它，理解项目的架构、约定和偏好，从而给出更精准的代码建议。
### 3.2 创建 CLAUDE.md
让 Claude Code 自动生成初始配置：
```
> 运行 /init 生成项目配置文件
```
或者手动创建 `~/taskflow/CLAUDE.md`：
```markdown
# TaskFlow - 任务管理应用
## 技术栈
- React 19 + TypeScript
- Vite 构建工具
- CSS Modules 样式方案
- Vitest 单元测试
## 项目结构
- `src/components/` - React 组件，每个组件一个目录
- `src/hooks/` - 自定义 Hooks
- `src/types/` - TypeScript 类型定义
- `src/utils/` - 工具函数
## 编码规范
- 使用函数式组件 + Hooks
- 组件文件名使用 PascalCase
- 工具函数文件名使用 camelCase
- CSS 类名使用 BEM 命名
- 所有组件必须有 TypeScript 类型
## 命令
- `npm run dev` - 启动开发服务器
- `npm run build` - 构建生产版本
- `npm run test` - 运行测试
- `npm run lint` - 代码检查
```
### 3.3 配置层次结构
Claude Code 的配置系统有五个层级，优先级从高到低：
```mermaid
graph BT
A["CLAUDE.md
(项目根目录)"] -->|最高优先级| B[".claude/rules/*.md
(模块化规则)"]
B --> C["~/.claude/CLAUDE.md
(全局用户配置)"]
C --> D[".claude/settings.json
(项目设置)"]
D -->|最低优先级| E["~/.claude/settings.json
(全局设置)"]
style A fill:#4CAF50,color:#fff
style B fill:#66BB6A,color:#fff
style C fill:#81C784,color:#fff
style D fill:#A5D6A7,color:#333
style E fill:#C8E6C9,color:#333
```
- **项目级 CLAUDE.md**：跟着项目走，提交到 Git，团队共享
- **全局级 CLAUDE.md**：你的个人偏好，不提交到 Git
- **settings.json**：控制工具权限、MCP 服务器等结构性配置
---
## 第四步：开发任务管理应用
### 4.1 设计数据模型
在 Claude Code REPL 中描述需求：
```
> 设计一个任务管理应用的数据模型。任务(Task)有以下属性：
> - id: 唯一标识
> - title: 任务标题
> - description: 任务描述（可选）
> - status: 待办/进行中/已完成
> - priority: 高/中/低
> - createdAt: 创建时间
> - updatedAt: 更新时间
>
> 请创建 TypeScript 类型定义文件 src/types/task.ts
```
Claude Code 生成的代码大致如下：
```typescript
// src/types/task.ts
export type TaskStatus = 'todo' | 'in-progress' | 'done';
export type TaskPriority = 'high' | 'medium' | 'low';
export interface Task {
id: string;
title: string;
description?: string;
status: TaskStatus;
priority: TaskPriority;
createdAt: string;
updatedAt: string;
}
export type CreateTaskInput = Omit;
export type UpdateTaskInput = Partial & Pick;
```
### 4.2 创建自定义 Hook
```
> 创建一个 useTasks 自定义 Hook，管理任务的 CRUD 操作。
> 使用 useState 管理状态，支持添加、删除、更新、筛选任务。
> 初始数据包含 3 个示例任务。文件放在 src/hooks/useTasks.ts
```
这个指令展示了 Claude Code 的核心优势——你只需描述 **"做什么"**，它负责 **"怎么做"**。
### 4.3 构建组件
接下来逐个构建 UI 组件：
```
> 创建以下组件，全部使用 CSS Modules：
> 1. TaskBoard - 看板布局，三列展示不同状态的任务
> 2. TaskCard - 单个任务卡片，显示标题、优先级标签、操作按钮
> 3. TaskForm - 添加/编辑任务的表单，包含标题、描述、优先级选择
> 4. FilterBar - 筛选栏，按优先级和状态筛选任务
>
> 每个组件一个目录，包含 index.tsx 和 styles.module.css
> 主入口 App.tsx 组装所有组件
```
Claude Code 会一次性创建多个文件，每个文件创建前都会请求确认。你可以逐个审查，也可以在权限设置中开放文件写入权限。
**权限控制提示：** 如果不想每次确认，可以临时允许：
```
> 允许在 src/components/ 目录下创建文件，不需要每次确认
```
或者在 `.claude/settings.json` 中配置：
```json
{
"permissions": {
"allow": [
"Edit(src/**)",
"Write(src/**)",
"Bash(npm run *)"
]
}
}
```
### 4.4 添加交互功能
```
> 为 TaskCard 添加以下交互：
> 1. 点击卡片展开详情（使用 React 19 的 原生支持）
> 2. 拖拽排序功能（用 HTML5 Drag and Drop API）
> 3. 删除前弹出确认对话框
> 4. 状态切换时有过渡动画
```
### 4.5 运行开发服务器
```
> 启动开发服务器，打开浏览器看看效果
```
Claude Code 会执行：
```bash
npm run dev
```
**预期输出：**
```
VITE v6.x.x ready in xxx ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
```
在浏览器中访问 `http://localhost:5173/` 即可看到应用。
---
## 第五步：掌握核心命令与技巧
### 5.1 必学斜杠命令
| 命令 | 用途 | 使用频率 |
|------|------|----------|
| `/clear` | 清除当前会话上下文 | 每次切换任务时使用 |
| `/compact` | 压缩上下文（保留摘要，释放 token） | 上下文接近上限时使用 |
| `/init` | 生成/更新 CLAUDE.md 配置 | 新项目初始化 |
| `/review` | 代码审查 | 提交前使用 |
| `/model` | 切换模型（Haiku/Sonnet/Opus） | 按任务复杂度切换 |
| `/vim` | 启用 Vim 键绑定 | Vim 用户必开 |
| `/mcp` | 管理 MCP 服务器 | 配置外部工具时使用 |
| `/doctor` | 诊断 Claude Code 运行状况 | 遇到问题时排查 |
### 5.2 上下文管理策略
Claude Code 的上下文窗口是有限的。以下是保持高效的最佳实践：
```mermaid
flowchart TD
A[开始新任务] --> B{任务相关吗？}
B -->|是，继续当前会话| C[直接提问]
B -->|否，全新任务| D["/clear 清除上下文"]
D --> E[开始新话题]
C --> F{上下文太长？}
F -->|是| G["/compact 压缩"]
F -->|否| H[继续工作]
G --> H
style D fill:#FF9800,color:#fff
style G fill:#FF9800,color:#fff
style A fill:#4CAF50,color:#fff
```
**关键原则：**
- **一个会话聚焦一个任务**：切换大任务时用 `/clear`
- **长会话定期压缩**：用 `/compact` 保留关键信息，丢弃冗余细节
- **小任务用 Haiku**：`/model` 切换到 Haiku，省钱且快速
- **复杂架构讨论用 Opus**：需要深度推理时切换
### 5.3 模型选择指南
```mermaid
graph LR
A[任务复杂度] --> B[简单：格式化/小修改]
A --> C[中等：新功能/调试]
A --> D[复杂：架构设计/重构]
B --> E["Haiku
快速且便宜"]
C --> F["Sonnet
平衡之选"]
D --> G["Opus
最强推理"]
style E fill:#81C784
style F fill:#FFB74D
style G fill:#E57373
```
### 5.4 提示词编写技巧
与 Claude Code 交互时，好的提示词能大幅提升代码质量：
**差的提示词：**
```
> 做一个好看的页面
```
**好的提示词：**
```
> 创建一个任务看板页面，要求：
> - 三列布局：待办、进行中、已完成
> - 每个任务卡片显示标题、优先级色标（高红/中黄/低绿）
> - 支持拖拽移动任务到不同列
> - 响应式设计，移动端纵向排列
> - 参考 Trello 的视觉风格，圆角卡片 + 柔和阴影
```
**提示词公式：**
```
动作 + 具体需求列表 + 技术约束 + 视觉/风格参考
```
---
## 第六步：测试与质量保障
### 6.1 配置测试环境
```
> 配置 Vitest 测试环境，安装 @testing-library/react 和 jsdom。
> 创建一个测试示例文件验证配置是否正确
```
### 6.2 编写测试
```
> 为 useTasks Hook 编写完整的单元测试：
> - 测试初始状态包含 3 个示例任务
> - 测试添加任务
> - 测试删除任务
> - 测试更新任务状态
> - 测试按优先级筛选
> - 测试按状态筛选
> 使用 vitest 和 @testing-library/react-hooks
```
### 6.3 代码审查
在提交前用 `/review` 命令让 Claude Code 审查代码：
```
> /review 检查整个项目的代码质量，重点关注：
> 1. TypeScript 类型安全性
> 2. React 19 最佳实践
> 3. 性能问题（不必要的重渲染）
> 4. 可访问性（a11y）
```
---
## 第七步：权限与安全配置
### 7.1 三级权限模型
Claude Code 的权限系统分为三个层级：
```mermaid
graph TD
A[权限模式] --> B["🟢 Allow
自动批准，无需确认"]
A --> C["🟡 Ask
每次执行前询问"]
A --> D["🔴 Deny
完全禁止"]
B --> B1["例：读取项目内文件"]
C --> C1["例：执行 npm 命令"]
D --> D1["例：删除文件、访问敏感路径"]
style B fill:#4CAF50,color:#fff
style C fill:#FF9800,color:#fff
style D fill:#F44336,color:#fff
```
### 7.2 配置权限
在 `.claude/settings.json` 中精细控制：
```json
{
"permissions": {
"allow": [
"Read(*)",
"Edit(src/**)",
"Write(src/**)",
"Bash(npm run *)",
"Bash(npm test *)",
"Bash(git status)",
"Bash(git diff *)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(git push --force *)",
"Read(.env*)",
"Write(.env*)"
]
}
}
```
### 7.3 沙箱模式
Claude Code 支持操作系统级沙箱，限制文件系统和网络访问：
```bash
# 启用沙箱运行（推荐用于不信任的项目）
claude --sandbox
```
沙箱模式下，Claude Code 的所有文件操作和命令执行都被限制在项目目录内。
---
## 实战案例：完整的 TaskFlow 项目
### 项目最终结构
```
taskflow/
├── CLAUDE.md # Claude Code 项目配置
├── .claude/
│ └── settings.json # 权限和工具配置
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── src/
│ ├── main.tsx # 应用入口
│ ├── App.tsx # 根组件
│ ├── App.module.css
│ ├── types/
│ │ └── task.ts # 类型定义
│ ├── hooks/
│ │ └── useTasks.ts # 任务管理 Hook
│ ├── components/
│ │ ├── TaskBoard/
│ │ │ ├── index.tsx
│ │ │ └── styles.module.css
│ │ ├── TaskCard/
│ │ │ ├── index.tsx
│ │ │ └── styles.module.css
│ │ ├── TaskForm/
│ │ │ ├── index.tsx
│ │ │ └── styles.module.css
│ │ └── FilterBar/
│ │ ├── index.tsx
│ │ └── styles.module.css
│ └── utils/
│ └── id.ts # ID 生成工具
├── __tests__/
│ ├── useTasks.test.ts
│ └── TaskCard.test.tsx
└── public/
└── favicon.svg
```
### 完整开发工作流
```mermaid
flowchart LR
A["1. 创建项目
npm create vite"] --> B["2. 配置 Claude
CLAUDE.md"]
B --> C["3. 定义类型
src/types/"]
C --> D["4. 构建 Hook
src/hooks/"]
D --> E["5. 开发组件
src/components/"]
E --> F["6. 测试验证
npm run test"]
F --> G["7. 代码审查
/review"]
G --> H["8. 构建部署
npm run build"]
style A fill:#E3F2FD
style B fill:#E8F5E9
style C fill:#FFF3E0
style D fill:#F3E5F5
style E fill:#FFEBEE
style F fill:#E0F7FA
style G fill:#FFF9C4
style H fill:#C8E6C9
```
### 关键代码片段
**App.tsx 根组件：**
```tsx
import { TaskBoard } from './components/TaskBoard';
import { useTasks } from './hooks/useTasks';
import styles from './App.module.css';
function App() {
const {
tasks,
addTask,
deleteTask,
updateTask,
filterByStatus,
filterByPriority,
} = useTasks();
return (
TaskFlow
用 Claude Code 构建的任务管理器
);
}
export default App;
```
### 部署到 Vercel
```
> 帮我将项目部署到 Vercel。先构建确认没有错误，然后用 Vercel CLI 部署
```
Claude Code 会执行：
```bash
npm run build
npx vercel --prod
```
**预期输出：**
```
✓ Build successful.
🔍 Deploying...
✅ Production: https://taskflow-xxx.vercel.app
```
---
## 高效工作流总结
### Claude Code 驱动的开发节奏
```mermaid
sequenceDiagram
participant D as 开发者
participant CC as Claude Code
participant FS as 文件系统
participant BR as 浏览器
D->>CC: 描述需求
CC->>CC: 分析上下文 & 规划
CC->>D: 展示计划（待审批）
D->>CC: 确认执行
CC->>FS: 创建/修改文件
CC->>D: 展示变更结果
D->>CC: 提出调整或新需求
CC->>FS: 执行修改
CC->>BR: 启动 dev server 预览
D->>CC: /review 审查代码
CC->>D: 审查报告
D->>CC: 确认构建
CC->>FS: npm run build
```
### 提效五条黄金法则
1. **CLAUDE.md 写清楚**：项目结构、编码规范、技术栈、常用命令——Claude Code 理解越多，输出越精准
2. **任务拆小**：一次请求一个明确的功能点，比一次性描述整个系统效果好 10 倍
3. **善用 `/compact`**：长会话中每完成一个阶段就压缩一次上下文
4. **分级授权**：信任的目录配置 `allow`，敏感操作保持 `ask` 或 `deny`
5. **审查再提交**：`/review` 是免费的代码审查，提交前必用
---
## 延伸阅读
| 资源 | 说明 |
|------|------|
| [Claude Code 官方文档](https://code.claude.com/docs/en/quickstart) | Anthropic 官方快速入门指南 |
| [Claude Code Best Practices](https://code.claude.com/docs/en/best-practices) | 官方最佳实践文档 |
| [Claude Code 命令参考](https://code.claude.com/docs/en/commands) | 完整斜杠命令和 CLI 参数参考 |
| [Claude Code 权限配置](https://code.claude.com/docs/en/permissions) | 权限模型和沙箱配置详解 |
| [Claude Code 终端配置](https://code.claude.com/docs/en/terminal-config) | 终端兼容性和快捷键设置 |
---
## 训练营适用性评估
| 维度 | 评估 |
|------|------|
| **适合训练营类型** | AI 编程工具入门营、前端零基础训练营、全栈工程师速成营 |
| **目标学员** | 零编程经验到 1 年经验的前端初学者 |
| **预计教学时长** | 4-6 小时（含实操练习） |
| **前置课程** | 无（HTML/CSS/JS 基础即可） |
| **后续课程建议** | Claude Code Skills 开发、MCP 服务器构建、Agent 自动化 |
| **实操占比** | 70% 实操 + 30% 讲解 |
| **所需设备** | 笔记本电脑（macOS/Linux/WSL2）、稳定网络、Claude Pro 及以上订阅 |
---
## 参考来源
1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速入门指南，涵盖安装、认证、首次使用
2. [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) — 官方最佳实践文档，上下文管理和工作流建议
3. [Claude Code Tutorial 2026: Complete Beginner's Guide](https://www.nxcode.io/resources/news/claude-code-tutorial-beginners-guide-2026) — 第三方完整入门教程，命令详解和实战案例
4. [Configure permissions - Claude Code Docs](https://code.claude.com/docs/en/permissions) — 权限系统官方参考，三级模型和沙箱配置
5. [45 Claude Code Tips: From Basics to Advanced](https://github.com/ykdojo/claude-code-tips) — 社区维护的 Claude Code 使用技巧集合
> [!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 等场景全覆盖。
