企业官网建设流程全解析

做前端开发的这些年，我一直在折腾React生态里那些“看似简单、实则一碰就碎”的问题：组件拆了又拆还是耦合，状态管了一堆还是乱，新人接手代码十分钟就想跑路。去年我花了大半年时间，把团队内部的基础设施重写了一遍，代号就叫rea。它不是某个开源框架，也不是新语言，而是一套基于React的中后台工程化落地方案，核心就一句话：让前端项目从“能跑”变成“好用、好维护、好扩展”。这篇博文会把rea的设计思路、核心实现、踩坑记录全盘托出，适合正在搭中后台脚手架、或者被React项目维护成本压得喘不过气的同学参考，也可以当作一个从0到1搭建前端工程方案的checklist来用。

1. rea到底在解决什么问题：从“能跑”到“好用”

1.1 中后台项目为什么越做越烂

但凡做过几个后台管理系统的前端，多半都见过这些场景：一个项目三个月后，components目录里堆了两百多个组件，命名从Table到Table3到TableFinal；全局状态里塞了一堆只有单个页面用到的数据；两个模块需要共用一套逻辑，谁也不敢动，因为一动就牵一发动全身。这不是某个团队的问题，而是React中后台项目的通病：框架只给了你组件化的能力，但没有替你决定组件怎么划分、状态怎么流动、请求怎么管理。

我拿盖房子打个比方。React本身是砖头和水泥，你可以按任意姿势砌墙，但如果没有结构设计，房子盖到三层必然歪。中后台业务的特点是页面多、逻辑重、权限细、接口变化频繁，这种情况下，工程方案的约束力比组件写得漂不漂亮重要得多。rea的出发点，就是把“结构设计”这部分抽出来，用一套明确的约定和机制，把项目从无序生长拽回有序迭代。

1.2 rea的设计目标与适用范围

先给rea画个像。它不是一个npm包，也不是脚手架生成器，而是一套工程实践集合，包含目录约定、状态管理思路、路由权限模型、请求层封装、样式方案选型、构建优化配置，以及配套的代码规范。当时我给rea定了三条设计目标：

• 可复用：页面级组件、业务逻辑、请求层能力，都能在项目内低成本复用，不靠复制粘贴。
• 可维护：新人接手代码后，能在半天内搞清楚数据怎么流、页面怎么挂、权限怎么配。
• 可观测：接口错误、页面渲染时间、组件性能问题，都能通过日志和监控快速定位。

适用范围上，rea主要面向中后台管理系统、内部运营工具、数据看板类应用。这些场景有共同特征：登录态强、权限层级多、表格表单密集、交互深度不高。如果要做的是在线编辑器、实时协作白板这类强交互应用，rea这套以“约定优于配置”为基调的方案就不太合适，那部分我会在后面单独说明。

1.3 为什么没有直接上全家桶

当初调研时也考虑过直接引入重型应用框架，比如带状态管理、路由、请求、i18n的一体化方案。纠结了几天，还是在原型验证阶段放弃了。原因有三：

第一，学习成本被转嫁给了整个团队。一体化的方案看着省事，但内部的钩子和约定，只有深度读过源码的人才敢改。中后台项目的核心诉求是快速交付，团队成员水平参差不齐，复杂框架很容易变成黑盒。

第二，可替换性差。前端技术迭代快，今天热门的状态库明天可能就不维护了。rea选择的是“核心技术栈固定，周边可替换”的思路：React和路由这两层不变，状态管理、请求库、样式方案都保留了替换接口。实践下来，这个决策帮我们省了不止一次升级的麻烦。

第三，没必要。中后台80%的需求，用原生React能力加少量轻量库就能解决，重框架带来的是一堆用不上的功能和更长的首屏Bundle。

2. 核心细节与实操要点：rea的架构与关键落地

2.1 目录结构与模块边界

先给出一份rea的目录结构，这是整个方案的地基：

