企业官网建设流程全解析

REA 这个名字，第一次出现其实挺随意的。当时要在仓库里新建一个前端项目目录，大家正忙着重构那个维护了快三年的后台管理系统，没人有心思给项目起什么正经名字，我随手敲了 React Enterprise Application 的缩写：REA。没想到后面大半年，这个名字成了我们内部讨论问题时的高频词，也成了那套前端工程体系的代称。

这篇文章想从头聊聊 REA 是怎么从零搭起来、怎么从一堆“能跑的页面”变成一套“基本可控的工程”的。如果你正在被老项目里混乱的状态、越堆越厚的工具函数、一改就崩的页面搞得头大，或者正准备接手一个中大型 React 应用的工程化改造，那这篇里的选型思路、文件组织方式、状态管理层约定和真实踩坑记录，应该能帮你少走不少弯路。

说到底，前端项目的痛大多不是某个功能难写，而是整体结构撑不住新需求。REA 最大的价值，不是在某个技术上用了多酷的方案，而是把“接下来几个月怎么继续加功能”这件事，变成了一套有规矩、有边界的流程。

1. REA是什么：从一团乱麻到可控的前端工程

先说说为什么要起一个看起来像“文件夹名”的代号。REA 其实不是某个框架，也不是某个开源库，它就是我们对那套 React 企业级应用基础工程的总称。给它一个名字，是为了让团队里每次说起“这一批新页面要不要改骨架”的时候，大家能明确指的是同一套东西，而不是含糊地聊“前端那边怎么弄”。

1.1 为什么要重构而不是继续打补丁

老系统最典型的问题，是代码里各种写法并存。有的页面还在用字符串拼接 HTML 再插入节点，有的组件里维护着一大坨状态散落各处，有的同学喜欢把所有请求结果都塞进全局 store，导致排查一个问题要翻好几个文件。最让人头疼的是改一个公共组件，第二天就有人报“某个页面打不开了”，因为根本没人知道这个组件被多少个地方依赖。

这种状态下继续加需求，其实就是每天给自己挖坑。REA 要解决的，不是某个页面好不好看，而是让项目回到“改动可预测”的状态。我们当时的目标很简单：新功能来了，知道该把代码放哪里；旧页面出了问题，能从报错信息一步步定位到具体位置。听起来很基础，但对于已经乱了几年的系统来说，这本身就是一次不小的改动。

1.2 REA的边界：我们明确不做什么

做工程重构最容易犯的错，是想着把所有老代码一次性重写，最后工作量失控、业务停摆，团队也跟着崩溃。所以 REA 在一开始就划了三条边界。

第一，不重写全部业务逻辑。老系统里很多特殊判断是拿真实业务坑换来的经验，重写的时候极易丢。REA 只搭建新工程的架构和规范，老页面迁移按优先级慢慢来。第二，不追求 100% 的组件复用。很多组件看起来相似，细化后完全不同，强行抽象成一个通用组件只会让每个使用处都沾上一堆条件分支。第三，不改动后端接口协议。接口变更涉及前后端联调、数据库逻辑、历史数据兼容，范围太大，REA 一期只在前端层面做事，把数据边界留给后续单独治理。

这三条边界看着保守，却是 REA 能平稳落地的关键。很多重构失败，不是技术能力不行，而是没想清楚“这次做到哪里为止”。

2. 脚手架与项目结构：REA的骨架是怎么定的

工程化改造的第一步，是先把工程底座立住。选工具、定目录、理路由，这三件事看似基础，却决定了后续所有页面代码长成什么样。

2.1 构建工具选型：Vite + React + TypeScript 的基本盘

构建工具我们最终选了 Vite，搭配 React 和 TypeScript。对中大型项目来说，Vite 带来的开发体验提升非常直观：开发服务器启动快、热更新响应快，不用像以前那样改一行代码等好几秒才能看到效果。Vite 之所以快，是因为它利用浏览器原生 ESM 能力，开发时按需编译，而不是把所有模块一次性打包。

