# react+hooks+ts+vite模版

**Repository Path**: chen1142399899/react-hooks-ts-vite-template

## Basic Information

- **Project Name**: react+hooks+ts+vite模版
- **Description**: react18+vite+ts+antd模版 拒绝花里胡哨
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2024-07-04
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# React + TypeScript + Vite 企业级管理系统模板

一个基于 React 18 + TypeScript + Vite + Ant Design 5 的现代化企业级管理系统模板，包含完整的权限管理、路由守卫、状态管理等企业级功能。

## ✨ 核心特性

- 🚀 **现代化技术栈**：React 18 + TypeScript + Vite
- 🎨 **UI 框架**：Ant Design 5.16.1，开箱即用的高质量组件
- 🔐 **权限管理**：基于路由和菜单的权限控制系统，支持角色和权限双重验证
- 📦 **状态管理**：Redux Toolkit，现代化的状态管理方案
- 🛣️ **路由管理**：React Router v6 + RouterProvider，支持懒加载和权限拦截
- 🎯 **TypeScript**：完整的类型定义，提供良好的开发体验
- 📱 **响应式设计**：支持移动端适配
- 🎨 **样式方案**：SCSS + CSS Modules，支持主题定制
- 🔧 **代码分割**：路由懒加载，优化首屏加载速度

## 📦 使用的插件和依赖

### 核心依赖

| 包名 | 版本 | 说明 |
|------|------|------|
| react | ^18.2.0 | React 核心库 |
| react-dom | ^18.2.0 | React DOM 渲染库 |
| react-router-dom | ^6.22.3 | React 路由库 |
| @reduxjs/toolkit | ^2.2.3 | Redux 工具包 |
| react-redux | ^9.1.1 | React Redux 绑定 |
| antd | ^5.16.1 | Ant Design UI 组件库 |
| @ant-design/icons | ^5.3.6 | Ant Design 图标库 |
| axios | ^1.6.8 | HTTP 请求库 |
| sass | ^1.74.1 | SCSS 预处理器 |

### 开发依赖

| 包名 | 版本 | 说明 |
|------|------|------|
| vite | ^5.2.0 | 构建工具 |
| @vitejs/plugin-react-swc | ^3.5.0 | Vite React 插件（SWC 编译） |
| vite-plugin-imp | ^2.4.0 | Ant Design 按需加载插件 |
| typescript | ^5.2.2 | TypeScript 编译器 |
| @typescript-eslint/eslint-plugin | ^7.2.0 | TypeScript ESLint 插件 |
| @typescript-eslint/parser | ^7.2.0 | TypeScript ESLint 解析器 |
| eslint | ^8.57.0 | 代码检查工具 |
| eslint-plugin-react-hooks | ^4.6.0 | React Hooks ESLint 插件 |
| eslint-plugin-react-refresh | ^0.4.6 | React Refresh ESLint 插件 |

## 📁 项目结构

```
react-hooks-ts-vite-template-master/
├── public/                 # 静态资源目录
├── src/
│   ├── assets/            # 资源文件
│   │   ├── style/         # 全局样式
│   │   │   ├── variables.scss  # SCSS 变量
│   │   │   └── main.scss      # 全局样式
│   │   └── react.svg      # SVG 图标
│   ├── layout/            # 布局组件
│   │   ├── index.tsx      # 主布局组件
│   │   ├── index.scss     # 布局样式
│   │   ├── breadcrumb/    # 面包屑导航
│   │   │   ├── index.tsx
│   │   │   └── index.scss
│   │   └── selectNav/     # 用户下拉菜单
│   │       ├── index.tsx
│   │       └── index.module.scss
│   ├── pages/             # 页面组件
│   │   ├── dashboard/     # 仪表盘
│   │   ├── login/         # 登录页
│   │   ├── system/        # 系统管理
│   │   │   ├── user/      # 用户管理
│   │   │   ├── role/      # 角色管理
│   │   │   └── settings/  # 系统设置
│   │   ├── commonUse/     # 常用功能
│   │   ├── 404/           # 404 页面
│   │   └── ...
│   ├── router/            # 路由配置
│   │   ├── index.tsx      # 路由导出
│   │   ├── config.tsx      # 路由配置
│   │   ├── createRouter.tsx  # 创建路由实例
│   │   ├── loader.tsx     # 路由加载器（权限检查）
│   │   ├── components.tsx # 路由组件（Loading、withSuspense）
│   │   ├── types.ts       # 路由类型定义
│   │   ├── utils.ts       # 路由工具函数
│   │   ├── exports.ts     # 路由导出（避免 Fast Refresh 警告）
│   │   ├── guard.tsx      # 路由守卫（已废弃，使用 loader.tsx）
│   │   └── README.md      # 路由模块文档
│   ├── store/             # Redux 状态管理
│   │   ├── index.ts       # Store 配置
│   │   ├── modules/       # 状态模块
│   │   │   ├── auth.ts    # 认证模块
│   │   │   ├── router.ts   # 路由状态模块
│   │   │   └── counterSlice.ts  # 示例模块
│   │   └── reducers/      # Reducer 配置
│   │       └── index.ts
│   ├── utils/             # 工具函数
│   │   ├── request.ts     # HTTP 请求封装
│   │   ├── config.ts      # 配置文件
│   │   └── permission.ts  # 权限工具函数
│   ├── type/              # 类型定义
│   │   └── index.d.ts
│   ├── App.tsx            # 根组件
│   ├── main.tsx           # 入口文件
│   └── index.scss         # 全局样式入口
├── .eslintrc.cjs          # ESLint 配置
├── index.html             # HTML 模板
├── package.json           # 依赖配置
├── tsconfig.json          # TypeScript 配置
├── vite.config.ts         # Vite 配置
└── README.md              # 项目说明文档
```

