自荐一个中后台管理的前端模版ELEGANTEER WEB 基于 React + Vite + TypeScript 的现

ELEGANTEER WEB

基于 React + Vite + TypeScript 的现代化前端管理后台模板。对应后台地址：gitee.com/sunjones/ea… 前端地址：gitee.com/sunjones/mi… 觉得可以，麻烦star一下，可以共同改进

技术栈

构建工具: Vite 8 + TypeScript 6
UI 框架: React 19 + MUI 9 (Material UI)
路由: React Router 7
状态管理: Redux Toolkit (RTK Query)
表单: React Hook Form + Zod
HTTP: Axios
国际化: i18next + react-i18next
动画: Framer Motion
认证: OAuth2 Authorization Code + PKCE

环境要求

Node.js >= 20
Yarn >= 4 (推荐) 或 npm

快速开始

1. 安装依赖

# 使用 Yarn (推荐)
yarn install

# 或使用 npm
npm install

2. 配置环境变量

复制 .env 文件并根据实际情况修改：

cp .env .env.local

默认环境变量：

VITE_SERVER_URL=/api              # 后端 API 基础地址
VITE_OAUTH2_CLIENT_ID=eagleWeb    # OAuth2 客户端 ID
VITE_OAUTH2_SCOPE=openid profile phone email address  # OAuth2 授权范围

3. 启动开发服务器

# 使用 Yarn
yarn dev

# 或使用 npm
npm run dev

开发服务器默认运行在 http://localhost:8080

常用命令

# 开发
yarn dev              # 启动开发服务器 (端口 8080)
yarn build            # 构建生产环境 (先执行 tsc 类型检查，再 vite build)

# 代码质量
yarn lint             # ESLint 检查
yarn lint:fix         # ESLint 自动修复
yarn fm:check         # Prettier 格式检查
yarn fm:fix           # Prettier 格式化
yarn fix:all          # 同时执行 lint:fix 和 fm:fix
yarn tsc:watch        # TypeScript 实时类型检查

# 测试
yarn test             # 运行测试 (Vitest)
yarn test:run         # 运行测试一次
yarn test:coverage    # 生成测试覆盖率报告

# 清理与重装
yarn clean            # 删除 node_modules、dist 等
yarn re:dev           # 清理、重装依赖、启动开发
yarn re:build         # 清理、重装依赖、构建

项目结构

src/
├── app.tsx           # 应用根组件，包含所有 Provider 嵌套
├── main.tsx          # 入口，配置 RouterProvider
├── global-config.ts  # 全局配置（OAuth2 客户端、服务端地址等）
├── routes/           # 路由配置
│   ├── sections/     # 路由定义（lazy load 页面）
│   ├── paths.ts      # 路径常量
│   └── hooks/        # 路由相关 hooks
├── auth/             # 认证系统
│   ├── context/oauth2/  # OAuth2 AuthProvider、PKCE、Token 管理
│   ├── guard/           # AuthGuard, GuestGuard, RoleBasedGuard
│   └── hooks/           # useAuthContext, useOAuth2
├── api/              # API 层
│   ├── axios.ts      # axios 实例（含 token 刷新拦截器）
│   ├── base-api.ts   # RTK Query baseApi
│   └── base-query.ts # axios 适配 RTK Query
├── store/            # Redux Store
│   └── slices/       # auth.slice 等
├── features/         # 功能模块（各管理页面的 api.ts、types.ts、页面组件）
├── layouts/          # 布局组件
│   ├── dashboard/    # Dashboard 布局（含侧边栏、导航）
│   ├── core/         # 布局基础组件
│   └── auth-split/   # 认证页面布局
├── theme/            # MUI 主题系统
├── components/       # 可复用组件
├── pages/            # 页面组件
├── locales/          # 国际化
└── lib/              # 工具函数

认证系统

本项目使用标准 OAuth2 Authorization Code + PKCE 流程：

应用启动时通过 /.well-known/oauth-authorization-server 发现认证端点
登录时跳转到发现的 authorization_endpoint，携带 PKCE code_challenge
回调页面通过 token_endpoint 用 code 换 token
用户信息通过 /userinfo 端点获取
Token 过期时通过 refresh_token 自动刷新，刷新失败则重新登录

认证守卫

AuthGuard: 保护需要登录的路由
GuestGuard: 仅限未登录用户访问（如登录页）
RoleBasedGuard: 基于角色的访问控制

代理配置

开发服务器代理配置（vite.config.ts）：

/api/* -> 转发到后端（去掉 /api 前缀）
/.well-known/*, /authorize, /oauth/*, /userinfo, /logout, /login, /connect/* -> 直接转发到后端

注意事项

复制文件夹时请同时复制隐藏文件（如 .env），这些文件通常包含应用运行所需的关键环境变量
开发时如需跳过认证，可将 src/global-config.ts 中的 auth.skip 设为 true
推荐使用 yarn 作为包管理器

自荐一个中后台管理的前端模版