企业官网建设流程全解析

"rea"这个项目，其实是我前段时间接手的一个前端重构Demo。名字没什么讲究，就是取自React的前三个字母——当时立项的时候大家懒得想名字，谁也不想为一个内部项目绞尽脑汁，就直接用"rea"顶上了。结果这个名字一直用到了上线，反而成了问起来都能记住的代号。

这个项目解决的是一个很具体的问题：一个数据看板类应用，原来用老一套的jQuery加模板引擎堆了两年，页面越来越臃肿，状态管理基本靠全局变量，线上时不时冒出诡异的数据不同步bug。团队决定全面重写，"rea"就是这次重写的产物——一个基于React 18、TypeScript、Redux Toolkit和Vite构建的跨端数据看板。

如果你正打算从传统前端技术栈迁移到React，或者你已经在用React但想看看一个完整的工程化项目是怎么把状态管理、异步请求、性能优化和工程规范围着同一个目标串起来的，那这篇内容应该会有参考价值。下面记录的不只是代码层面的实现，更多是我踩完坑之后才知道的那些"为什么"。

1. 整体设计思路与关键技术选型

1.1 "rea"项目到底在做什么

先交代一下项目的基本盘。这个看板应用服务的场景是内部运营数据汇总，需要实时刷新多个指标卡、趋势图、排行榜和数据表格，同时还有跨部门的权限控制：不同角色登录后看到的菜单、按钮、字段都不一样。数据量不算夸张，但刷新频率高，交互逻辑复杂。

旧系统的问题相当典型：

• 全局状态散落在十几个window变量里，组件间通信靠事件互相触发，链路一长就完全理不清。
• 每次数据刷新都是整页重渲染，图表操作卡顿明显。
• 权限判断写死在HTML模板里，后端返回一个角色枚举，前端用字符串拼接的方式自行判断，新增一个角色就得改一遍代码。

重构的目标很明确：一是把状态集中管理，二是把权限逻辑抽成可配置的元数据，三是在保持业务不变的前提下把交互流畅度提上去。"rea"就是围绕这三个目标搭起来的。我在项目开始的时候用"目标-约束-取舍"的方式拆了一下：

这三个目标基本定义了项目的骨架。后来所有技术决策都围绕着它们展开，没有出现因为单纯炫技而偏离主线的情况。

1.2 技术栈选型的逻辑与取舍

很多人选技术栈喜欢追新，但我个人的原则是"用团队最容易上手且生态成熟的组合"。React 18是当时的主流稳定版本，TypeScript带来了类型安全，Vite提供了极快的冷启动——这三个组合在一起，几乎没有学习成本之外的缺点。

关于Vite和webpack的取舍，这里多说两句。Vite在开发环境下基于原生ES Module，冷启动基本在一秒内，热更新的速度比webpack快一个量级。对"rea"这种每次改动都要立刻看到效果的看板项目来说，开发体验的提升是立竿见影的。生产构建方面，Vite底层用的是Rollup，对代码分割和Tree Shaking的支持都做得很好。

但Vite也不是没有坑。项目依赖里有一个老旧的图表插件，它内部用CommonJS方式引用了一些Node环境才有的模块，Vite在预构建时直接报错。最终处理方案是把这个插件单独放到external列表里，用script标签在HTML中引用全局变量，再通过window上挂载的对象来调用。这个坑在后面讲构建配置时还会细说。

选Redux Toolkit而不是原生Redux，最直接的原因是模板代码量差了三倍。原生Redux需要手写action类型、action创建函数、reducer的switch分支，Redux Toolkit用createSlice一个方法就全搞定了。而且它自带的Immer中间件允许在reducer里直接写"看似可变"的代码，心智负担小很多。

异步处理选了redux-thunk，没有用redux-saga。理由很朴素：这个项目没有复杂的异步竞态管理需求，saga的学习成本和调试成本都不低，thunk足以覆盖"请求-成功-失败"这种常规流程。一个经验是，别为了架构好看而引入超出问题复杂度的方案。

1.3 组件设计模式的要点

组件设计这块，我采用的是"容器组件/展示组件"加自定义Hook结合的思路。最底层是一批展示组件，只接收props，不做任何数据请求；再往上是自定义Hook，负责把状态和逻辑从组件里抽出来；最外层是页面级别的容器组件，负责把这些组合起来。

举一个实际例子：指标卡组件只接收value、title、loading这几个props，图表组件只接收data和config。这样做的直接好处是，组件可以独立在Storybook里预览，测试和联调都方便。

