企业官网建设流程全解析

1. 项目代号与原始需求拆解

1.1 “rea”到底想解决什么问题

先说清楚：这个项目代号叫“rea”，没有更多官方释义。团队内部叫顺口了，就一直沿用下来，后来复盘时我们试着拆过，有人说是“React Architecture”的浓缩，也有人说是“reactive”的前三个字母，其实都不重要——名字就是个代号，关键是它背后承载的任务。

第一次拿到需求时，我面对的是一个比较典型的问题：某业务线的前端项目已经跑了两三年，功能堆叠得越来越厚，但代码组织方式还停留在“能用就行”的阶段。跨页面共享的数据状态散落在各个组件内部，几个核心页面之间互相传递回调函数，改一个业务逻辑往往要顺藤摸瓜改七八个文件。新来的同事接手时，光是理解“这个状态到底由谁维护”就要花上一两天。

这类问题的教科书级答案其实是现成的：引入状态管理库、统一数据流、组件解耦。但现实远比教科书复杂——老项目不能推翻重写，团队成员对新技术栈的熟悉度参差不齐，线上业务不能停，迭代节奏也不能放缓。所以我们需要一套既符合工程规范、又能平滑落地的渐进式改造方案，“rea”这个项目就是为了承载这套方案而存在的。

1.2 这个项目适合谁来参考

如果你正好处于下面这几种处境，那这篇文章大概率能帮你节省一些试错时间：

• 手上维护着一个运行稳定、但内部结构已显杂乱的 React 中大型项目，想理清状态管理却不敢伤筋动骨。
• 正在几个状态管理库之间犹豫，想知道各自的适用边界，而不是盲目跟风选“最热门”的方案。
• 已经决定要梳理项目的数据流，但不知道从哪个页面入手、怎么落地、怎么避免改着改着就失控。
• 或者你只是刚接触 React 生态不久，想弄明白“状态管理”这件事到底解决的是什么问题。

我会把整个项目的思考链路、技术选型、具体改造步骤、踩过的坑以及最终沉淀的规范一起分享出来，尽量还原一个真实项目的推进过程。我不会只罗列结论，而是把每一步背后的权衡都讲清楚——因为这些权衡恰恰是文档里查不到的东西。

2. 技术选型背后的取舍逻辑

2.1 老项目改造为什么不能直接换框架

每次聊到老项目重构，总会有人提议“干脆重写，顺便升级框架”。这个想法听起来痛快，实际操作却是一场灾难。老项目承载着大量经过线上验证的业务逻辑，重写意味着所有边界条件都要重新覆盖，测试用例、异常处理、兼容性策略全部推倒重来。而业务方不会给你大半年时间去“闭门造车”，他们只管功能照常上线、Bug 不再增多。

所以“rea”项目从一开始就定下了两条硬约束：第一，不改动项目整体技术栈，继续基于现有的 React 版本与构建体系；第二，改造必须是渐进式的，一次只迁移一个模块，迁移完立刻回归验证。这两条约束直接把“重写框架”这种方案挡在了门外。

在这个前提下，技术选型的核心就变成：如何在现有约束下，给项目建立起一套清晰、可扩展的数据流规范，同时让团队成员的迁移成本尽可能低。

2.2 状态管理方案对比：从 useState 到完整状态库

当时我们对比了四条技术路线，每条都有自己的适用场景，我把关键差异整理成了表格：

这里面有个反直觉的点值得展开说说。很多人觉得 React 自带的 Context 既然能共享状态，为什么还要费劲引入 Redux？我在项目里实际对比过：Context 的更新机制是“从 Provider 到所有消费组件广播”，一旦 Provider 的 value 发生变化，所有 useContext 的组件都会重渲染，无论它们消费的是哪一部分数据。这意味着状态一多、消费组件一多，渲染压力会指数级上升。

而 Redux 这类方案通过订阅机制，让每个组件只关心自己关心的那部分状态，配合 useSelector 的选择器，可以精准控制重渲染范围。性能上的差异在老项目里会被放大——因为老项目往往已经存在大量不合理渲染，再叠加一个无差别广播机制，页面卡顿几乎是必然的。