## 🚀 快速开始

### 环境要求

- Node.js >= 16.0.0
- npm >= 7.0.0 或 pnpm >= 7.0.0

### 安装依赖

```bash
# 使用 npm
npm install

# 或使用 pnpm（推荐）
pnpm install
```

### 启动开发服务器

```bash
npm run dev
```

开发服务器将在 `http://localhost:5173` 启动。

### 构建生产版本

```bash
npm run build
```

构建产物将输出到 `dist` 目录。

### 预览生产构建

```bash
npm run preview
```

### 代码检查

```bash
npm run lint
```

## 🔑 登录账号

项目提供了两个测试账号：

- **管理员**：`admin` / `123456`（拥有所有权限）
- **普通用户**：`user` / `123456`（拥有部分权限）

## 📋 功能模块

### 1. 仪表盘（Dashboard）
- 数据统计展示
- 最近交易记录
- 系统信息展示
- 快捷操作入口

### 2. 用户管理
- 用户列表展示
- 新增/编辑/删除用户
- 用户状态管理
- 权限：`system:user:view`

### 3. 角色管理
- 角色列表展示
- 角色权限配置
- 角色管理
- 权限：`system:role:view`

### 4. 系统设置
- 基础设置
- 安全设置
- 通知设置
- 权限：`system:settings:view`

## 🔐 权限系统

### 权限标识格式

权限标识采用 `模块:操作` 的格式，例如：
- `system:view` - 系统管理查看权限
- `system:user:view` - 用户管理查看权限
- `system:user:edit` - 用户管理编辑权限
- `common:use` - 常用功能使用权限
- `common:use:svg` - SVG 功能使用权限
- `component:view` - 组件查看权限

### 路由权限配置

在 `src/router/config.tsx` 中配置路由权限：

```typescript
{
  path: '/system/user',
  element: withSuspense(UserManagement),
  meta: {
    title: '用户管理',
    label: '用户管理',
    icon: <UserOutlined />,
    permissions: ['system:user:view'], // 权限标识数组
    requiresAuth: true, // 是否需要登录
    order: 1 // 菜单排序
  }
}
```

### 组件权限控制

使用 `PermissionWrapper` 组件：

```tsx
import { PermissionWrapper } from '@/utils/permission'

<PermissionWrapper permissions={['system:user:edit']}>
  <Button>需要权限的按钮</Button>
</PermissionWrapper>
```

### 权限检查流程

1. **路由级别**：在 `src/router/loader.tsx` 中进行路由权限检查
2. **菜单级别**：在 `src/layout/index.tsx` 中根据权限过滤菜单
3. **组件级别**：使用 `PermissionWrapper` 组件控制组件显示

## 🛠️ 技术栈详解

### React Router v6 + RouterProvider

项目使用 React Router v6 的 `RouterProvider` API，通过 `createBrowserRouter` 创建路由实例。

**路由加载器（Loader）**：
- 在路由加载前进行权限检查
- 未登录用户自动重定向到登录页
- 无权限用户重定向到首页或 403 页面

**路由配置**：
- 所有路由在 `src/router/config.tsx` 中统一配置
- 支持路由懒加载，优化首屏性能
- 支持嵌套路由和路由元信息

### Redux Toolkit

使用 Redux Toolkit 进行状态管理，包含以下模块：

- **auth**：认证状态（登录状态、用户信息、权限信息）
- **router**：路由状态（当前路由、面包屑等）

### Ant Design 5

- 使用 `vite-plugin-imp` 实现按需加载
- 支持主题定制（通过 SCSS 变量）
- 完整的 TypeScript 类型支持

### HTTP 请求封装

`src/utils/request.ts` 提供了完整的 HTTP 请求封装：