src/ ├── apis/ # 接口定义，按业务域拆分 │ ├── user.ts │ └── order.ts ├── components/ # 通用业务组件，与业务域解耦 │ ├── ProTable/ │ ├── DetailPanel/ │ └── Uploader/ ├── layouts/ # 页面框架：侧边栏、顶栏、多标签页 ├── pages/ # 路由页面，一个路由对应一个目录 │ ├── dashboard/ │ ├── user/ │ └── order/ ├── stores/ # 全局状态，按领域拆分 │ ├── userStore.ts │ └── appStore.ts ├── hooks/ # 可复用逻辑 ├── utils/ # 纯函数工具 ├── router/ # 路由配置与权限映射 ├── styles/ # 全局样式与设计变量 └── types/ # 全局类型定义

这个结构最大的特点是：按业务域聚合，而不是按文件类型聚合。很多React项目喜欢把components、hooks、utils三个目录平铺，最后的结果是“一个功能要跨三个目录找代码”。rea的做法是让每个业务域内的页面、组件、hooks靠在一起，目录名字即导航，新人定位代码靠的就是“先找到业务域，再找具体文件”。

模块边界上，我画了三条铁律：

• 页面不直接调用API，必须通过对应业务域的apis模块转发，避免接口散落在各处。
• 全局状态只放跨页面共享的数据，页面内部的临时状态不许进store。
• 通用组件不能反向依赖业务代码，比如ProTable不能import某个页面里的类型。

这三条看起来简单，但真正执行到位，项目的可维护性会有质的飞跃。当时我们项目里有一个跑了两年的老系统，重构前改一个列表页要动五个文件，重构后平均只需要改两个文件。

2.2 状态管理：从小型Context到轻量外部Store

React社区最不缺的就是状态管理方案，Redux、MobX、Zustand、Jotai，选型文章比代码还多。rea的状态管理思路可以浓缩成一张表：

这里重点说一个我长期踩坑后得出的经验：接口返回的数据，不要放进全局store。很多团队习惯把接口结果set进Redux，然后所有页面共享。问题是，接口数据天然具有“时效性”和“局部性”，放进全局store后，你会为“数据为什么没更新”和“要不要手动刷新”吵翻天。rea的做法是把服务端状态交给专门的请求缓存库处理，全局store只管用户信息、权限、主题这类真正需要全局同步的客户端状态。

2.3 路由与权限模型

中后台路由的复杂度不在“怎么定义路由”，而在“怎么把路由和权限、菜单绑定”。rea的路由模型分三层：

1. 静态路由：登录页、404页、注册页这类所有人可见的路由。
2. 动态路由：由后端返回的菜单/权限数据生成，每个用户看到的菜单不同，可访问的页面也不同。
3. 权限指令：页面内部的按钮级别控制，通过自定义hooks或高阶组件判断。

动态路由的核心代码我会在下一章展开，这里先讲清楚设计意图。为什么路由要由后端数据生成？因为中后台的角色和权限经常调整，如果前端把路由写死，每次新增角色都得发版。把菜单配置挪到后端后，前端只要约定好“路由元信息的字段格式”，剩下就交给接口返回。这样产品经理调整菜单权限时，运营后台点几下就生效，前端不需要参与发布。

路由这块需要特别小心的是刷新白屏。动态路由通常是在用户登录后异步拉取再注册的，浏览器刷新时如果直接访问深层URL，动态路由还没生成，就会先匹配到404。rea的解决方案是：在路由配置里记录“路由是否已初始化”的状态，刷新时先判断store里有没有菜单数据，没有就先拉取再渲染路由组件，而不是让路由立刻抛404。

2.4 请求层与错误处理

中后台项目里，接口请求是最容易出现重复代码的地方。每个页面手写fetch，意味着token注入、超时处理、错误提示、loading状态这些逻辑要重复写几十遍。rea选择统一封装请求层，核心能力有四个：