自定义Hook是这次重构里用得最顺手的东西。比如useDashboardData这个Hook，封装了"拉取看板数据、管理加载状态、处理错误重试"的逻辑，任何页面只要调用这个Hook就能拿到完整的数据流。代码复用率上去了，测试也更容易写——你不需要渲染组件，单纯调Hook就能断言数据状态。

说到底，组件划分的核心不是追求极致的抽象，而是让每个文件都能被快速读懂。我见过把组件拆到两三百行以上、props传十几层的项目，那种"为了架构而架构"的设计比不设计更可怕。

2. 核心功能模块与实现细节

2.1 状态管理的完整方案

Redux Toolkit的store结构，我按业务域拆了四个slice：dashboard（看板数据）、user（用户信息与权限）、app（全局UI状态，如侧边栏展开收起）、notification（消息通知）。每个slice内部用createAsyncThunk处理异步action。

createAsyncThunk的使用有一个非常容易被忽略的点：它生成pending、fulfilled、rejected三个状态，但reducer默认只处理fulfilled的返回值。如果请求失败，你必须显式处理rejected，否则界面会一直停留在loading状态，用户会以为页面卡死了。

我在"rea"里的做法是，在rejected的回调里统一写入一个error字段，并且配合一个全局错误提示组件去展示。状态结构如下：

interface DashboardState { data: DashboardData | null; loading: 'idle' | 'pending' | 'succeeded' | 'failed'; error: string | null; lastUpdated: number | null; }

这里用loading的四种字符串状态，而不是简单的boolean isLoading，最大的好处是能区分"初始未加载"和"正在加载"。很多项目用两个boolean（isLoading和hasLoaded）来表示，很容易出现组合状态的遗漏。

关于Immer中间件，遇到过的一个真实内存问题：在一个高频更新的slice里，往state里push新的数据点，同时保留过去24小时的所有数据。因为Immer会做结构共享，每次更新都会生成新的对象图，旧对象如果还被图表组件引用，内存就一直释放不掉。解决方法是限制数据窗口，只保留最近2000个点，超出部分直接丢弃。

2.2 异步请求与缓存策略的实现

异步请求层我封装了一个request工具函数，基于fetch实现，统一处理超时、错误码映射和Token注入。这里有一个很重要的细节：fetch本身不对超时做处理，必须自己通过AbortController来实现。

function request<T>(url: string, options: RequestInit = {}, timeout = 15000): Promise<T> { const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), timeout); return fetch(url, { ...options, signal: controller.signal }) .then(handleResponse) .finally(() => clearTimeout(timer)); }

缓存策略方面，"rea"采用了SWR（stale-while-revalidate）的思路，但没有额外引入库，自己用Map实现了一个轻量缓存。看板数据每30秒轮询一次，在数据未过期时直接返回缓存，同时后台静默更新数据源。

这个方案在体验上的提升非常明显：用户切换Tab再回来时，界面几乎是瞬间展示缓存数据，而不是空白的加载状态。轮询背后的定时器在页面隐藏时会被清掉，避免无谓的请求浪费。

这里还有一个竞态条件的坑需要提醒：用户快速切换筛选条件时，可能出现旧请求晚于新请求返回的情况，导致界面展示的是过期数据。我的处理方式是，在请求工具里维护一个自增序号，每次发起新请求时自增，响应返回后只有序号最大的那次才被采用。

2.3 权限系统的前端落地

权限控制是"rea"项目里最容易被低估难度的一块。需求是：菜单、按钮、字段三级权限都受控，角色由后端下发，前端要做的是根据角色过滤可见性。

菜单级控制我用的是路由守卫。在路由配置上给每条路由加一个meta.permission字段，然后在路由前置守卫里判断当前用户是否有权限，没有就直接重定向到403页面。

按钮级控制通过封装一个<Permission>组件来实现。React里没有像Vue那样的原生指令，所以需要用组件来包裹按钮：

<Permission code="dashboard:export"> <button onClick={handleExport}>导出数据</button> </Permission>

Permission组件内部读取当前用户的权限码集合，如果不存在就把children渲染为null。

字段级控制是最麻烦的。同一个表格，不同角色看到不同列。我采用的方式是在表头配置里标注权限码，渲染列的时候先过滤一遍再展示。

权限逻辑的核心经验是：权限码的定义一定要集中管理，不能散落在各个页面里。我建了一个permissionCodes.ts文件，统一定义所有权限码常量，任何地方都引用常量而不是字符串字面量。这样新增权限时，IDE的类型检查会自动帮你找出所有需要更新的位置，改起来非常安心。

3. 性能优化与工程化落地实战

3.1 首屏加载的极致压缩

看板类应用对首屏加载的要求极高，第一眼看不到图表的用户大概率会直接关掉页面。我在"rea"上做的第一项性能优化就是路由级别的代码分割。

