React

v18.x

TypeScript

官方网站 GitHub

React 是 Facebook 开发的前端框架，生态丰富，组件化开发。

📋 前置要求

Node.js 18+ 已安装

pnpm 已安装

已下载生成的项目代码

📁 项目结构

frontend

src

main.tsx // 入口文件

App.tsx // 根组件

components // 组件目录

ui // UI 基础组件

layout // 布局组件

pages // 页面组件

hooks // 自定义 Hooks

services // API 服务

stores // 状态管理

styles // 样式文件

utils // 工具函数

public // 静态资源

index.html // HTML 模板

vite.config.ts // Vite 配置

tsconfig.json // TypeScript 配置

package.json

🚀 运行步骤

第 1 步：进入项目目录

bash

        $
        cd frontend
      

第 2 步：安装依赖

bash

        $
        pnpm install
      

首次运行

首次运行需要安装依赖，这可能需要几分钟时间。

第 3 步：配置环境变量

复制环境变量示例文件：

bash

        $
        cp .env.example .env
      

编辑 .env 文件：

变量名	说明	必填
VITE_API_URL 默认值: http://localhost:3000	后端 API 地址	是
VITE_APP_TITLE 默认值: My App	应用标题	否

环境变量命名

Vite 项目中的环境变量必须以 `VITE_` 开头才能在代码中访问。

第 4 步：启动开发服务器

bash

        $
        pnpm run dev
      

第 5 步：验证运行

服务启动后，在浏览器访问：

http://localhost:5173

启动成功

如果看到页面正常显示，说明前端启动成功！

🔧 常用命令

命令	说明
pnpm run dev	开发模式启动
pnpm run build	生产构建
pnpm run preview	预览生产构建
pnpm run lint	代码检查
pnpm run type-check	类型检查

🎨 UI 组件库

项目可能使用以下 UI 组件库之一：

组件库	说明
Ant Design	企业级 UI 组件库
Material UI	Google Material Design 风格
Chakra UI	简洁灵活的组件库

查看项目的 package.json 确认使用的是哪个 UI 库。

📦 状态管理

项目可能使用以下状态管理方案：

• Zustand - 轻量级状态管理
• Redux Toolkit - Redux 官方工具包
• Jotai - 原子化状态管理
• React Query - 服务端状态管理

❓ 常见问题

白屏或页面空白

1. 打开浏览器开发者工具（F12）
2. 查看 Console 面板的错误信息
3. 常见原因：
   • API 地址配置错误
   • 后端服务未启动
   • 路由配置问题

API 请求 404

确保：

1. 后端服务已启动
2. .env 中的 VITE_API_URL 地址正确
3. 后端 CORS 已配置

样式错乱

1. 清除浏览器缓存
2. 删除 node_modules/.vite 目录
3. 重新启动开发服务器

TypeScript 类型错误

bash

        $
        pnpm run type-check
      

查看具体错误并修复类型问题。

热更新不生效

1. 检查文件是否正确保存
2. 尝试重启开发服务器
3. 清除 Vite 缓存：

bash

        $
        rm -rf node_modules/.vite && pnpm run dev
      

🔍 开发工具推荐

• React Developer Tools - 浏览器扩展，调试 React 组件
• Redux DevTools - 如果使用 Redux，调试状态变化

⏭️ 下一步

• 同时运行前后端
• 部署项目