• Token自动注入与失效跳转：请求拦截器统一从store取token，接口返回401时自动清空登录态并跳转登录页。
• 错误码归一化：后端返回的错误码五花八门，请求层统一转换为前端可识别的错误对象，页面里只需要catch后读error.msg。
• 重复请求取消：表格切换筛选条件时，上一次请求如果不取消，返回顺序错乱就会渲染出错误数据。React 18的AbortController配合请求库的取消机制可以很好解决竞态问题。
• 统一Loading与错误埋点：请求开始、成功、失败都有钩子，方便接入统计系统。

这里有个实操坑：不是所有接口都需要全局loading。有些场景是静默刷新，比如用户改变头像后重新拉取用户信息，这时候转圈会非常突兀。所以rea的请求层默认不开启全局loading，而是支持每个请求单独配置silent模式。

3. 实操过程与核心环节实现：从0搭起rea骨架

3.1 工程初始化与依赖选择

搭建rea的第一步是初始化工程。如果是从零开始，我推荐Vite而不是老牌的Create React App。原因很直接：Vite的开发服务器基于原生ESModule，冷启动速度和热更新都比webpack方案的CRA快一个量级，中后台项目组件数量多的时候，这个时间差从“受不了”变成“感知不到”。

依赖清单如下（当时冻结的版本组合，至今仍然稳定）：

这套选型的核心逻辑是：每个品类只选一个，且都有明确的可替代方案。比如状态管理，Zustand用起来简单，但如果你更习惯Redux Toolkit，rea的store层接口设计也允许直接切换。

3.2 基础配置与构建优化

Vite的配置是rea的关键一环。这里给出核心的vite.config.ts片段，重点是alias、构建分包和环境变量：

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'), }, }, css: { modules: { localsConvention: 'camelCaseOnly', // 统一命名风格 }, preprocessorOptions: { scss: { additionalData: `@import "@/styles/variables.scss";`, }, }, }, build: { rollupOptions: { output: { manualChunks: { react: ['react', 'react-dom', 'react-router-dom'], echarts: ['echarts'], }, }, }, }, server: { port: 8080, proxy: { '/api': { target: 'http://localhost:3000', changeOrigin: true, }, }, }, });

几个要点解释一下：

• alias配@是必做项，否则之后几十个文件里的相对路径../../../会让人崩溃。
• SCSS的additionalData可以把全局设计变量自动注入每个样式文件，这样写组件样式时直接用$primary-color，不需要手动import。
• manualChunks手动分包，把React核心和ECharts这类大体积库拆出来，利用浏览器缓存让用户升级代码时不用重新下载框架文件。

构建优化上，第一优先级永远是控制首屏包体积。我遇到过某系统首屏加载了3.6MB JS，调用rollup-plugin-visualizer一看，ECharts完整版就占了1.4MB。换成按需引入的echarts/core后，体积直接砍掉一大半。rea的每个业务组件都要求“用多少引多少”，禁止import * as echarts这类写法。

3.3 核心代码实现：路由映射与鉴权流程

动态路由是rea最核心的机制。先看后端返回的菜单数据结构约定：

[ { "path": "/order", "name": "订单管理", "icon": "order", "component": "order/OrderList", "children": [ { "path": "/order/detail", "name": "订单详情", "component": "order/OrderDetail" } ] } ]

前端需要一个通用函数，把菜单数据批量转化为React Router的路由对象：

import { lazy } from 'react'; import type { RouteObject } from 'react-router-dom'; import type { MenuItem } from '@/types/menu'; // 用于按需加载页面组件 const moduleCache: Record<string, any> = {}; function loadComponent(componentPath: string) { if (moduleCache[componentPath]) { return moduleCache[componentPath]; } // 约定：component字段对应src/pages/下的路径 const Component = lazy(() => import(`@/pages/${componentPath}`)); moduleCache[componentPath] = Component; return Component; } export function generateRoutes(menus: MenuItem[]): RouteObject[] { return menus.map((menu) => { const route: RouteObject = { path: menu.path, // 有子菜单时，父路由用布局组件包裹 element: menu.children?.length ? <Layout /> : undefined, children: menu.children ? generateRoutes(menu.children) : [{ index: true, element: menu.component ? loadComponent(menu.component) : undefined }], }; return route; }); }

