# react-vite-ts-tem **Repository Path**: ikunfami/react-vite-ts-tem ## Basic Information - **Project Name**: react-vite-ts-tem - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-18 - **Last Updated**: 2026-07-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # React + Vite + TypeScript 模板 一个基于 **React 19**、**Vite 8**、**TypeScript 6** 构建的前端项目模板，集成 **Ant Design 6**、**Zustand 5**、**react-router-dom 7**，并配置了 **ESLint 10**、**Prettier 3** 与 **vite-plugin-mock**，适合作为中后台应用或中台项目的起始工程。 ## 技术栈 | 类别 | 技术 | | --------- | -------------------------------------- | | 框架 | React 19 | | 构建工具 | Vite 8 | | 语言 | TypeScript 6 | | UI 组件库 | Ant Design 6 | | 图标 | @ant-design/icons | | 状态管理 | Zustand 5 | | 路由 | react-router-dom 7 | | 请求 | axios | | 日期处理 | dayjs | | 国际化 | i18next + react-i18next | | 样式 | Sass / CSS | | 代码规范 | ESLint 10 + Prettier 3 | | 类型工具 | type-fest | | 包管理器 | pnpm 11.5.1（已锁定 `packageManager`） | ## 项目框架 本项目采用组件化、模块化的前端工程架构： - **视图层**：React 19 + Ant Design 6，函数组件配合 Hooks。 - **路由层**：react-router-dom 7，支持固定路由与基于后端菜单的动态路由。 - **状态层**：Zustand 5，用户信息、菜单、权限持久化到 `localStorage`。 - **网络层**：axios 二次封装，统一处理请求拦截、响应格式、错误提示。 - **Mock 层**：vite-plugin-mock，开发环境下模拟后端接口。 - **构建层**：Vite 8，开发服务器、生产打包、代理转发、版本文件生成。 ## Vite 插件 项目使用以下 Vite 插件（配置见 `vite.config.ts`）： | 插件 | 说明 | | -------------------------- | ---------------------------------------------------------------------------------- | | `@vitejs/plugin-react` | 官方 React 插件，支持 Fast Refresh 与 JSX 转换 | | `vite-plugin-mock` | 开发环境下启用本地 Mock 接口，配置路径 `mock/` | | `vite-plugin-version-file` | 自定义插件（`plugin/vite-plugin-version-file.ts`），打包时生成 `dist/version.json` | | `rollup-plugin-visualizer` | 构建产物体积分析，仅在 `pnpm analyze` 时生成 `dist/stats.html` | ## ESLint 与 Prettier 代码规范配置如下： | 工具 / 插件 | 说明 | | ----------------------------- | -------------------------------- | | `@eslint/js` | ESLint 官方推荐规则 | | `typescript-eslint` | TypeScript 规则 | | `eslint-plugin-react-hooks` | React Hooks 规则 | | `eslint-plugin-react-refresh` | React Refresh 规则 | | `eslint-plugin-prettier` | 将 Prettier 作为 ESLint 规则运行 | | `eslint-config-prettier` | 关闭与 Prettier 冲突的规则 | | `prettier` | 代码格式化，配置见 `.prettierrc` | Prettier 主要配置： - `semi: false`：语句末尾不加分号 - `singleQuote: true`：使用单引号 - `tabWidth: 2`：缩进 2 个空格 - `trailingComma: "es5"`：ES5 有效位置添加尾随逗号 - `printWidth: 100`：每行最大 100 字符 - `endOfLine: "lf"`：换行符为 LF ## 目录结构 ``` react-vite-ts-tem/ ├── mock/ # Mock 数据 ├── plugin/ # 自定义 Vite 插件 ├── public/ # 静态资源（不经过构建） ├── src/ │ ├── api/ # API 请求 │ ├── assets/ # 图片、图标等资源 │ ├── components/ # 公共组件 │ ├── constants/ # 常量 │ ├── hooks/ # 自定义 Hooks │ ├── layouts/ # 布局组件 │ │ ├── index.tsx # 布局入口（动态切换 4 种布局） │ │ ├── verticalLayout.tsx │ │ ├── horizontalLayout.tsx │ │ ├── verticalDoubleLayout.tsx │ │ └── mixedLayout.tsx │ ├── pages/ # 页面 │ ├── router/ # 路由配置、守卫、动态路由 │ ├── store/ # Zustand 状态管理 │ ├── types/ # 全局类型 │ ├── utils/ # 工具函数 │ ├── App.tsx # 根组件 │ ├── main.tsx # 入口文件 │ └── index.css # 全局样式 ├── .env # 默认环境变量 ├── .env.development # 开发环境变量 ├── .env.production # 生产环境变量 ├── .env.test # 测试环境变量 ├── .env.example # 环境变量模板 ├── eslint.config.js # ESLint 配置 ├── .prettierrc # Prettier 配置 ├── tsconfig.json # TypeScript 项目引用配置 ├── tsconfig.app.json # 应用 TypeScript 配置 ├── tsconfig.node.json # Node 端 TypeScript 配置 └── vite.config.ts # Vite 配置 ``` ## 环境要求 - Node.js >= 20 - pnpm >= 9（项目已锁定 `packageManager` 为 `pnpm@11.5.1`） ## 安装依赖 ```bash pnpm install ``` ## 项目环境与运行模式 项目支持三种运行模式，分别对应不同的环境变量文件： | 模式 | 环境变量文件 | 说明 | | ----------- | ------------------ | -------------------------------------- | | development | `.env.development` | 本地开发模式，默认启用 Mock 或代理转发 | | test | `.env.test` | 测试环境构建/预览 | | production | `.env.production` | 生产环境构建 | Vite 会自动根据 `--mode` 加载对应的环境变量文件。所有客户端可访问的变量必须以 `VITE_` 开头。 ## 可用脚本 | 脚本 | 命令 | 说明 | | ------------------- | ------------------------------------- | -------------------------------------------------------------- | | `pnpm dev` | `vite` | 启动开发服务器（development 模式），默认 http://localhost:5173 | | `pnpm dev:test` | `vite --mode test` | 以 test 模式启动开发服务器 | | `pnpm build` | `tsc -b && vite build` | 类型检查并构建生产版本 | | `pnpm build:test` | `tsc -b && vite build --mode test` | 构建测试环境版本 | | `pnpm preview` | `vite preview` | 本地预览生产构建 | | `pnpm preview:test` | `vite preview --mode test` | 本地预览测试构建 | | `pnpm analyze` | `tsc -b && vite build --mode analyze` | 构建并生成体积分析报告 `dist/stats.html` | | `pnpm lint` | `eslint .` | 运行 ESLint 检查 | | `pnpm lint:fix` | `eslint . --fix` | 自动修复 ESLint 可修复问题 | | `pnpm format` | `prettier --write .` | 使用 Prettier 格式化代码 | | `pnpm format:check` | `prettier --check .` | 检查 Prettier 格式 | ## 开发服务器 ### 启动开发服务器 ```bash pnpm dev ``` 默认访问地址：http://localhost:5173 - 若 `VITE_ENABLE_MOCK=true`，请求会由 `vite-plugin-mock` 拦截并返回本地 Mock 数据。 - 若 `VITE_ENABLE_MOCK=false`，请求会通过 Vite 代理转发到 `VITE_API_BASE_URL` 对应的后端服务。 ### 构建生产版本 ```bash pnpm build ``` 构建产物输出到 `dist/` 目录，资源按类型分目录存放： ``` dist/ ├── index.html ├── version.json # 版本信息 ├── favicon.svg # public 静态资源 ├── icons.svg # public 静态资源 ├── js/ # JS 入口与 chunk ├── css/ # CSS 文件 ├── images/ # 图片资源 ├── fonts/ # 字体资源（如有） └── media/ # 音视频资源（如有） ``` ### 构建体积分析 ```bash pnpm analyze ``` 构建完成后打开 `dist/stats.html` 即可查看各 chunk 体积分布。 ### 本地预览生产构建 ```bash pnpm preview ``` ## 环境变量 复制 `.env.example` 为对应环境的配置文件： ```bash cp .env.example .env cp .env.example .env.development cp .env.example .env.production ``` 示例变量： | 变量名 | 说明 | 示例 | | ------------------- | ------------- | ------------------------- | | `VITE_APP_TITLE` | 应用标题 | React Vite TS Template | | `VITE_APP_ENV` | 当前环境 | development | | `VITE_API_BASE_URL` | API 基础地址 | http://localhost:3000/api | | `VITE_ENABLE_MOCK` | 是否开启 Mock | true | 在代码中使用： ```ts const apiUrl = import.meta.env.VITE_API_BASE_URL ``` ## 路径别名 项目已配置 `@/` 指向 `src/` 目录，推荐优先使用别名导入模块： ```tsx import { useUserStore } from '@/store' import { formatDate } from '@/utils' ``` 配置位于 `vite.config.ts`： ```ts resolve: { alias: { '@': path.resolve(__dirname, './src'), }, } ``` ## 状态管理 项目使用 Zustand 进行全局状态管理，示例 Store 位于 `src/store/useCounterStore.ts`： ```ts import { useCounterStore } from '@/store' function App() { const { count, increase, decrease, reset } = useCounterStore() // ... } ``` ## 代码规范 - 使用 ESLint 10 进行语法与风格检查 - 使用 Prettier 3 进行代码格式化 - 提交前建议运行： ```bash pnpm lint pnpm format:check ``` ## 许可证 [MIT](./LICENSE)