但 Redux 进入老项目也有实际阻力：样板代码太多，团队成员容易陷入“复制粘贴”模式，写着写着就忘了自己在干什么。所以我们后来做了一层自定义封装，把重复逻辑收敛起来，这个封装过程我会在后面的实操章节详细展开。

2.3 关于“引入新依赖”这件事

每次给老项目引入新依赖，团队里总会有不同的声音——有人担心包体积增大影响首屏加载，有人担心生态维护不稳定。这些顾虑本身没问题，但需要量化看待。

当时我们算过一笔账：完整引入状态管理库及其配套工具，压缩后的体积大概在十几 KB 左右，对现有项目首屏体积的影响可以控制在 5% 以内。相比它带来的代码可维护性提升、定位问题的时间缩短，这点体积成本完全划算。而且我们开启了构建阶段的依赖分析，确认没有引入冗余子依赖，这个数字是可接受的。

我的原则是：引入新依赖之前，先回答三个问题——它解决的核心问题是否真实存在？团队的维护能力是否匹配？现有方案是否真的无法低成本替代？三个问题都得到肯定答案，再动手引入，不能为了“技术先进性”而堆依赖。

3. 核心改造过程与关键步骤复盘

3.1 从盘点现状开始：绘制状态地图

任何改造项目，第一步永远不是写代码，而是搞清楚现状。“rea”项目的第一周，我们没写一行业务代码，全部精力放在梳理既有页面的状态流向上。

具体做法是给每个页面/模块建立一张“状态清单”，要回答的问题包括：

1. 这个页面有哪些本地状态？它们被哪些子组件使用？
2. 哪些状态需要跨越多个页面共享？
3. 哪些状态被提升到父组件，但父组件本身并不消费它？
4. 状态之间有哪些联动关系？例如 A 状态变化是否要触发 B 状态的更新？

把这些信息全部记录下来后，就能画出一张全局状态依赖图（虽然当时用的是白板和可擦除马克笔，组合得比较“原始”，但信息量非常完整）。有了这张地图，哪些状态该收敛、哪些状态可以留在本地、哪些状态需要彻底重构，就一目了然了。

这里有一个非常重要的经验：改造前的盘点比改造本身更耗时，也更容易被低估。我们花在盘点上的时间占了整个项目周期的三分之一，后来证明这笔时间花得极其值得——因为没有地图就开始动工，大概率是在错误的方向上“勤快地制造混乱”。

3.2 设计统一的状态分层模型

盘点完成后，我们基于现状设计了一套三层状态模型，这是整个“rea”项目最核心的架构决策：

• UI 本地状态（Local UI State）：只服务于单个组件自身展示逻辑的状态，例如下拉框的展开/收起、Tab 的切换索引。这类状态坚决留在组件内部，用 useState 管理，绝不放进全局仓库。
• 跨组件共享状态（Shared State）：例如当前登录用户信息、主题配置、全局通知列表。这类状态是全局仓库的主体，但需要按业务模块做目录切割，避免一个仓库文件膨胀到几千行。
• 服务端缓存状态（Server Cache）：例如从后端接口拉取的数据列表。这类状态需要统一管理“请求中 / 成功 / 失败”三种状态，并配置缓存与失效策略。

这个分层模型的价值在于：它给团队一个明确的“决策入口”。工程师写新功能时，先自问一句“这个状态属于哪一层”，答案自然就出来了，不需要每次都来问架构师。长期维护中，这种清晰边界带来的效率提升远大于具体技术栈选择带来的差异。

确定分层后，我们开始动手搭建仓库结构。目录规划成这个样子：

src/ store/ modules/ # 按业务模块拆分的子仓库 user/ order/ settings/ index.ts # 仓库入口，负责组合所有子模块 hooks.ts # 自定义的接入 Hooks，减少样板代码 pages/ # 业务页面 ...

每个业务模块的仓库内部，我们统一采用三段式结构：state（状态定义）、actions（动作定义）、selectors（读取函数）。这样队友看到任一模块，都能立刻定位到对应的逻辑位置，不需要猜。

3.3 用自定义 Hook 消灭样板代码

上面提到 Redux 样板代码多，团队容易“无脑复制”，所以我们做了一件非常关键的事：封装自定义 Hooks，把接入细节收敛起来。

原本一个最基础的 Redux 接入代码长这样：