初始化命令很简单：

pnpm create vite rea --template react-ts cd rea pnpm install pnpm add react-router-dom @reduxjs/toolkit react-redux @tanstack/react-query

这里用了 pnpm 而不是 npm，原因是 pnpm 通过硬链接共享依赖，安装速度快，而且严格的依赖隔离能逼着你把每个包都声明在 package.json 里，避免在项目里“幽灵依赖”满天飞。TypeScript 是必须的，对于多人协作的大型应用，类型就是代码之间的契约，重构时敢不敢动一个函数，很大程度取决于类型系统能不能帮你兜底。

2.2 目录分层：让代码待在它该待的地方

REA 的目录结构，是花了最多时间讨论的部分之一。一开始大家习惯把所有组件都平铺在 components 目录里，三个月后这个目录就变成了一个没人敢碰的垃圾场。最终我们定了这样的分层：

rea/ ├─ src/ │ ├─ app/ # 应用初始化、路由配置、全局样式 │ ├─ pages/ # 页面级组件，一个路由对应一个页面 │ ├─ components/ # 跨页面复用的通用展示组件 │ ├─ features/ # 业务模块，按领域组织 │ ├─ shared/ # 工具函数、常量、基础类型定义 │ └─ api/ # 接口请求封装 ├─ public/ └─ vite.config.ts

这套结构的核心思路，是把“通用组件”和“业务模块”分开。components 里只放不依赖业务数据的纯展示组件，比如按钮、弹窗、表单控件；features 则按业务域划分，每个模块内部可以有自己的状态、组件和 API 调用。这样不同业务之间的代码不会互相纠缠，后期某个模块要大改，可以直接钻进 features 对应的目录里处理，不用在全局组件堆里大海捞针。

2.3 路由组织与懒加载：保持页面级独立

路由我们用 React Router 的 createBrowserRouter，每个页面组件都通过懒加载引入。懒加载的意义，不只是省流量，更是让每个页面成为独立的模块边界，页面之间不共享运行时状态。

import { lazy } from 'react'; const Dashboard = lazy(() => import('../pages/dashboard')); const UserList = lazy(() => import('../pages/user-list')); const OrderDetail = lazy(() => import('../pages/order-detail'));

懒加载配合 Suspense 使用。每个路由切换时，如果目标页面的 chunk 还没加载，就显示一个轻量级的 loading 占位。这里有一个容易被忽略的细节：loading 状态不要做得太炫，因为切换页面时出现空白比网络慢更让人困惑。我们后来把 fallback 设计成顶部一条细进度条，既给用户反馈，又不会让界面闪来闪去。

3. 状态管理：REA里数据流动的规矩

状态管理是 React 项目里最容易写乱的地方。REA 里我们定了一条核心原则：先看数据从哪里来，再决定它应该住在哪里。这条原则避免了 80% 的混乱。

3.1 告别全局state的滥用：按数据来源分层

以前的状态管理之所以乱，是因为大家习惯把所有数据都往全局 store 里塞，最终 store 变成一个没有类型的、任何组件都能改的公共沙盒。REA 把状态按来源和生命周期分成了三层：

分层之后，很多原本“必须”用全局 store 的状态，其实都可以留在组件内部。比如一个页面的筛选条件，只有当前页面关心，就根本不需要放 store。我们当时做了个严格的代码审查约定：任何新增的全局状态，必须说明它是被多少个页面共享的；少于两个页面使用的状态，一律不准进 store。

3.2 服务端数据交给请求层缓存管理

服务端数据这块，REA 直接引入了 TanStack Query。它解决的不只是请求状态管理，更重要的是缓存与数据同步。以前每个列表页面都要自己写 loading、error、重新请求的逻辑，而且切走页面再回来，数据必然重新拉一次。TanStack Query 则会把请求结果按 query key 缓存起来，同一份数据多个组件共用时，只需要一次网络请求。