React.lazy和Suspense是标配：

const DashboardPage = React.lazy(() => import('./pages/DashboardPage')); const SettingsPage = React.lazy(() => import('./pages/SettingsPage'));

这样一来，首屏只需要加载DashboardPage的代码，其他页面都按需加载。配合Vite的构建配置，每个路由独立成chunk。

但这里有个细节：React.lazy对同一个模块的多次加载会去重，但如果用户快速切换路由，可能会出现Suspense的fallback频繁闪烁。我的经验是设置一个最小加载时间阈值，保证fallback至少展示300毫秒后再切走，避免白屏闪烁造成的视觉不适。

除了代码分割，资源层面也做了优化：

• 所有图标改用SVG sprite，减少HTTP请求数。
• 图表库使用按需注册，只注册用到的图形类型。
• 图片资源切到CDN，并用WebP格式。

首屏优化做完后，加载时间从3.2秒降到了1.4秒左右，在内部网络环境下体验非常明显。

3.2 Vite构建配置的踩坑记录

Vite的构建配置是"rea"项目里坑最多的地方，前面提到的老图表插件算一个，还有几个值得记录的。

第一个坑：代码分割策略。默认情况下Vite把所有动态import的chunk按引用关系打包，两个页面都依赖同一个大型公共库时，公共部分会被打成共享chunk。我的处理是在rollupOptions.output.manualChunks里显式分组：

manualChunks: { vendor: ['react', 'react-dom', 'redux', 'react-redux'], charts: ['echarts', 'echarts-gl'] }

第二个坑：环境变量的注入。Vite用import.meta.env代替了process.env，老代码里用到process.env.NODE_ENV的地方需要兼容处理。我在vite.config.ts里用define做了全局替换：

define: { 'process.env.NODE_ENV': JSON.stringify('production') }

第三个坑：文件名hash。默认情况下Vite生成的CSS文件名不带hash，长缓存策略下样式不会更新。我在build.cssFilename里加上了hash标识，这样每次构建的CSS文件都是新的。

构建优化的核心思路是：优先看哪些模块是"重"的，哪里重就往哪里动手。不要一上来就优化代码业务逻辑里的微操作，先把打包这关过了，收益最大。

3.3 开发体验与Mock机制的改进

开发阶段的体验直接影响整个团队的效率。Vite的冷启动很快，但"rea"的场景下还是有几个绕不开的问题。

第一个是Mock数据。后端接口当时还没完全就绪，前端需要一套稳定的Mock方案。有人喜欢用MSW，有人喜欢自建Node中间层，我选了把Mock能力直接集成到request工具函数里：当环境变量REACT_APP_USE_MOCK为true时，request会读取本地mock目录里的JSON文件，返回模拟数据。

这样做的好处是，前端开发、单元测试、联调环境可以无缝切换，不需要改业务代码。开关在.env.development里配，一个环境变量搞定。

第二个是TypeScript的编译速度。Vite启动时不打包类型，但IDE的ts服务仍然会对整个项目做类型检查，项目一大就会卡。我用了项目引用的方式，把tsconfig拆成主配置和node配置两部分，并在编辑器设置里让ts服务只加载必要的文件。

开发体验的优化有个原则：任何让开发等待超过5秒的操作都值得改进。启动慢、热更新慢、类型检查慢，这些都是实打实的效率杀手，优先级应该排在业务功能之前。

4. 高频踩坑与问题排查实录

4.1 状态更新了但界面不动的谜案

这个现象我排查了将近两天。现象是：Redux DevTools里能看到state的变化，但组件UI始终不刷新。

最终定位到的原因是对数组的原地修改。有一段代码直接对state.data.items做了push操作，Immer虽然允许写操作，但这里的state是另一个模块通过引用传过来的，绕过了Immer的代理，导致Redux认为引用没变、没有触发重渲染。

排查的思路分享给大家：

1. 先在reducer里手动return一个新对象，看UI是否刷新，排除渲染层问题。
2. 再用Immer的freeze方法检查是否修改了共享引用。
3. 最后看是否在类组件里写了shouldComponentUpdate或memo的比较逻辑。

我最常犯的其实还是第三种：给memo组件传了一个每次渲染都新建的函数引用，导致memo永远比较不等，性能反而下降。这个坑很隐蔽，因为功能没错，只是性能有问题，只有用profiler才能看出来。解决方法是把函数用useCallback包起来，或者把依赖值放进useMemo里。

4.2 列表key值引起的图表错位

"rea"里的图表组件渲染的数据项较多，一开始用index作为key，结果在数据重排时出现了图表错乱。这个问题的本质是：React复用DOM节点时，key的变化会导致组件内部状态错位。