// 改造前：每个页面都要手写这样的样板逻辑 import React, { useEffect } from 'react'; import { connect } from 'react-redux'; import { fetchUserInfo } from '../../store/actions/user'; import { getUserName, getUserLoading } from '../../store/selectors/user'; const UserProfile = ({ userName, loading, fetchUserInfo }) => { useEffect(() => { fetchUserInfo(); }, []); return ( <div> {loading ? '加载中...' : `用户：${userName}`} </div> ); }; const mapStateToProps = (state) => ({ userName: getUserName(state), loading: getUserLoading(state), }); export default connect(mapStateToProps, { fetchUserInfo })(UserProfile);

这段代码的问题不在于“写起来长”，而在于每一个页面都要重复整个 connect 结构，逻辑分散在组件定义之外，可读性和可维护性都差。改造后，我们用自定义 Hook 封装成这样：

// 改造后：自定义 Hook 直接返回需要的数据和操作 import React, { useEffect } from 'react'; import { useUserStore } from '../../store/hooks'; const UserProfile = () => { const { userInfo, loading, fetchUserInfo } = useUserStore(); useEffect(() => { fetchUserInfo(); }, []); return ( <div> {loading ? '加载中...' : `用户：${userInfo.name}`} </div> ); };

对比非常直观：改造前 connect、mapStateToProps、selectors 这些“胶水代码”散落在组件文件里，改造后全部被封装进 useUserStore 这个 Hook。组件只需要声明“我要什么”，由 Hook 负责从仓库里精准读取。

这个封装还有一个隐藏收益：因为 Hook 内部封装了 useSelector 的选择逻辑，所有状态读取都经过同一层出入，后续如果需要加缓存、加埋点、加权限校验，只需要在 Hook 里改一处，所有业务组件同步生效，不需要全项目搜索替换。

这也是我想特别强调的一个观点：技术选型只是起点，真正的工程价值在于围绕选型建立一套适合团队的使用规范。再好的工具，如果没有配套封装与约定，用不了多久就会退化成一堆“只有原作者能看懂的拼图”。

3.4 存量代码的渐进式迁移策略

老项目改造最怕什么？最怕为了“一次性到位”开启一个巨大的改造工程，然后被业务节奏拖垮。我们当时采取的是“按模块、分批次”迁移策略，每一步都保证线上可回滚。

具体操作顺序如下：

第一批：只迁移最痛的 2 个页面。我们选择的依据有两条：一是跨组件状态共享最多的页面，二是开发人员反馈“改起来最想骂人”的页面。这两类页面往往是状态混乱的重灾区，迁移后收益最明显，能最快建立团队信心。

第二批：迁移全局共享状态。包括登录用户信息、全局配置、通知中心等。这些状态一旦落地全局仓库，所有页面都可以直接消费，就不再需要通过 props 层层透传了。

第三批：开始迁移服务端数据请求。把所有页面中直接写在 useEffect 里的数据请求，逐步收敛到统一的服务端缓存层。这一步要特别谨慎：每个接口的缓存策略需要单独确认，不能一把梭。

最后：清理所有废弃的状态提升。经过前面几轮迁移，很多“被迫提升”到父组件的状态已经不再需要了。我们要把这些状态重新降回子组件，恢复组件应有的独立性。

每个批次之间至少间隔两个完整迭代周期，确保上一批改动在线上稳定运行、没有任何回归问题后，才开始下一批。这个节奏看似慢，实际是最快的——因为省去了大量线上事故后的“救火时间”。

4. 状态管理时的性能陷阱与调试技巧

4.1 别让“重渲染”吃掉你的性能

做了状态管理统一之后，一个之前隐藏的问题会被立刻放大：重渲染。从前状态散落在各处时，每个组件只管自己的更新，影响范围有限。状态一旦集中到全局仓库，如果某个组件触发了全局状态更新，所有订阅了这个状态的组件都会进入更新流程。

我们曾遇到一个典型的性能劣化案例：一个列表页面，用户勾选一个筛选条件，整个页面白屏了将近一秒才刷新出来。用性能分析工具定位后，发现根源是某个组件的事件处理函数内部修改了一个全局状态，而这个全局状态被十几个不相关的组件订阅了。筛选条件本身只影响列表区域，但其他模块因为订阅了同一个状态源，被迫一起进入重渲染流程。