function useUserList() { return useQuery({ queryKey: ['user-list', currentPage], queryFn: () => fetchUserList(currentPage), staleTime: 30 * 1000, }); }

这段代码里，queryKey 是缓存的坐标，currentPage 变化时自动发起新请求；staleTime 表示 30 秒内数据视为新鲜，切换页面回来不会重复打接口。这样一个简单配置，就省掉了以前一大片手写的状态逻辑。后来很多同事反馈，用上这个之后，写列表页的时间几乎少了一半。

3.3 异步竞态：一个REA里最常见的bug

状态管理里最容易踩的坑，是异步请求的竞态问题。典型场景是：用户快速切换两个页面，A 页面的请求还没返回，用户已经切到 B 页面，结果 A 的响应数据回来后被 setState 写进了当前页面，表现出“页面显示的数据是上一页的”这种诡异现象。

REA 里主要通过两种方式解决。一是依赖 TanStack Query 的请求去重与取消能力，切换页面时旧请求不再绑定 UI；二是对于手写 fetch 的场景，统一用 AbortController 或清理函数处理。

useEffect(() => { const controller = new AbortController(); fetchOrderDetail(id, { signal: controller.signal }) .then(setDetail) .catch(() => {}); return () => controller.abort(); }, [id]);

这个习惯一定要养成。所有在 useEffect 里发起的异步请求，都应该在清理函数里中断或标记失活，否则你迟早会被“旧响应覆盖新页面”的 bug 折磨一个晚上。

4. 组件规范：从“能跑”到“经得起多人协作”

工程化改造进行到中段，代码量上来了，新的问题也随之出现：组件怎么拆、拆到什么粒度、谁来复用谁。没有规则的话，每个人都会按自己的审美写，项目很快会退化回没人敢动的状态。

4.1 组件分层的三个桶

REA 把组件分成了三个层级：基础组件、业务组件、页面组件。基础组件是那些脱离业务也能存在的元素，比如表格、弹窗、输入框，它们通常只通过 props 接收数据和回调，不直接发请求。业务组件则是对某个业务场景的封装，比如“用户卡片”“订单状态标签”，它们内部可以调用业务 hook，也可以组合多个基础组件。页面组件就是路由对应的那一层，负责把各种业务组件拼装成完整页面。

这三个层级之间有明确的依赖方向：页面组件可以依赖业务组件和基础组件，业务组件只能依赖基础组件，基础组件谁都不依赖。代码审查时一旦发现反向依赖，全部打回重写。这条规则看似严格，但它保证了组件之间的耦合度不会失控，也让公共组件可以安心演进。

4.2 表单与受控组件的处理

表单在管理后台里是最常见的交互，也是最容易写出重复账的地方。REA 最终选了 react-hook-form 作为表单方案。原因是它能减少受控组件引起的多余渲染，同时用 Controller 把自定义组件接入表单时，代码更整洁。

const { control, handleSubmit } = useForm(); <Controller name="name" control={control} render={({ field }) => <Input {...field} />} />

关于表单状态，有一条硬约定：表单内部状态不允许放进全局 store。理由很直接，用户在输入框里打每一个字如果都触发全局状态更新，整个应用都会跟着重渲染，性能影响非常大。表单状态就应该活在表单组件自己的生命周期里，只有最终提交结果才跨组件共享。

4.3 组件拆分的判断：什么时候值得重构

组件不是拆得越细越好。拆太碎了，props 会越传越多，逻辑被拆得七零八落；拆太粗了，一个文件几百行，改哪里都像是踩雷区。REA 实践下来，常用的判断标准有三条：文件超过 300 行、一个组件有五个以上的事件处理函数、同一个组件被两个以上页面复用。满足任意一条，就该认真考虑拆分了。

拆分的时候也要记住，重构不是目的，可维护性才是。如果某个组件内部逻辑虽然长，但高度内聚，也不一定要立刻拆。我们吃过强行抽象组件的亏：两个看似类似的区域被合并成一个大组件后，各种 branch 条件堆在上面，最后比不拆还难维护。所以 REA 的规矩是，拆分必须先有明确的业务边界，而不是仅仅因为“代码看着太长”。

