第 1 章：项目初始化与技术选型

本章学习目标理解为什么选择 React 19 TypeScript Vite 技术栈从零搭建一个企业级前端项目脚手架掌握目录结构设计的思路学会配置 ESLint、Prettier 和路径别名了解多环境配置方案接入 Ant Design 组件库1.1 为什么选这套技术栈在开始写代码之前我们先聊聊技术选型的思考。React 19React 19 带来了很多新特性对后台系统开发特别友好useOptimistic乐观更新提升操作反馈体验useActionState表单处理更简洁ref 作为 prop不再需要 forwardRef 包裹Server Components复杂场景下的性能优化手段TypeScript后台系统的核心痛点是数据模型复杂、字段多、状态流转繁琐。TypeScript 能在编译期就发现大量 Bug是企业级项目的必选项。Vite相比 WebpackVite 的开发体验提升明显冷启动快基于 ESM不需要打包整个项目HMR 快模块级热更新改完代码秒级刷新配置简单开箱即用插件生态成熟Ant Design 5.x企业级后台最常用的组件库没有之一组件丰富表格、表单、弹窗、树…应有尽有设计规范统一主题定制方便CSS-in-JSTypeScript 支持好1.2 从零搭建项目脚手架1.2.1 初始化 Vite 项目npmcreate vitelatest admin-hub ----templatereact-tscdadmin-hubnpminstall1.2.2 安装基础依赖# 路由npminstallreact-router-dom# HTTP 请求npminstallaxios# UI 组件库npminstallantd ant-design/icons# 图表npminstallecharts echarts-for-react# 工具库npminstalldayjs lodash-es# 开发依赖 - 代码规范npminstall-Deslint prettier eslint-config-prettier eslint-plugin-prettiernpminstall-Dtypescript-eslint/parser typescript-eslint/eslint-pluginnpminstall-Deslint-plugin-react-hooks eslint-plugin-react-refresh1.3 目录结构设计一个清晰的目录结构是项目可维护的基础。推荐以下分层src/ ├── assets/# 静态资源图片、字体等├── components/# 通用组件可跨页面复用│ ├── StatCard/# 统计卡片│ ├── TimeLine/# 时间线│ └── Empty/# 空状态├── hooks/# 自定义 Hooks跨页面复用的逻辑│ ├── usePagination.ts# 分页逻辑│ ├── useDebounce.ts# 防抖│ └── useTable.ts# 表格通用逻辑├── layouts/# 布局组件│ ├── BasicLayout/# 基础布局侧边栏 顶栏 内容│ └── BlankLayout/# 空白布局登录页等├── pages/# 页面层按业务模块划分│ ├── workbench/# 工作台│ ├── ticket/# 任务单管理│ ├── approval/# 审批管理│ ├── scheduled-task/# 定时任务│ ├── ai-assistant/# AI 助手│ ├── knowledge/# 知识中心│ └── statistics/# 数据统计├── services/# 服务层API 调用│ ├── request.ts# axios 实例与拦截器│ ├── ticket.ts# 任务单相关接口│ └──... ├── store/# 状态管理│ ├── createStore.ts# 轻量 Store 工厂函数│ ├── useUserStore.ts# 用户信息全局│ └── useTicketStore.ts# 任务单页面级├── types/# 类型定义│ ├── api.ts# 通用接口类型│ ├── ticket.ts# 任务单类型│ └──... ├── utils/# 工具函数│ ├── format.ts# 格式化工具│ ├── storage.ts# 本地存储封装│ └── validate.ts# 校验规则├── router/# 路由配置│ ├── index.tsx# 路由入口│ └── routes.ts# 路由表定义├── App.tsx# 根组件└── main.tsx# 入口文件为什么这样分目录职责特点pages/页面容器组合组件与业务逻辑按业务模块分每个模块一个文件夹components/纯 UI 组件不包含业务逻辑可在任何页面复用hooks/逻辑复用单元抽离状态逻辑组件只负责渲染services/数据获取层统一管理 API便于 mock 和切换store/状态管理全局状态放这里页面级状态尽量用 useStatetypes/类型定义业务类型集中管理避免循环引用1.4 配置 ESLint Prettier 路径别名1.4.1 ESLint 配置在项目根目录创建.eslintrc.cjsmodule.exports{root:true,env:{browser:true,es2021:true,node:true},extends:[eslint:recommended,plugin:typescript-eslint/recommended,plugin:react-hooks/recommended,plugin:prettier/recommended,],ignorePatterns:[dist,.eslintrc.cjs],parser:typescript-eslint/parser,parserOptions:{ecmaVersion:latest,sourceType:module,ecmaFeatures:{jsx:true},},settings:{react:{version:detect}},plugins:[react-refresh],rules:{react-refresh/only-export-components:[warn,{allowConstantExport:true},],typescript-eslint/no-unused-vars:[warn,{argsIgnorePattern:^_}],typescript-eslint/no-explicit-any:warn,},};1.4.2 Prettier 配置创建.prettierrc{semi:true,singleQuote:true,trailingComma:all,printWidth:100,tabWidth:2,arrowParens:always}1.4.3 路径别名Vite 配置vite.config.tsimport{defineConfig}fromvite;importreactfromvitejs/plugin-react;importpathfrompath;exportdefaultdefineConfig({plugins:[react()],resolve:{alias:{:path.resolve(__dirname,src),components:path.resolve(__dirname,src/components),hooks:path.resolve(__dirname,src/hooks),services:path.resolve(__dirname,src/services),store:path.resolve(__dirname,src/store),utils:path.resolve(__dirname,src/utils),pages:path.resolve(__dirname,src/pages),types:path.resolve(__dirname,src/types),},},});同步配置tsconfig.json的compilerOptions{compilerOptions:{baseUrl:.,paths:{/*:[src/*],components/*:[src/components/*],hooks/*:[src/hooks/*],services/*:[src/services/*],store/*:[src/store/*],utils/*:[src/utils/*],pages/*:[src/pages/*],types/*:[src/types/*]}}}1.5 环境变量与多环境配置后台系统通常有三个环境开发、测试、生产。1.5.1 环境变量文件在项目根目录创建# .env.development —— 开发环境 VITE_API_BASE_URL/api VITE_APP_TITLEAdminHub (开发环境)# .env.staging —— 测试环境 VITE_API_BASE_URLhttps://staging-api.example.com VITE_APP_TITLEAdminHub (测试环境)# .env.production —— 生产环境 VITE_API_BASE_URLhttps://api.example.com VITE_APP_TITLEAdminHub1.5.2 类型声明在src/vite-env.d.ts中补充类型/// reference typesvite/client /interfaceImportMetaEnv{readonlyVITE_API_BASE_URL:string;readonlyVITE_APP_TITLE:string;}interfaceImportMeta{readonlyenv:ImportMetaEnv;}1.5.3 package.json 脚本{scripts:{dev:vite,build:staging:tsc vite build --mode staging,build:prod:tsc vite build --mode production,preview:vite preview,lint:eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0}}1.6 接入 Ant Design 组件库1.6.1 基础配置在App.tsx中配置全局主题import { ConfigProvider, App as AntdApp } from antd; import zhCN from antd/locale/zh_CN; import dayjs/locale/zh-cn; import { RouterProvider } from react-router-dom; import router from ./router; const theme { token: { colorPrimary: #1677ff, borderRadius: 6, fontFamily: PingFang SC, Microsoft YaHei, sans-serif, }, }; function App() { return ( ConfigProvider locale{zhCN} theme{theme} AntdApp RouterProvider router{router} / /AntdApp /ConfigProvider ); } export default App;为什么用 AntdAppAnt Design 5.x 推荐用App组件来获取全局的message、modal、notification实例不需要再手动 import 和处理 Context。1.6.2 按需加载Ant Design 5.x 默认支持 Tree Shaking不需要额外配置按需加载插件。直接import { Button } from antd即可。1.7 第一个页面Hello AdminHub在src/pages/demo/Hello.tsx写一个简单的验证页面import { Button, Card, Space, Typography } from antd; import { SmileOutlined } from ant-design/icons; const { Title, Paragraph } Typography; export default function Hello() { return ( div style{{ padding: 24 }} Card Space directionvertical sizemiddle style{{ width: 100% }} Title level{2} SmileOutlined style{{ marginRight: 8 }} / 欢迎使用 AdminHub /Title Paragraph typesecondary 这是你的第一个后台页面。接下来我们会一步步构建完整的管理系统。 /Paragraph Button typeprimary开始学习/Button /Space /Card /div ); }运行npm run dev看到页面说明项目搭建成功。本章小结知识点关键内容技术选型React 19 TypeScript Vite Ant Design 5.x目录结构按职责分层pages / components / hooks / services / store / utils代码规范ESLint 检查代码质量Prettier 统一格式路径别名Vite TSConfig 双配置使用/替代深层相对路径多环境.env.*文件 --mode参数三环境隔离UI 框架Ant Design 5.x通过 ConfigProvider 配置主题和语言下一章预告我们会深入架构设计实现一套轻量级状态管理方案并完成 axios 的统一封装和路由体系搭建。