解决思路有两个方向，我们两种都用了：

方向一是优化订阅精度。之前使用 useSelector 时，有人习惯直接返回整个状态树：

// 性能反例：selector 返回了过多的数据，渲染时全部参与对比 const allState = useSelector((state) => state);

正确做法是让 selector 只返回组件真正关注的最小片段，例如：

// 性能正确示例：只订阅需要的字段 const filters = useSelector((state) => state.list.filters);

方向二是稳定组件引用。当我们向子组件传递回调函数时，如果这个函数在每次渲染中都重建，就会导致子组件即使数据没变也无法跳过渲染。正确做法是用 useCallback 缓存函数引用，同时配合 React.memo 让子组件实现“数据不变即不渲染”。

这一套组合拳打下来，那个页面从“筛选一次白屏一秒”优化到“几乎无感更新”，性能面板中的渲染耗时下降了 80% 以上。用数字说话，团队才真正相信状态分层与订阅粒度的价值。

4.2 开发阶段必开的调试三件套

我个人强烈建议，做这种状态管理改造的项目，开发阶段的调试工具一定要配齐：

第一，状态变更日志工具（Redux 生态自带的 DevTools 或类似的中间件）。它能把每一次 action 派发、状态 diff 结果直观展示出来。有了它，排查“这个数据怎么突然变了”这类问题时，不再需要逐个组件加 console.log。

第二，React 的性能分析器（React DevTools 里的 Profiler）。它可以直接录制一段操作，然后可视化地展示哪些组件发生了渲染、渲染耗时多少。我们就是靠它才精确定位到上面提到的重渲染问题。

第三，接口请求面板。因为服务端缓存收敛后，数据请求都走同一层，这个面板能帮助团队清晰看到每个接口的请求时机、依赖关系与缓存命中情况。

这三件套配置好之后，整个项目的“黑盒”程度大大降低，新成员接手一个模块时，也能快速通过调试工具搞清数据流动的全貌。

4.3 状态持久化：刷新页面不能丢数据

老项目里有个高频需求：页面上用户已经填好了几个筛选条件，一不小心刷新了页面，条件全部重置，用户就得重新填一遍。技术层面上，这类状态属于“跨会话保持状态”，不能只存在内存里，需要落盘。

我们在“rea”项目里统一封装了一个持久化模块，只对明确标记为“需要持久化”的状态开启本地存储备份。封装思路很简单：

// 持久化状态自定义 Hook 的核心逻辑（伪代码） function usePersistentState(storageKey, initialValue) { // 1. 从本地存储读取初始值，如果没有则使用传入的初始值 const [state, setState] = useState(() => { const saved = localStorage.getItem(storageKey); return saved ? JSON.parse(saved) : initialValue; }); // 2. 每次状态变化时，同步写入本地存储 useEffect(() => { localStorage.setItem(storageKey, JSON.stringify(state)); }, [state, storageKey]); return [state, setState]; }

这段逻辑本身不复杂，但有一个必须注意的坑：不是所有状态都适合持久化。如果状态里存了文件对象、临时会话令牌、频繁变化的实时数据，一股脑持久化会带来额外的读写开销，甚至埋下安全隐患。所以我们的规范是：持久化必须显式声明，默认不开启，宁可让用户偶尔重新填写，也不要让本地存储变成垃圾场。

5. 典型踩坑记录与排查思路

这个项目做下来，算不上惊心动魄，但零零碎碎踩过的坑确实不少。挑了三个最有代表性的记录下来，它们往往是新接手项目时最容易反复踩中的类型。

5.1 状态“幽灵”更新：某个变量莫名其妙就变了

现象：某张表单页，用户只在输入框里打字，页面角落里的一块统计数字也跟着变，而且变的数值完全看不懂逻辑。排查了一下午，最后发现原因特别“基础”：这个统计数字存储在全局仓库里，而一个不太起眼的输入框 onChange 事件里，不小心调用了统计模块的更新 action。因为两段代码在同一个文件中、位置离得比较近，之前某次改动时“顺手”多写了一行。

这个问题的解决方案有两个层面。技术层面，我们从此立了一条硬规矩：action 的命名必须能直接看出业务意图，且每个 action 只能出现在它对应的业务模块目录下。管理层面，我们开始要求所有涉及全局状态的改动必须提交清晰的变更说明，不能“夹带私货”。