```typescript
import request from '@/utils/request'

// GET 请求
const users = await request.get('/api/users', { page: 1, size: 10 })

// POST 请求（显示成功提示）
await request.post('/api/users', userData, { showSuccess: true })

// PUT 请求
await request.put(`/api/users/${id}`, userData)

// DELETE 请求
await request.delete(`/api/users/${id}`)

// 文件上传
const formData = new FormData()
formData.append('file', file)
await request.upload('/api/upload', formData, { showSuccess: true })
```

**特性**：
- 自动添加 token 到请求头
- 统一错误处理
- 支持请求/响应拦截器
- 自动处理 token 过期

## 📝 开发规范

### 代码规范

- 使用 ESLint 进行代码检查
- 使用 TypeScript 严格模式
- 遵循 React Hooks 最佳实践
- 组件使用函数式组件 + Hooks

### 文件命名规范

- **组件文件**：使用 PascalCase，如 `UserManagement.tsx`
- **工具文件**：使用 camelCase，如 `permission.ts`
- **样式文件**：使用 kebab-case，如 `index.scss`
- **类型文件**：使用 camelCase + `.d.ts`，如 `index.d.ts`

### 目录结构规范

- 每个功能模块独立目录
- 组件、样式、类型文件放在同一目录
- 公共组件放在 `src/components`（如需要）
- 工具函数放在 `src/utils`

### Git 提交规范

建议使用 [Conventional Commits](https://www.conventionalcommits.org/)：

```
feat: 添加用户管理功能
fix: 修复登录跳转问题
docs: 更新 README 文档
style: 调整样式格式
refactor: 重构路由配置
test: 添加单元测试
chore: 更新依赖版本
```

## 🔧 配置说明

### Vite 配置

`vite.config.ts` 主要配置：

- **路径别名**：`@` 指向 `src` 目录
- **Ant Design 按需加载**：使用 `vite-plugin-imp`
- **SCSS 全局变量**：自动注入 `src/assets/style/variables.scss`

### TypeScript 配置

`tsconfig.json` 主要配置：

- **严格模式**：启用所有严格类型检查
- **路径别名**：支持 `@/*` 路径别名
- **JSX**：使用 `react-jsx` 模式

### ESLint 配置

`.eslintrc.cjs` 主要配置：

- TypeScript ESLint 规则
- React Hooks 规则
- React Refresh 规则

## 🎨 样式方案

### SCSS 变量

在 `src/assets/style/variables.scss` 中定义全局变量：

```scss
$primary-color: #1890ff;
$success-color: #52c41a;
$text-primary: #262626;
// ...
```

### 全局样式

在 `src/assets/style/main.scss` 中定义全局样式：

- 卡片样式
- 表格样式
- 按钮样式
- 滚动条样式

### 组件样式

- 使用 SCSS 模块化
- 支持 CSS Modules（`.module.scss`）
- 支持全局样式（`.scss`）

## 🐛 常见问题

### 1. 路由跳转后自动返回登录页

**原因**：权限检查失败或 token 过期

**解决**：
- 检查 `src/store/modules/auth.ts` 中的权限配置
- 检查路由配置中的 `permissions` 是否正确
- 检查 `src/router/loader.tsx` 中的权限检查逻辑

### 2. 菜单不显示

**原因**：权限过滤导致菜单被隐藏

**解决**：
- 检查用户权限是否包含路由所需的权限
- 检查 `src/layout/index.tsx` 中的菜单生成逻辑
- 检查路由配置中的 `hidden` 属性

### 3. TypeScript 类型错误

**原因**：类型定义不完整或类型不匹配

**解决**：
- 检查 `src/router/types.ts` 中的类型定义
- 检查组件 props 的类型定义
- 使用 `as` 进行类型断言（谨慎使用）

### 4. 请求失败或 token 过期

**原因**：HTTP 请求拦截器检测到 token 过期

**解决**：
- 检查 `src/utils/request.ts` 中的拦截器逻辑
- 检查后端返回的状态码
- 重新登录获取新的 token

## 📚 相关文档

- [React 官方文档](https://react.dev/)
- [TypeScript 官方文档](https://www.typescriptlang.org/)
- [Vite 官方文档](https://vitejs.dev/)
- [Ant Design 官方文档](https://ant.design/)
- [React Router 官方文档](https://reactrouter.com/)
- [Redux Toolkit 官方文档](https://redux-toolkit.js.org/)

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 License

MIT License

## 👥 作者

- 项目维护者：[Your Name]
- 邮箱：[your.email@example.com]

## 🙏 致谢

感谢以下开源项目的支持：

- [React](https://react.dev/)
- [Ant Design](https://ant.design/)
- [Vite](https://vitejs.dev/)
- [Redux Toolkit](https://redux-toolkit.js.org/)

---

**注意**：`src/router/guard.tsx` 文件已废弃，权限检查已迁移到 `src/router/loader.tsx`。如需查看旧的守卫实现，请参考该文件。