5. 性能优化：首屏加载时间从4秒多降到1.5秒

性能优化不能靠感觉，要先量化再动手。REA 上线后的第一次性能检查，首屏加载时间是 4 秒多，高峰期甚至要 5 秒。整个优化过程可以分成四步，每一步都对应可验证的数据改善。

5.1 资源体积分析：先量化再动手

我们没有一上来就猜是哪个组件慢，而是先用打包体积分析工具看了一遍产物。结果很扎眼：首屏依赖的一个主 chunk 有 2MB 多，打开看分布，第三方 UI 库占了将近一半，业务代码也全被挤在了一起。这个分析直接决定了优化方向：先拆分第三方库，再按路由拆业务代码。

5.2 代码分割与按需加载

路由懒加载在前面的骨架部分已经做了，但还不够。UI 组件库的大体积依然堆在主 chunk 里。我们做了两件事：一是按需引入组件，不再从入口文件统一 import 整个组件库；二是在 Vite 的构建配置里手动拆分 vendor 包，把 react、react-dom 和组件库分别拆到独立 chunk。

build: { rollupOptions: { output: { manualChunks: { react: ['react', 'react-dom'], antd: ['antd'], }, }, }, }

这样改完，首屏加载只需要 html、运行时代码、react 相关 chunk 和页面自己的 chunk，UI 库的沉重代码等到实际用到对应组件时再加载。这一步做完，首屏时间直接砍掉了三分之一。

5.3 长列表与重复渲染优化

管理后台的列表页动辄几百行，一次性渲染会让页面卡顿明显。REA 引入了虚拟滚动方案，只渲染可视区域内的行。这个优化对于表格、日志列表这类长数据场景几乎是刚需。

渲染优化方面，我们用了 memo、useMemo、useCallback，但也不是无脑乱加。React 的渲染优化本质是减少不必要的重复计算和子组件重渲染，而不是把每一处都包一层缓存。我们定了个规矩：只有当前组件确实因为父组件频繁更新而出现性能问题时，才做这层优化；普通场景直接写普通代码，保持可读性。

5.4 构建层面的压缩与缓存

下一步是构建产物层面的优化。REA 在部署前用构建插件开启了 gzip 压缩，资源体积进一步缩小。配合静态资源文件名加内容哈希，用户在发版后不会因为浏览器缓存而加载到旧的代码。

这里有个容易踩的坑：gzip 只能在服务器开启相应响应头或者托管平台支持时生效。如果你只在本地压缩了文件，服务器没有对应能力，那这个优化等于白做。部署之后可以通过浏览器的网络面板看响应头 content-encoding 是否出现 gzip 字段，确认真的生效了。

经过这几轮优化，REA 的首屏加载时间稳定在 1.5 秒左右，高峰期也没有超过 2 秒。性能优化最怕没有度量，每次改动前后都记录数据，团队才知道投入产出比到底怎么样。

6. 部署与线上稳定性：REA上线前后的那几件事

工程架子搭好了、页面也迁移了一批，接下来就是上线。上线这件事，代码能跑只是最基础的要求，真正考验的是交付流程和异常处理。

6.1 CI检查：把低级错误挡在合并前

REA 的代码仓库在合并前必须过一轮自动化检查。命令顺序是这样的：先跑 lint 检查代码风格和明显错误，再做类型检查，然后跑核心组件和工具函数的单元测试，最后执行生产构建。任何一步失败，合并请求都会被拦截。

这个流程的低级错误拦截率非常高。有了它，那种“本地能跑、同事拉下来就报错”的尴尬情况大大减少。最常见的漏网之鱼是类型错误，TypeScript 的严格模式下，一个 null 可能没处理，代码在开发环境不报错，构建到生产环境下直接白屏。CI 里把 tsc 检查加上后，这类问题在合并前就被解决了。