类似的问题让我意识到：状态管理解决的不仅是技术问题，更是在倒逼团队建立代码变更的透明性。

5.2 组件明明订阅了状态，但页面就是没更新

这个坑更隐蔽。起因是一个同事在组件里对从仓库取出的数组对象做了原地修改（push 了一个新元素），组件内部虽然调用 setState 强行刷新了，但仓库里记录的引用没有变化。结果数据成功变了，但其他订阅同一个状态源、并且走正常渲染逻辑的组件全都感知不到——因为它们在对比引用时发现“还是那个数组”，直接跳过了渲染。

这是 JavaScript 引用类型的一个经典陷阱。在 React 状态管理场景下，它会暴露得更彻底。解决方法是严格遵守不可变数据原则，更新任何数组和对象时都返回新引用，例如：

// 错误示范：原地修改原始数据 const currentList = state.list; currentList.push(newItem); // 正确示范：创建新数组并完整替换 const newList = [...state.list, newItem];

为了降低心智负担，我们还在规范里明确了一条默认策略：凡是存在全局仓库里的数据，一律当作不可变数据对待。即使团队里有人不熟悉不可变数据的理念，只要记住“不要原地改数据，直接生成新数据替换”这一个原则，就能避开 90% 的同类问题。

5.3 新封装 Hook 导致的循环依赖问题

封装完成并推广使用后，有一次改动导致构建时出现“循环依赖”警告。定位后发现：业务组件 A 引入了业务组件 B，而 B 中封装的某个逻辑又反向引用了 A 模块中的常量定义。这个依赖环在状态管理接入之前是隐性的，因为两个组件彼此通过 props 传递状态，没有产生模块级的直接引用。状态收敛到全局仓库，并把读取逻辑抽到自定义 Hook 后，原本隐性的依赖环变成了模块级的显式引用。

解决的思路是调整模块边界，把公共类型定义和纯函数抽到一个独立的基础模块中，让 A 和 B 都从基础模块引用需要的东西，切断反向依赖链。

这个坑提醒我们：设计自定义 Hook 的归属时，不能只看“哪个页面在用”，还要审视依赖图的走向。如果多个页面共用同一个 Hook，它应该被放在仓库目录或专门的公用目录，而不是放在某一个业务页面内部。

6. 改造后的项目管理规范沉淀

代码改完之后，如果只留下一堆改动文件，那这个项目只能算成功了一半。真正让改造效果长期稳定的，是配套的管理规范。我们在“rea”项目收尾时，沉淀了一套团队约定，这里分享其中最核心的四条。

第一条：仓库目录与业务模块一一对应。不允许在全局仓库里出现一个谁都说不清属于哪个业务模块的“公共杂物箱”目录。哪怕某段逻辑确实被多个模块共用，也要显式定义归属，由归属模块负责维护对外接口。

第二条：状态读取必须通过自定义 Hook。任何业务组件不允许直接访问全局仓库的原始对象，必须经自定义 Hook 中转。这条规范可以保证后续的权限校验、埋点、缓存逻辑有统一的纳入位置。

第三条：新增全局状态必须过评审。一旦全局仓库新增一个状态，我们要求修改者明确回答三个问题：是否有其他模块真正需要共享它？能否放到服务端缓存层？是否可以考虑组件本地状态？三个问题都没通过，则不允许轻易加入全局仓库。这个机制的初衷是控制全局状态的膨胀，保持仓库“少而精”。

第四条：所有跨模块数据流动必须配变更记录。这种记录不需要长篇大论，只要说清楚“为什么这个状态要被其他模块使用、哪里在消费它”即可。这个习惯极大降低了后人的接手成本，尤其是在团队人员流动的时候。

写到这里，项目本身的核心内容基本聊完了。回过头看，“rea”这个项目真正教会我的东西，不是某个具体状态管理库的用法，而是面对一个“烂摊子”时如何保持清醒：先绘制地图，再做选择，然后小步快跑地迭代，最后把经验固化成团队规范。技术方案永远可以争论，但清晰的边界、渐进式的策略、对工程细节的敬畏，才是一个改造项目能平稳落地的根本保障。