这里有个细节容易踩坑：懒加载组件必须配合Suspense。React Router 6里，如果直接给element传一个lazy组件而不包Suspense，运行时大概率会报A component suspended while responding to synchronous input。rea的做法是在Layout组件的外层包一个统一的<Suspense fallback={<PageLoading />}>，这样所有动态路由懒加载时都有统一的加载态。

鉴权流程上，rea用一层高阶组件做了路由守卫：

function RequireAuth({ children }: { children: JSX.Element }) { const token = useUserStore((state) => state.token); const location = useLocation(); if (!token) { return <Navigate to="/login" state={{ from: location }} replace />; } return children; }

然后在路由配置里统一包一层：

<Route element={<RequireAuth />}> {generatedRoutes} </Route>

3.4 关键指标与性能卡点

rea做完骨架后，我给性能定了三个核心指标，每次迭代必须守住的底线：

这些数字不是随便填的，当时我记录过优化日志。最明显的一次收益是发现项目中引入了一个“现代化”动效库，它内部加载了webgl相关代码，但实际上整个项目只有一个页面的一个按钮用到了它。删掉后，首屏JS体积立刻掉了500KB。性能优化第一位永远是一刀砍掉没用的依赖，第二位才是各种配置技巧。

4. 常见问题与排查技巧实录：我在rea中踩过的坑

4.1 无限渲染与依赖数组

React函数组件最容易翻车的坑之一，就是useEffect搭配了不稳定的依赖项。举个例子，下面这段代码看起来没什么问题：

useEffect(() => { fetchUserList(filters); }, [filters]);

但filters如果是从父组件传下来的对象字面量，比如：

<FilterPanel filters={{ status: 'pending', page: 1 }} />

父组件每次重渲染都会创建一个新对象，useEffect的依赖比较用的是Object.is，只要引用变了就会重新执行。如果fetchUserList又触发了setState，恭喜，你的页面进入了无限渲染循环。

rea的处理方式分两步：第一，依赖项尽量用原始类型，比如把filters拆成status、page两个具体值；第二，非要用对象时，用useMemo缓存它：

const filters = useMemo(() => ({ status: 'pending', page: 1 }), [status, page]);

排查这种问题有个小技巧：React开发者工具里看Profiler，如果某个组件每帧都被重渲染，优先检查它的props里有没有“每次都是新引用”的对象。

4.2 内存泄漏与定时器清理

中后台项目里，图表页是内存泄漏重灾区。很多人在组件里写了这样的代码：

useEffect(() => { const timer = setInterval(() => { refreshChart(); }, 5000); return () => clearInterval(timer); }, []);

这个写法本身没问题，问题出在“只清理了定时器，没清理其他占用”。比如ECharts实例，如果不在卸载时chart.dispose()，它会一直持有DOM引用，页面切换几百次后浏览器卡成PPT。rea的通用hook里内置了清理机制：

function useEChart(domRef: RefObject<HTMLDivElement>) { const chartRef = useRef<ECharts>(); useEffect(() => { const chart = echarts.init(domRef.current); chartRef.current = chart; return () => { chart.dispose(); }; }, []); return chartRef; }

另一个典型是异步请求的竞态。用户在A页面发起请求，请求还没返回就切到了B页面，然后A页面的回调里又setState，控制台报Can't perform a React state update on an unmounted component。rea的方案是，封装一个useMounted的ref，在卸载时标记，所有异步回调先判断一下：

const mountedRef = useRef(true); useEffect(() => { return () => { mountedRef.current = false; }; }, []); const loadData = async () => { const res = await fetchData(); if (mountedRef.current) { setData(res.data); } };

现在React 18里，官方推荐直接用AbortController从源头取消请求，比mountedRef更干净。

4.3 样式冲突与CSS方案选型

全局样式在中后台项目里是双刃剑：变量和工具类能提升一致性，但谁都可以import全局样式，就必然有人造出“全局浮动”这种车祸现场。rea最终用了Sass + CSS Modules双轨制：