6.2 构建产物与静态资源部署

REA 的前端是纯静态资源，构建后就是一个 dist 目录。部署时把 dist 下的文件同步到目标服务器或云存储，再由网关托管。这里必须注意 history 路由的配合：单页应用的所有前端路由路径，在没有对应物理文件时，都需要重写到 index.html。

如果部署时忘了这一步，用户刷新某个子页面就会出现 404。REA 在部署脚本里专门加了一个 rewrite 规则，把所有非静态资源路径都指向 index.html，同时排除掉带内容哈希的 js/css 文件，让它们按真实文件路径访问。

6.3 错误监控与版本回滚

线上稳定性的底气来自监控。REA 接入了前端错误监控，并且把 sourcemap 单独上传，线上报错堆栈能还原成原始源码位置。这让“用户说页面打不开”变成了“后台监控显示某行代码抛了 TypeError”，排查效率直接提升一个量级。

回滚流程也是上线前就定好的。每次发版前，部署系统都会把当前线上版本号记录下来，如果新版本上线后监控数据出现异常，一键回滚到上一个版本。这个操作一定要提前演练，别等到出事的时候再翻部署文档。

7. 复盘：REA踩过的几个坑和现在的状态

工程化改造的过程中，我们踩的坑比想象中多。这里挑四个比较典型的记录下来，给后来的人提个醒。

7.1 npm依赖升级引发的连锁反应

有一次需要升级某个构建相关依赖，顺手把好几个包一起升了。结果升级完成后，生产构建突然多了一堆兼容性错误，排查了很久才发现是某个底层工具链的新版本改变了目标浏览器编译规则，导致一段老代码在低版本浏览器上报错。这个坑给我们留下的教训是：依赖升级永远要单独建分支，一次只升一个包，并且升级完必须跑完整构建和核心流程验证。

7.2 路由懒加载带来的首屏白屏问题

懒加载本身是个优化，但它也带来了新的风险。如果一个页面 chunk 的加载失败或者网络异常，用户会卡在白屏状态。这个坑我们发现是某次 CDN 缓存错误导致的，所有新增页面 chunk 都返回了旧的 html 内容。后来我们在路由外层加了错误边界，捕获加载失败后展示友好提示并提供重试按钮，同时在加载期间用细进度条代替空白。

7.3 状态缓存与服务端数据不同步

TanStack Query 的缓存解决了很多重复请求问题，但它也引入了数据“过期”的概念。有一个列表页，用户修改了数据后回到列表，列表依然是旧数据。就是因为列表接口被缓存了，而修改操作并没有触发缓存失效。解决方案很简单：在修改成功后调用一次 invalidateQueries，让列表查询失效并重新拉取。这件事情告诉我们，引入缓存机制的时候，必须同步设计好失效策略。

7.4 迁移老页面时丢失的组件状态

老页面从全局 store 改为本地状态时，最容易丢状态。有个典型的例子：一个筛选面板的展开状态原本放在 store 里，切换菜单再回来它还是展开的；改成组件本地状态后，组件卸载再重新挂载，展开状态就没了。

这个问题的本质是“这个状态到底应该跟随页面还是跟随组件”。REA 后来定了个判断标准：如果用户离开页面再回来之后，状态必须保留，就把它归到页面级的状态容器；如果只是一个临时交互状态，跟随组件就够了。迁移老页面时，我们用这个标准逐个核对，之后就没再出现过类似问题。

到现在，REA 这个代号还在用，虽然它的含义早从 React Enterprise Application 变成了大家默认的“我们那套架子”。回头再看这段工程化改造，我最深的感触是：一个前端项目的上限，往往不是某个技术方案有多高级，而是骨架是否稳定、边界是否清晰、状态是否可控。如果你也在做类似的改造，先把状态分层和目录边界定死，再开始写页面。架子决定上限，代码决定下限，这两件事都值得认真对待。