主题
概述
React 是由 Meta（原 Facebook）开发的开源前端库，采用组件化开发模式，拥有庞大的生态系统。ThesisAI 生成的 React 项目使用 Vite 作为构建工具，配合 TypeScript 提供类型安全的开发体验。
为什么选择 React？
- 生态丰富：海量第三方库和组件库
- 组件化：一切皆组件，复用性强
- TypeScript 支持：完整的类型定义和开发体验
- 社区活跃：全球最大的前端社区之一
技术特性
| 特性 | 说明 |
|---|---|
| 编程语言 | TypeScript / JavaScript |
| 构建工具 | Vite |
| 状态管理 | Zustand / Redux Toolkit / Jotai / React Query |
| UI 组件库 | Ant Design / Material UI / Chakra UI |
| 路由 | React Router |
| 请求库 | Axios / Fetch |
| 样式方案 | Tailwind CSS / CSS Modules |
| 性能评分 | ★★★★☆ |
| 学习曲线 | 中等 |
生成的项目结构
ThesisAI 生成的 React 项目采用清晰的分层架构：
frontend/
├── src/
│ ├── main.tsx # 入口文件
│ ├── App.tsx # 根组件
│ ├── components/ # 通用组件
│ │ ├── ui/ # UI 基础组件
│ │ └── layout/ # 布局组件
│ ├── pages/ # 页面组件
│ ├── hooks/ # 自定义 Hooks
│ ├── services/ # API 服务层
│ ├── stores/ # 状态管理
│ ├── styles/ # 样式文件
│ ├── types/ # TypeScript 类型定义
│ └── utils/ # 工具函数
├── public/ # 静态资源
├── index.html # HTML 模板
├── vite.config.ts # Vite 配置
├── tsconfig.json # TypeScript 配置
├── package.json
└── .env.example # 环境变量示例开发环境
环境要求
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Node.js | >= 18.0 | 推荐 LTS 版本 |
| pnpm | >= 8.0 | 包管理器 |
安装依赖
bash
cd frontend
pnpm install首次运行
首次运行需要安装依赖，这可能需要几分钟时间。
环境变量
bash
cp .env.example .env| 变量名 | 说明 | 必填 | 默认值 |
|---|---|---|---|
VITE_API_URL | 后端 API 地址 | 是 | http://localhost:3000 |
VITE_APP_TITLE | 应用标题 | 否 | My App |
环境变量命名
Vite 项目中的环境变量必须以 VITE_ 开头才能在代码中访问。以 VITE_ 开头的变量会被注入到客户端代码中，不要在 VITE_ 变量中存放密钥等敏感信息。
启动开发服务器
bash
pnpm run dev:::success 服务启动成功
- 开发地址:
http://localhost:5173
如果看到页面正常显示，说明前端启动成功！ :::
状态管理
项目可能使用以下状态管理方案之一（具体以 package.json 为准）：
| 方案 | 说明 | 适用场景 |
|---|---|---|
| Zustand | 轻量级状态管理，API 简洁 | 中小型项目首选 |
| Redux Toolkit | Redux 官方工具包，功能完整 | 大型项目、复杂状态 |
| Jotai | 原子化状态管理，灵活组合 | 需要细粒度控制 |
| React Query | 服务端状态管理，内置缓存 | API 数据管理 |
常用命令
| 命令 | 说明 |
|---|---|
pnpm run dev | 开发模式启动（热重载） |
pnpm run build | 生产构建 |
pnpm run preview | 预览生产构建 |
pnpm run lint | 代码检查 |
pnpm run type-check | TypeScript 类型检查 |
常见问题
白屏或页面空白
- 打开浏览器开发者工具（F12）
- 查看 Console 面板的错误信息
- 常见原因：
- API 地址配置错误
- 后端服务未启动
- 路由配置问题
API 请求 404
确保：
- 后端服务已启动
.env中的VITE_API_URL地址正确- 后端 CORS 已配置允许前端来源
样式错乱
- 清除浏览器缓存（Ctrl+Shift+R 强制刷新）
- 删除
node_modules/.vite缓存目录 - 重新启动开发服务器
TypeScript 类型错误
bash
pnpm run type-check查看具体错误并修复类型问题。
热更新不生效
- 检查文件是否正确保存
- 尝试重启开发服务器
- 清除 Vite 缓存：
bash
rm -rf node_modules/.vite && pnpm run dev开发工具推荐
- React Developer Tools - 浏览器扩展，用于调试 React 组件树和状态
- Redux DevTools - 如果项目使用 Redux，用于调试状态变化
- TypeScript Vue Plugin (Volar) - 在 VS Code 中获得更好的 TS 支持