• 全局只放设计变量和工具类，比如颜色、间距、字体、flex工具类。
• 每个组件自带.module.scss文件，类名通过CSS Modules自动hash，不会撞车。

有个坑必须说：CSS Modules在Vite里默认启用，但如果你在.module.scss里嵌套了全局类名，比如：

.container { :global(.ant-btn) { color: red; } }

这里的:global(.ant-btn)仍然是全局作用域，务必清楚混用的边界。实际开发中，这种“改组件库内部样式”的需求越来越多，rea的约定是：“组件库样式覆写只允许出现在全局override文件里，业务模块里不许用:global。”

4.4 路由刷新404与部署配置

动态路由已经解决了权限路由的生成问题，但刷新404是另一个层面的坑。当用户访问/order/detail/123时，刷新请求直接打到服务器。前端路由是SPA，服务器没有这个真实路径，如果nginx没配置try_files，就会返回404。部署配置其实很简单：

location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; }

但这里有个更深的问题：所有404都会落到index.html，前端路由里必须自己处理“页面不存在”的分支。rea的做法是在路由配置的最后加一个*匹配，展示自定义404组件，而不是让用户看到白屏。

还有一个小坑是history路由模式。React Router用BrowserRouter时，URL不带#，好看但依赖服务器配合；如果服务器没法配try_files，就只能退回HashRouter。当时我们有个项目部署在客户的私有化环境里，对方的运维策略极保守，改不了nginx配置，我直接把路由模式切回hash，损失一点URL美观度换来部署无依赖，这在ToB场景里是值得的。

4.5 状态不同步与多标签页缓存

中后台系统常做多标签页模式（像浏览器Tab一样切换页面）。这时候会遇到一个经典问题：在列表页点开详情页，修改了数据后返回列表，列表还是旧数据。rea在早期也踩过这个坑，解决方案因地制宜：

• 如果不需要保留页面状态：每次激活标签页时重新请求最新数据，简单粗暴但数据永远新鲜。
• 如果必须保留：用KeepAlive思路，在React里可以用react-activation这类库实现，或者干脆把列表页的数据放到Zustand里，离开页面时不清理。

这个选择没有标准答案，纯看业务。我的建议是：优先重新请求，因为保留状态的复杂度会伴随整个开发周期。只有遇到“用户填了一半表单切出去再切回来，表单内容不能丢”这类强诉求时，再考虑使用页面缓存方案。

5. rea项目的后续扩展与我的心得体会

rea做到这个程度，基本覆盖了一个中后台项目从搭建到稳定交付的全过程。但工程方案不是做完就结束的，它要跟着业务一起演进。我和团队正在琢磨的几个扩展方向，也给各位做个参考。

第一个是微前端化。如果团队里同时跑着React和Vue的项目，又想共用一个登录态和导航壳，微前端确实能解决“物理隔离、逻辑共享”的问题。但它的心智成本和架构复杂度都不低，我的建议是：先问自己是不是真的需要。如果只是几个独立系统的聚合展示，用iframe加一个统一壳往往更省事。

第二个是代码生成与低代码化。中后台80%的页面都是“表格 + 查询表单 + 新增编辑弹窗”三段式，我们正在写一个基于JSON配置生成ProTable页面的工具，目标是让新需求的开发时间从两天压到半天。这里核心是把“页面模板”抽象成可配置的schema，再让rea的运行时组件去渲染它。

最后说说我个人的体会。做rea最大的收获不是技术方案本身，而是一个很朴素的道理：前端的工程化问题，越晚处理代价越高。很多团队觉得“业务快跑最重要，架构等量级大了再搞”。但量级一大，重构的成本是指数级上升的。趁项目还在早期，用rea这类明确约定去约束代码边界，比未来某一天推倒重来要划算得多。如果你现在正被React项目的维护成本折磨，不妨试着从一小块边界开始约束起来，比如先把请求层抽出来，再调整状态管理，一步一步来。工程化改造不需要轰轰烈烈，但需要每次都走在正确的方向上。