用index做key，在头部插入新数据时，所有元素的key都会变化，React会认为所有节点都变了，直接重建整个列表。重建的瞬间图表会出现闪烁和卡顿。

正确做法是给每条数据生成一个稳定的唯一ID。如果后端没提供，就在前端用crypto.randomUUID生成一次，然后缓存起来，不要每次渲染都重新生成。用index做key的真正高危场景是排序——排序时数据顺序变化但数据本体没变，用唯一ID能保证组件状态跟着数据走，而不是跟着位置走。

4.3 生产环境样式丢失与缓存失效

上线后遇到一个很刁钻的问题：部分用户反馈样式错乱，刷新后又正常。查了半天发现是CSS文件的缓存策略问题，Vite生成的CSS文件名带hash，但CDN节点的缓存过期时间和HTML本身的更新不同步，导致用户拿到旧的HTML但请求新的CSS文件名，资源加载不到。

解决方法是给CDN配置回源校验，并且把CSS和JS的缓存时间设为一致。同时，在部署脚本里加了构建前后的hash比对，防止旧缓存服务旧资源。

这里还想分享一个通用排查技巧：打开浏览器控制台的Network面板，看CSS请求的响应码，如果发现404或MIME type不匹配，大概率是资源文件没有正确上传或者命名不一致。这个排查方法在几乎所有前端项目里都通用。

4.4 高频轮询导致的内存增长问题

看板页面的轮询机制运行一段时间后，内存占用以肉眼可见的速度攀升。用Performance面板抓了快照发现，图表实例没有正确销毁，每次更新数据都会创建一个新实例，旧实例虽然不可见但仍然被Canvas缓存持有。

ECharts这类图表库，组件卸载时必须手动调用dispose方法，否则Canvas资源不会释放。我在封装图表组件时，在useEffect的清理函数里做了处理：

useEffect(() => { const chart = echarts.init(domRef.current); chart.setOption(option); return () => { chart.dispose(); }; }, [option]);

另外，React 18的StrictMode在开发模式下会执行两次useEffect，导致图表初始化两次。我一开始以为是代码写错了，后来才发现是StrictMode的刻意行为，生产环境不会有这个问题。开发时不要因此放松对重复初始化的警惕，写完清理函数才是正解。

5. 项目复盘与后续可以扩展的方向

5.1 团队协作与代码规范的落地

"rea"项目做出来的一个重要副产品，是一套能在团队里稳定执行的代码规范。之前很多规范文档写在wiki里但没人看，这次我把规范直接落到了工具链上：ESLint加Prettier加husky的pre-commit钩子，统一处理格式和基础规则检查。

比较有意思的是commit message的规范。我引入了一个轻量的commitlint配置，要求所有commit必须遵循"type(scope): description"的格式。刚开始大家都很抵触，觉得麻烦，但坚持三周后，git log的可读性大为改观，回溯bug时能立刻定位到相关改动。

代码评审方面，我给自己和团队都定了硬规则：

1. 任何涉及状态结构的改动，必须有对应的类型定义变更。
2. 新增第三方依赖必须经过全组讨论，防止随手引库导致包体积膨胀。

这两条看起来简单，但真正坚持下来，项目里几乎没有出现过"这个字段从哪来""这个依赖能不能删"的扯皮问题。

5.2 后续可以扩展的方向

"rea"目前已经稳定运行在内部环境，但后续有几个明确的扩展方向。

一是服务端渲染。目前这个看板应用的首屏加载虽然优化了，但SEO和无障碍方面仍然有瓶颈。如果后续需要对外部用户开放，可以考虑用Next.js迁移成SSR或SSG方案。这不是推翻重来，而是把现有组件层保留，只在入口层改渲染策略。

二是引入可视化编排能力。很多数据类产品都在做"拖拽搭看板"的功能，让业务人员自己配置图表和数据源。"rea"目前的配置是代码层面的，后续可以做一个基于JSON Schema的可视化编辑器，把看板模板动态生成。

三是对移动端的适配。当前界面是桌面优先，但运营人员经常需要随时随地盯数据。如果后续要支持手机端，布局需要从固定宽度改成流式布局，图表交互也需要重新设计成触屏友好。

我在实际写代码的过程中越来越觉得，项目命名这种小事往往被低估——一个像"rea"这样简短、无意义、但好记的项目代号，反而能让团队在沟通时少很多负担。然后真正有价值的从来不是代号本身，而是代号背后那些反复打磨过的实现方案。这个项目做完之后，我的体会是：重构的价值不在于用了多新的框架，而在于把那些半懂不懂的问题真正想明白了。