★ FEATURED ARTICLE 前两天有个朋友发消息问我“前端项目里那个‘rea’到底怎么搭才不踩坑”我愣了一下问他是不是指 React 项目的缩写他说对就是那个团队内部代号叫rea的跨端中后台项目。聊了一圈我才发现很多人对这个名字既熟悉又陌生——熟悉是因为天天见陌生是因为真要从零手写一个生产级rea项目时常常遇到初始化混乱、路由鉴权设计不清晰、状态一多就难以维护这类问题。这篇文章我就借这个机会把我在实际开发中反复打磨出来的一套rea项目落地经验完整写出来。从项目设计思路、目录规范、路由与状态管理到性能优化、常见坑位排查全部基于真实生产环境。不管你是刚接手rea项目的新手还是想把手头项目重构得更清爽的老手都能从中抄到现成的方案。所有示例代码基于主流前端技术栈React 18 Vite React Router v6 Zustand细节处我会解释为什么这么做而不是单纯丢一堆配置让你自己猜。1. 项目定位与前期思考1.1 为什么选择 React 技术栈构建rearea作为一个前端项目代号本质上代表一类单页应用SPA系统。我经历过从 jQuery 时代到 Vue、React 双雄争霸的完整周期最终在rea这类中后台管理系统上坚定选择 React核心原因有三个。第一是组件化模型足够纯粹。React 的“UI f(state)”心智模型在复杂业务场景下特别占优势尤其是中后台项目里大量的表单、表格、弹窗组合用纯函数组件加 Hook 组织起来非常自然。组件之间数据流单向清晰调试时顺着组件树往上找状态来源就行不会出现 Vue 中 v-model 跨层级修改这种隐含耦合。第二是生态的稳定性和可替换性。React 本身只是一个视图层库路由、状态管理、请求库、样式方案都可以自由搭配。rea这种长期维护的项目最怕的就是框架层面的 breaking change 导致大范围重写React 的保守演进策略在这方面的优势是明显的。第三是跨端复用的潜力。团队内部讨论过后面可能要出移动端或者桌面端版本React Native 和 TauriWebView 方案都能复用大部分rea的组件逻辑和状态层。这种“一次编写多处适配”的灵活性在立项阶段就值得放进选型考量。当然选型不是无脑吹 React。如果你们团队全员 Vue 熟练或者项目本身是重表单校验的简单 CRUD用 Vue 也完全没问题。选型的关键在于团队熟悉度、项目长期演进方向、生态匹配度这三点上取得平衡而不是纯技术层面的优劣之争。1.2 从零初始化的脚手架选型rea项目我首推 Vite 而不是 Webpack——别急着反驳听我说完。Vite 在开发服务器启动速度上的优势是肉眼可见的中后台项目动辄几百个组件模块Webpack 冷启动要 30 到 60 秒Vite 用 esbuild 预构建依赖后基本在 3 秒内完成。这个差距对日常开发体验的影响是质的。生产构建方面Vite 走 Rollup 打包产物体积和分包策略比 Webpack 默认配置要好控一些。不过有一点要注意Vite 对 CommonJS 依赖的兼容处理是通过 optimizeDeps 来预打包的遇到某些老旧的 npm 包可能需要在vite.config.ts里手动加optimizeDeps.include或exclude。这个属于正常情况踩过一两次就熟悉了。创建项目的命令是这样的# 使用官方 create-vite 脚手架指定 React TypeScript 模板 npm create vitelatest rea -- --template react-ts很多人会问为什么不直接用 Next.js 或者 UmiJS 这种重型框架答案很简单——rea是一个纯前端中后台应用没有 SSR服务端渲染需求也不需要约定式路由等强框架约束。用 Vite React Router 这种轻量组合目录结构、路由定义、数据获取方式都能完全掌控不会在排查问题时多出一个框架黑盒层。初始化完成后的第一件事不是写代码而是检查.gitignore是否需要补内容然后提交一次干净的 initial commit。这个习惯能保证后续任何改动都有清晰的 diff 历史可追踪。1.3 版本选定的一个关键原则“先用着出了问题再升级”这个原则在rea项目里绝对是大忌。React 18 的并发特性、Router v6 的完整重写、状态库的破坏性升级每一层都可能牵连业务代码大改。我的锁定策略是rea项目维护一个统一的dependencies版本清单所有依赖在package.json中用精确版本号不带^或~防止队友 npm install 后拉到带有破坏性变化的小版本。如果确实需要升级单独开一个分支做升级验证跑完所有测试用例和 E2E 冒烟测试后再合入主干。这个流程看起来笨重但能避免那种“明明没改代码怎么线上炸了”的诡异问题。package.json核心依赖版本示例{ react: 18.2.0, react-dom: 18.2.0, react-router-dom: 6.22.3, zustand: 4.5.2, axios: 1.7.2, typescript: 5.4.5, vite: 5.2.11 }2. 目录结构与工程规范2.1 按功能域而非按文件类型划分目录rea项目的目录我强烈建议按“功能域”划分而不是按“文件类型”划分。什么意思很多人习惯这么建目录components/、pages/、utils/、hooks/、services/全平铺结果项目一大光components/下面就有几百个文件找起来怀疑人生。按功能域划分时每个业务模块自成一个文件夹模块内部的组件、状态、请求、类型定义都放在一起rea/ ├── src/ │ ├── app/ # 应用级配置路由表、全局样式、入口文件 │ ├── modules/ │ │ ├── dashboard/ # 仪表盘模块 │ │ │ ├── components/ # 模块私有组件 │ │ │ ├── hooks/ # 模块私有 hooks │ │ │ ├── services/ # 模块接口定义 │ │ │ ├── stores/ # 模块状态仓库 │ │ │ ├── types/ # 模块类型定义 │ │ │ └── index.tsx # 模块入口页面 │ │ ├── user/ │ │ └── order/ │ ├── shared/ # 跨模块通用代码 │ │ ├── components/ # 通用 UI 组件 │ │ ├── hooks/ # 通用自定义 hooks │ │ ├── utils/ # 工具函数 │ │ └── constants/ # 常量定义 │ └── main.tsx这样的好处很直接接手订单模块时只需要进入modules/order/就能看到这个模块的全貌不需要在几十个目录间反复跳转。模块内部是自律的——你可以随意调整私有组件结构只要不污染模块外部接口。模块间的通信通过共享状态或应用级事件进行避免跨模块深层引用。2.2 别名配置与导入顺序规范rea项目的路径别名是舒适度的关键。没有别名时跨目录导入写出来是../../../shared/components/Button这种代码让人看着就头皮发麻。配置完别名后同样的导入变成/shared/components/Button清爽不少。Vite 配置别名// vite.config.ts import { defineConfig } from vite import react from vitejs/plugin-react import path from path export default defineConfig({ plugins: [react()], resolve: { alias: { : path.resolve(__dirname, ./src) } } })TypeScript 这边也要同步配置否则编辑器会报红{ compilerOptions: { baseUrl: ., paths: { /*: [src/*] } } }导入顺序规范上我约定了一套固定排序外部依赖react、react-router-dom 等在最前接着是/shared/下的通用代码然后是/modules/下的跨模块引用最后是相对路径的模块内导入。每类之间空一行。这套规则用 ESLint 的import/order插件自动强制人肉去记去排肯定不可靠。2.3 TypeScript 的严格模式是底线rea项目从头到尾都要开启 TypeScript 的 strict 模式。这一步省不了中后台业务里undefined和null的边界场景太多了。一个接口返回字段的缺失、一个数组索引的越界运行时才发现问题是最痛苦的。TypeScript 能帮你把这些错误拦截在编译期。tsconfig.json关键配置{ compilerOptions: { target: ES2020, lib: [ES2020, DOM, DOM.Iterable], module: ESNext, moduleResolution: bundler, strict: true, noUnusedLocals: true, noUnusedParameters: true, noFallthroughCasesInSwitch: true, skipLibCheck: true } }noUnusedLocals和noUnusedParameters这两个选项我建议也打开。它们会强制你清理未使用的变量和参数表面上看起来有点啰嗦实际对代码卫生帮助很大——很多死代码就是因为变量从未被使用而悄悄残留在项目里的。2.4 ESLint 与 Prettier 的配合我见过不少项目 ESLint 和 Prettier 打架的情况ESLint 管单引号双引号、Prettier 也管两边配置冲突导致保存文件时反复横跳。正确做法是Prettier 只管格式缩进、换行、分号、引号ESLint 只管代码质量规则未使用变量、隐式 any、hook 依赖不完整两者范围区隔开。在配置里明确告诉 ESLint 去掉格式类规则交给 Prettier// .eslintrc.cjs module.exports { root: true, extends: [ eslint:recommended, plugin:react/recommended, plugin:react-hooks/recommended, plugin:typescript-eslint/recommended, prettier // 必须在最后关闭格式类冲突规则 ], rules: { react/react-in-jsx-scope: off // React 17 JSX 转换后不需要显式 import React } }prettier这个扩展放在 extends 最后面它的作用就是“关掉所有可能与 Prettier 冲突的格式规则”让 ESLint 专心做代码质量检查。这样保存文件时Prettier 负责格式统一ESLint 负责揪出逻辑隐患两者各司其职。3. 路由与权限体系的完整设计3.1 路由表的数据驱动设计rea这样的中后台项目路由设计不能直接在 JSX 里写死一堆Route嵌套那样路由和导航菜单会松散耦合每次加一个页面要同步改两三处地方。更合理的方案是定义一份统一的路由配置数据由这份数据同时生成路由表和侧边栏菜单。// src/app/router/routes.tsx import { lazy } from react import type { ReactNode } from react import { DashboardOutlined, UserOutlined, FileTextOutlined } from ant-design/icons export interface AppRoute { path: string name: string icon?: ReactNode component?: ReactNode children?: AppRoute[] meta?: { title?: string requiresAuth?: boolean roles?: string[] } } export const appRoutes: AppRoute[] [ { path: /dashboard, name: 工作台, icon: DashboardOutlined /, component: lazy(() import(/modules/dashboard)), meta: { title: 工作台, requiresAuth: true } }, { path: /user, name: 用户管理, icon: UserOutlined /, meta: { requiresAuth: true, roles: [admin] }, children: [ { path: /user/list, name: 用户列表, component: lazy(() import(/modules/user/list)), meta: { title: 用户列表, requiresAuth: true } }, { path: /user/detail, name: 用户详情, component: lazy(() import(/modules/user/detail)), meta: { title: 用户详情, requiresAuth: true } } ] }, { path: /report, name: 报表中心, icon: FileTextOutlined /, component: lazy(() import(/modules/report)), meta: { title: 报表中心, requiresAuth: true, roles: [admin, analyst] } } ]这份路由配置用lazy()包装组件天然实现了代码分割每个模块的 JS 只会被加载到浏览器用 icon 字段驱动侧边栏菜单渲染路由表即菜单数据源增删页面只改一处。3.2 路由权限拦截的两种实现层面权限控制分两层第一层是路由层决定“你能不能进入这个页面”第二层是按钮/操作层决定“你进了页面能不能执行某操作”。路由层权限推荐用包装组件实现而不是在路由渲染里写逻辑判断。我定义了一个AuthGuard组件包裹需要鉴权的路由元素// src/app/components/AuthGuard.tsx import { Navigate, Outlet, useLocation } from react-router-dom import { useAuthStore } from /modules/auth/stores/useAuthStore export function AuthGuard() { const token useAuthStore((state) state.token) const userInfo useAuthStore((state) state.userInfo) const location useLocation() if (!token || !userInfo) { // 未登录跳转登录页并携带来源路径登录成功后可以回跳 return Navigate to/login replace state{{ from: location.pathname }} / } return Outlet / }在路由表的顶层配置中用AuthGuard包裹所有需要鉴权的子路由// src/app/router/index.tsx import { createBrowserRouter, Navigate } from react-router-dom import { AuthGuard } from /app/components/AuthGuard import { Layout } from /app/components/Layout export const router createBrowserRouter([ { path: /login, element: lazy(() import(/modules/auth/login)) }, { element: AuthGuard /, children: [ { element: Layout /, children: [ { path: /dashboard, element: ... }, { path: /user, element: ... }, { path: /report, element: ... } ] } ] }, { path: /, element: Navigate to/dashboard replace / }, { path: *, element: NotFound / } ])按钮层权限则通过一个自定义 Hook 实现。后端在登录时返回当前用户的角色和权限点数组前端把这些权限点存进useAuthStore需要通过权限控制的按钮统一调用// src/shared/hooks/usePermission.ts import { useAuthStore } from /modules/auth/stores/useAuthStore export function usePermission() { const permissions useAuthStore((state) state.permissions) const checkPermission (code: string) { return permissions.includes(code) } return { checkPermission } }使用时只需一行const { checkPermission } usePermission() if (!checkPermission(user:delete)) { return null // 或者禁用按钮 }3.3 动态路由的取舍动态路由根据用户权限动态注册路由表听起来很灵活但实现起来要考虑的点很多刷新后如何恢复路由表、动态生成的菜单如何与路由表同步、代码分割的 chunk 加载如何处理等等。rea项目中我做了一个折中方案路由静态注册菜单动态过滤。也就是说所有页面的路由在应用初始化时就注册但侧边栏菜单会按当前用户的角色过滤。这样用户虽然不能直接访问无权限页面的 URL路由层有角色校验但不会出现“刷新页面后菜单恢复但路由未注册导致白屏”的问题。后端返回的角色列表变化时只需重新拉取用户信息即可刷新菜单。如果项目角色权限体系特别复杂页面按角色动态生成那么动态路由也值得做但要先做好刷新恢复方案。通常是把后端返回的路由配置结构化存储刷新时先从本地缓存读取再异步拉取最新配置合并。这个复杂度是上线成本换来的按需评估。4. 状态管理与数据请求层的落地4.1 为什么选 Zustand 而不是 Reduxrea项目的全局状态用 Zustand这是一个被很多人忽略但其实很能打的轻量方案。Redux Toolkit 当然也不错但它的样板代码仍然偏多createSlice、configureStore、Provider 包裹、connect 或 useSelector 的导入……对中后台项目中“登录用户信息”“全局配置”“通知列表”这种低频更新的全局数据Redux 的重型架构性价比不高。Zustand 的核心心智是一个 Hook 就是一个 store不需要 Provider 包裹没有 context 的性能损耗。定义 store 的代码大概是这样的// src/modules/auth/stores/useAuthStore.ts import { create } from zustand import { persist } from zustand/middleware interface AuthState { token: string | null userInfo: UserInfo | null permissions: string[] setAuth: (payload: { token: string; userInfo: UserInfo; permissions: string[] }) void clearAuth: () void } export const useAuthStore createAuthState()( persist( (set) ({ token: null, userInfo: null, permissions: [], setAuth: ({ token, userInfo, permissions }) set({ token, userInfo, permissions }), clearAuth: () set({ token: null, userInfo: null, permissions: [] }) }), { name: rea-auth-storage } ) )加一个persist中间件token 和用户信息自动存到 localStorage刷新页面后状态自动恢复省去了手写同步逻辑的繁琐。Zustand 的订阅粒度也很细。在组件里只用选择器选择一个字段const token useAuthStore((state) state.token)只有token变化时才会触发当前组件重渲染其他字段的更新不会造成性能浪费。4.2 请求层的二次封装要领rea项目中的 Axios 实例一定是统一封装的不能每个模块自己裸调 axios。理由很直接统一处理 token 注入、超时设置、错误提示、HTTP 状态码与业务码的区分这套逻辑写在每个请求里既冗余又容易漏。基础封装如下// src/shared/utils/http.ts import axios from axios import { message } from antd import { useAuthStore } from /modules/auth/stores/useAuthStore const http axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, timeout: 15000 }) // 请求拦截器自动携带 token http.interceptors.request.use((config) { const token useAuthStore.getState().token if (token) { config.headers.Authorization Bearer ${token} } return config }) // 响应拦截器统一处理错误 http.interceptors.response.use( (response) { const res response.data // 约定后端返回 { code, data, message } if (res.code ! 0) { message.error(res.message || 请求失败) return Promise.reject(new Error(res.message)) } return res.data }, (error) { if (error.response?.status 401) { // 登录过期清掉本地状态并跳转登录页 useAuthStore.getState().clearAuth() window.location.href /login } else { message.error(error.message || 网络错误) } return Promise.reject(error) } ) export default http这里关键点是useAuthStore.getState()可以在 React 组件之外拿到 store 的当前状态这是 Zustand 相比 Redux 的一个实际优势——在拦截器、工具函数、普通模块中都能无感访问状态不需要额外的 store 实例引用。各模块请求接口时的写法建议用 TypeScript 强约束入参和出参// src/modules/user/services/fetchUserList.ts import http from /shared/utils/http interface FetchUserListParams { page: number pageSize: number keyword?: string } interface UserItem { id: string name: string email: string } export function fetchUserList(params: FetchUserListParams) { return http.getFetchUserListParams, UserItem[](/user/list, { params }) }4.3 服务器状态与客户端状态的界线rea项目里最容易烂掉的状态管理是把服务器数据一股脑塞进全局 store。用户列表数据、订单详情数据、报表数据——这些都属于“服务器状态”它们从接口来应该由请求函数负责获取并由组件或数据层缓存管理而不是放在全局 store 里由业务逻辑到处修改。我划的界线很简单全局 store 只放“客户端状态”——登录信息、主题配置、语言偏好、权限点这类前端自己生成和控制的数据。服务器返回的数据让它在组件内部通过请求函数获取并用useRequest之类的自定义 Hook 统一管理loading、error、data三个状态。// src/shared/hooks/useRequest.ts import { useCallback, useEffect, useRef, useState } from react export function useRequestT( fetcher: () PromiseT, options?: { manual?: boolean; onSuccess?: (data: T) void } ) { const [data, setData] useStateT | null(null) const [loading, setLoading] useState(false) const [error, setError] useStateError | null(null) const run useCallback(async () { setLoading(true) setError(null) try { const res await fetcher() setData(res) options?.onSuccess?.(res) return res } catch (err) { setError(err as Error) throw err } finally { setLoading(false) } }, [fetcher]) useEffect(() { if (!options?.manual) { run() } }, [run]) return { data, loading, error, run } }这样组件里就是纯粹的数据消费者不关心请求细节。列表页的请求逻辑、加载状态、失败重试都有了统一模板。5. 核心页面与组件设计实操5.1 一个典型列表页的状态管理模板rea项目里最多的页面就是列表页搜索条件、表格数据、分页、loading、选中行。这些页面的逻辑高度相似我总结了一个通用模板能避免每次从零开始写。组件内维护的 state 包括搜索表单字段、页码与每页条数、表格数据与 loading。注意这里搜索表单字段与表格查询参数不是一回事搜索表单只是用户填写的输入值点击“查询”后才同步到查询参数并触发请求。如果表单值和请求参数直接绑定用户的泛输入就会触发不必要请求既浪费性能又拖慢交互。// src/modules/user/index.tsx import { useCallback, useState } from react import { Table, Button, Form, Input, Space } from antd import { useRequest } from /shared/hooks/useRequest import { fetchUserList } from /modules/user/services/fetchUserList import type { UserItem } from /modules/user/types export default function UserListPage() { const [form] Form.useForm() const [queryParams, setQueryParams] useState{ page: number; pageSize: number; keyword?: string }({ page: 1, pageSize: 10 }) // 只有当 queryParams 变化时才重新请求 const { data, loading } useRequest( useCallback(() fetchUserList(queryParams), [queryParams]) ) const handleSearch () { const values form.getFieldsValue() setQueryParams((prev) ({ ...prev, page: 1, ...values })) } const handleTableChange (pagination: any) { setQueryParams((prev) ({ ...prev, page: pagination.current, pageSize: pagination.pageSize })) } return ( div Form form{form} layoutinline Form.Item namekeyword Input placeholder搜索用户名/邮箱 allowClear / /Form.Item Button typeprimary onClick{handleSearch}查询/Button Button onClick{() form.resetFields()}重置/Button /Form Table rowKeyid loading{loading} dataSource{data?.list ?? []} pagination{{ current: queryParams.page, pageSize: queryParams.pageSize, total: data?.total ?? 0 }} onChange{handleTableChange} / /div ) }这套结构里最核心的思路是queryParams是触发请求的唯一依据搜索按钮通过更新queryParams来间接触发请求表格翻页同理。这样请求时序永远可控不会出现表单未填完就发请求、翻页后搜索条件丢失等经典问题。5.2 弹窗表单的受控与非受控选型中后台项目的弹窗表单通常有两种模式新增弹窗和编辑弹窗。新增弹窗拿空表单编辑弹窗需要回填数据。常见做法是弹窗组件内放一个Form父组件通过open控制显示、通过initialValues传入回填数据。但这里有个容易踩的坑Form实例的initialValues只在表单挂载时生效一次如果同一个弹窗先编辑 A 再打开编辑 B表单里的数据可能还是 A 的旧值。解决办法是弹窗的destroyOnClose或forceRender的配合确保关闭时销毁表单重新打开会重新挂载并读取新的initialValues。或者更稳妥的做法是每次打开弹窗时手动调用form.setFieldsValue()做回填而不是依赖initialValues。更推荐的方式是用 React 的 key 强制重置组件Modal open{open} onOk{handleOk} onCancel{handleClose} EditForm key{currentRecord?.id ?? new} initialValues{currentRecord} / /ModalcurrentRecord变化时key变化导致EditForm组件重建表单状态完全重置。这个技巧在复杂情况下比清理表单字段可靠得多。在用Form的initialValues时我建议每次回填都写成这样useEffect(() { if (open currentRecord) { form.setFieldsValue(currentRecord) } }, [open, currentRecord, form])initialValues是“只有在首次渲染才生效”的静态值而setFieldsValue是动态的、每次都能生效。对于编辑场景动态设置更可靠。5.3 复杂筛选条件的防抖与缓存搜索框的“边输入边筛选”在中后台页面也越来越常见。实时搜索的前提是接口足够快、筛选逻辑简单但大多数rea场景的搜索条件会包含文本、日期区间、下拉多选等组合。此时不防抖每敲一个字符都发请求后端直接被查爆。自定义防抖 HooK 可以复用// src/shared/hooks/useDebounce.ts import { useEffect, useState } from react export function useDebounceT(value: T, delay 300) { const [debounced, setDebounced] useState(value) useEffect(() { const timer setTimeout(() setDebounced(value), delay) return () clearTimeout(timer) }, [value, delay]) return debounced }在搜索页面里const [searchText, setSearchText] useState() const debouncedSearchText useDebounce(searchText, 400) useEffect(() { // 只在防抖后的文本变化时更新查询参数 setQueryParams((prev) ({ ...prev, keyword: debouncedSearchText })) }, [debouncedSearchText])防抖时间建议设置在 300 到 500ms 之间。太短100ms用户还没输完下一位数字就触发请求效果不明显太长800ms 以上会显得界面反应迟钝。400ms 是体验和性能之间比较均衡的取值。5.4 表格大数据量的虚拟滚动方案列表数据一旦破万直接渲染全部 DOM 必然卡顿。rea场景中有两类做法分页渲染和虚拟滚动。分页是王道。只要后端支持分页表格就应该使用服务端分页模式每次只加载一页通常 10 到 20 条。这是最简单有效的方案但要注意用户勾选了第一页的若干行后翻到第二页再回到第一页勾选状态是否保留这需要用rowSelection的preserveSelectedRowKeys属性来处理。如果业务确实要求一次性加载所有数据且支持前端分页那么表格组件需要切换到底层虚拟列表方案。rea项目用的是rc-virtual-list或 Ant Design Table 自带的大数据量优化。Ant Design Table 在开启virtual属性后只渲染可视区域内的行滚动时动态替换几千条数据的滚动流畅度是可以接受的。另外对于表格首屏渲染性能有经验的做法是列的width尽量都显式设置。表格列有明确宽度时浏览器在计算布局时不用反复测量实际内容宽度滚动刷新时开销更小而且内容万一超长还会有ellipsis截断视觉效果更整齐。6. 性能优化的关键手段6.1 React.memo 的正确使用方式React 18 并发特性之下memo依然是一项保留优化手段。但很多人用错位置给每个组件都包一层memo结果性能没提升反而因为浅比较增加了额外计算。memo应该用在容易被父组件重渲染波及、而自身重渲染代价昂贵的组件上。表格行组件、复杂表单子组件、图表卡片这类组件包上memo效果明显。普通文本展示、纯布局组件包了没意义。还有一个关键点如果父组件传了一个内联函数给被memo包裹的子组件子组件的memo会失效。因为每次父组件渲染都会创建新的函数引用浅比较必然不相等。所以内联回调函数应该配合useCallback使用const handleRowClick useCallback((record: UserItem) { console.log(click row, record.id) }, [])6.2 懒加载与代码分割的落地细节路由懒加载已经在路由设计中用到了lazy()会按路由拆分 chunk。还有一些非路由级别的懒加载场景值得注意弹窗组件如果体积较大比如一个复杂富文本编辑器、图表编辑器不应跟主页面打包在一起而应该按需懒加载。const RichEditor lazy(() import(/shared/components/RichEditor)) // 弹窗打开时才加载编辑器代码 Modal open{open} title编辑详情 Suspense fallback{Spin /} {open RichEditor /} /Suspense /Modal用{open RichEditor /}确保弹窗未打开时编辑器组件不会被加载到浏览器。首次打开弹窗时会有一个短暂 loading但后续打开秒开因为 chunk 已经被浏览器缓存。代码分割的推荐粒度是按路由和按大组件不是每个小组件都分割。chunk 太多会导致浏览器并发请求过多反而拖慢首屏。经验值是小项目 5 到 20 个 chunk大项目 100 到 300 个 chunk 比较正常不要再细。6.3 图片资源的压缩与懒加载中后台项目图片主要来自两类静态资源如 logo、图标和用户上传的业务图片。静态资源建议用 SVG 格式体积小且清晰度无损业务图片在上传时后端就应该做压缩、剪裁、WebP 转换前端不需要承担太多。列表页的图片缩略图必须懒加载。用原生loadinglazy就能解决大部分问题不需要引入额外的库img src{item.coverUrl} loadinglazy width80 height80 alt封面 /给图片显式加width和height可以避免因图片加载导致的布局偏移这个细节会让页面的 CLS累积布局偏移指标好看很多。如果遇到老接口返回的图片地址特别大比如原图 5MB 直接展示在缩略图位置前端可以尝试在 URL 上拼接后端支持的压缩参数比如?imageView2/2/w/200或类似规格。大多数对象存储服务支持这种动态处理不需要后端动手。6.4 高频状态更新的性能保护列表页中常见的高频更新场景是表格行内状态切换、实时进度刷新、输入框自动保存。这些都是单组件内的高频 setStateReact 本身的批处理机制能合并部分渲染但仍然要小心避免不必要的大范围重渲染。如果是表格行内高频率更新的数据最好将每一行抽成独立的 memo 子组件更新只影响当前行而不是整个表格重渲染const UserRow memo(({ user, onToggle }: { user: UserItem; onToggle: (id: string) void }) { return ( div span{user.name}/span Switch checked{user.active} onChange{() onToggle(user.id)} / /div ) })如果存在跨组件的高频共享状态例如全局任务队列的进度Zustand 的订阅粒度优势就体现出来了——只有使用了该状态的组件会重新渲染其他组件完全不受影响。7. 常见问题与排障实录7.1 路由切换后页面不滚动到顶部rea项目中很经典的一个问题从列表页翻到详情页页面还停留在列表页的滚动位置体验很割裂。React Router v6 默认不会重置滚动位置需要手动处理。我的做法是在路由切换的根组件上监听pathname变化设置window.scrollTo(0, 0)// src/app/components/ScrollToTop.tsx import { useEffect } from react import { useLocation } from react-router-dom export function ScrollToTop() { const { pathname } useLocation() useEffect(() { window.scrollTo(0, 0) }, [pathname]) return null }在布局组件的最外层加上这个无渲染组件即可。但要注意如果分页表格翻页后切走再切回来表格的滚动位置是保不住的一般会默认回到第一页这是可接受的正常体验。7.2 useRequest 的重复请求问题useRequest自定义 Hook 里我写的依赖数组里有fetcher如果fetcher是每次渲染都新建的函数那么useEffect会每次渲染都重新请求。这个问题我在模板里已经用useCallback包裹查询函数解决了但实际项目中还是会有人漏掉。排查技巧在请求函数开头加一个 console.log如果发现组件只要有任何 state 变化就打印一次请求说明useCallback没有包好或者依赖数组没写对。// 错误的写法 const { data, loading } useRequest(async () fetchUserList(queryParams))这种写法中fetcher每次都变useRequest内部useEffect依赖fetcher往复循环可能导致无限请求。正确写法const { data, loading } useRequest( useCallback(() fetchUserList(queryParams), [queryParams]) )7.3 样式隔离与 CSS 命名冲突中后台项目引入第三方 UI 库如 Ant Design后经常遇到自定义样式覆盖无效的问题。很多人直接写全局 CSS 强制覆盖结果导致其他页面的组件样式跟着变。正确的覆盖姿势是用 CSS Modules 或 CSS-in-JS 方案。以 CSS Modules 为例// index.module.css .customCard { border-radius: 8px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06); } // index.tsx import styles from ./index.module.css Card className{styles.customCard}Vite 对*.module.css内置支持不需要额外配置。这样可以完全避免组件库样式的类名冲突局部覆盖也不会污染到其他地方。如果非得用全局 CSS 覆盖第三方组件样式务必确保选择器带有明确的业务前缀且不要使用!important除极少数必须的场合。!important是样式排查的噩梦后期维护成本极高。7.4 表格列固定导致的错位使用 Ant Design Table 的fixed列功能时偶尔表格会出现列错位、横向滚动条不灵敏的问题。这类问题的根因通常不是表格组件 bug而是表格容器宽度不稳定、或弹窗打开时表格宽度的重新计算时机不对。比较稳妥的解决办法弹窗打开时给表格外层容器一个确定的宽度而不是让它撑满整个弹窗内容区。表格加载数据后出现未知原因错位时调用表格的resizeObserver重算const tableRef useRefHTMLDivElement(null) useEffect(() { const updateTable () { // 触发表格重新测量 if (tableRef.current) { // 这里不需要直接调用表格实例 const event new Event(resize) window.dispatchEvent(event) } } window.addEventListener(resize, updateTable) return () window.removeEventListener(resize, updateTable) }, [])如果发现固定列在弹窗打开后首次渲染就错位最常见的根因是弹窗内容区的宽度从 0 变为某个值的过程Table 没有触发重算。这时可以用destroyOnClose让弹窗关闭时销毁内容重新打开时重新挂载表格通常能解决。更多的问题定位思路可以用 React DevTools 的 Profiler 录制交互过程查看哪个组件耗时最长、渲染次数最多。一般来说 95% 的卡顿都出在表格行未拆成 memo 子组件、列表页未做防抖、状态更新导致整个页面重渲染这三类情况。7.5 生产构建后路由刷新 404本地开发一切正常部署到服务器后点击刷新出现 404这是 SPA 部署最常见的坑。原因是在history模式下只有index.html这一个入口文件当用户访问/user/list时服务器找不到对应的物理文件就抛了 404。后端配置需要将所有路由回退到index.html。Nginx 的配置一般是location / { try_files $uri $uri/ /index.html; }如果是静态托管平台如某些对象存储静态站点需要在平台的面板里配置“默认首页”和“错误页面”为index.html或直接开启 SPA 模式。还有一点容易漏vite.config.ts里的base配置。如果项目是在子路径如https://example.com/rea/下部署的需要设置base: /rea/否则打包后的资源引用路径会指向根目录导致样式和脚本 404。8. 一些实操心得与扩展建议8.1 后端接口约定的提前确立rea项目开发到后期大部分返工因为前后端接口字段语义不统一。一个常见问题是分页接口后端返回{ items: [...], total: 100 }另一个接口返回{ list: [...], total: 100 }前端每对接一个都要看文档或手动适配。我现在的做法是在一开始就推动前后端统一响应结构并在前端封装层就做一次收敛// src/shared/types/api.ts export interface PageResultT { list: T[] total: number page: number pageSize: number }所有分页接口统一返回PageResultT前端直接用同一套类型定义。如果后端有人用了items在拦截器里做一个字段兼容处理就能避免大量低级 bug。8.2 数据乐观更新列表页的操作如删除、状态切换如果都要等接口返回后再刷新交互体验总是慢半拍。rea中我经常用乐观更新的思维先在本地立刻改变 UI 状态同时发出请求如果请求失败再回滚。Zustand 中的乐观更新写法const toggleUserActive async (userId: string) { const prevState useUserStore.getState().users // 先更新本地 useUserStore.setState({ users: prevState.map((u) u.id userId ? { ...u, active: !u.active } : u) }) try { await apiToggleUserActive(userId) } catch (err) { // 失败回滚 useUserStore.setState({ users: prevState }) } }这套模式在单机或低延迟场景下体验极佳。但要注意不要把乐观更新用于涉及强一致性的场景如支付确认、库存扣减它只适合状态可回滚、业务可容忍短暂不一致的交互。8.3 项目结构随规模扩张的演进rea项目的规模会从两三个模块增长到十几个模块。模块越来越多时原先完全平铺的功能域目录的效率会下降——比如modules/下面有 20 个一级目录IDE 的文件树会非常长。这时候我会建议引入领域分组的思路把modules再按业务域划分为modules/auth/、modules/trade/、modules/ops/等。领域内模块之间的引用可以有更多的约定自由度领域间通过shared/共享通用逻辑。这种分层的引入时机不宜过早通常在模块超过 15 个时做一次整体调整收益明显。前端项目的目录重构比后端安全很多只要不改公共接口模块内部移动文件不会影响其他模块。配合 IDE 的移动文件自动更新导入路径重构成本可控。8.4 小技巧记住用户上次的路由位置中后台用户经常有这种需求昨天编辑到一半的页面今天打开系统希望继续。我们可以简单地记录用户离开时的路由位置下次登录时提供“继续上次操作”的入口// 路由切换时记录路径 const location useLocation() useEffect(() { const currentPath location.pathname location.search if (![/login].includes(currentPath)) { localStorage.setItem(rea-last-path, currentPath) } }, [location.pathname, location.search])登录成功后读取rea-last-path如果存在且有权限就直接跳转过去const lastPath localStorage.getItem(rea-last-path) const fallbackPath lastPath !lastPath.startsWith(/login) ? lastPath : /dashboard navigate(fallbackPath)这个功能代码量不大但体验上的反馈很好也算是一个低成本赢得用户好感的设计。需要注意清理用户退出登录时把这个记录清掉避免下次登录直接跳到没有权限的页面。回到最开始朋友问我的问题rea项目该怎么搭才不会踩坑。其实核心就一句话把目录、路由、状态、请求、性能这些层面的事先在设计阶段想清楚而不是写一个功能想一个方案。项目会一直长大你今天随意写的临时逻辑明天可能就成了所有人绕不开的基础设施。先把架子搭正后面的路会顺畅很多。如果这篇经验对你有帮助后续落实到自己的项目上遇到具体问题可以按文中提到的排障思路去定位——多数坑都已有解法你不用再趟一遍。
阅读完成 · 觉得有帮助？
