企业官网建设流程全解析

对“rea”这个词，我第一反应是 React。这几年做前端，跟 React 生态打交道的时间占了大部分，从最开始用 Class 组件写业务，到后来全面拥抱 Hooks，再到把服务端渲染、微前端、性能优化这些硬骨头一个个啃下来，“rea”这个缩写其实挺能代表 React 技术栈在实际项目里的地位——它不只是一个 UI 库，更是一整套解决复杂前端工程问题的思路。

这篇文章我不打算讲那种“Hello World”级别的入门教程，而是想从一个实际落地的跨端项目出发，聊聊 React 技术栈在真实业务里怎么选型、怎么组织代码、怎么排查那些让人掉头发的疑难杂症。如果你正在用 React 做项目，或者正打算从零搭建一个中大型前端应用，这篇文章应该能给你一些直接能抄作业的经验。

1. 项目整体设计与思路拆解

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

我接到的这个模拟项目X，要求做一个跨平台的管理系统，支持桌面端和移动端访问，核心功能包括数据看板、工单流转、权限管理和实时消息提醒。技术选型的时候，团队内部有过争执，有人建议用传统多页面方案，有人建议引入低代码平台，但最后我们还是敲定了 React。

理由其实很实在。React 的组件化模型特别适合这种业务复杂、界面元素复用度高的管理系统。你看，光是表格、表单、弹窗、图表，这些在管理系统里几乎每个页面都有，如果用传统模板引擎，每个页面都要复制粘贴一大段 HTML 和对应的 JS 逻辑，维护成本直接爆炸。而 React 可以把这些拆成独立组件，一次编写，处处引用。

另一个关键因素是 React 的生态足够成熟。路由有 React Router，状态管理有 Redux、Zustand，UI 组件库有 Ant Design、Material UI，数据请求有 React Query、SWR，几乎你能想到的每一种业务场景，社区里都已经有经过大量项目验证的方案。这意味着我们不需要从零造轮子，而是把成熟方案组合起来，风险可控，开发效率也高。

至于跨端需求，React 本身是平台无关的——一套代码通过不同的渲染器可以运行在 Web、移动端原生环境和桌面端。虽然这个项目最终只做了 Web 端，但选型时考虑到未来可能要做移动端 App，React 技术栈的延续性是最平滑的。

1.2 整体技术架构的选型逻辑

核心架构分成五层：

• UI 层：React 18 + TypeScript，组件库选 Ant Design
• 状态层：服务端状态用 React Query，客户端全局状态用 Zustand
• 路由层：React Router v6，按业务模块做代码分割
• 样式层：CSS Modules 配合设计系统变量
• 工程层：Vite 构建 + ESLint + Prettier + Jest 测试

这里面有几个选型是反复权衡过的。

先说 TypeScript。很多人觉得写 TS 麻烦，多写一堆类型定义，拖慢开发速度。但项目规模大了之后，TS 的价值会越来越明显。管理系统通常涉及大量的数据模型，用户、订单、工单、权限这些实体之间的关系复杂，如果没有类型约束，改动一个接口字段可能满项目都是报错，而且很多错误是运行时才能发现的。用 TS 之后，很多低级错误在编译期就被拦截了，重构的胆子也大了很多。

再说 Zustand 和 Redux 的选择。Redux 虽然经典，但样板代码实在太多，写一个 action 要定义 action type、action creator、reducer 分支，流程繁琐。Zustand 足够轻量，API 设计贴近 Hooks 风格，在 React 18 的并发特性下表现也稳定。特别是它不需要 Context Provider 包裹整个应用，避免了不必要的重渲染，这对管理系统的性能是实打实的帮助。

React Query 解决的是服务端状态的问题。管理系统里大量操作是数据的增删改查，手动管理 loading、error、缓存这些逻辑很容易出 bug，而且代码极其无聊。React Query 把这些逻辑抽象掉，自带缓存、重试、失效刷新、乐观更新，让开发者可以专注于业务本身。

1.3 这套方案的优势和避开的坑

这套架构跑下来，最大的体会是边界清晰。每一层只负责自己的事情，UI 组件不直接发请求，状态管理不关心组件渲染，路由只负责分发。团队协作的时候，大家不用互相猜代码意图，新人上手也快。

另外一个隐性优势是调试体验。Zustand 的 devtools 插件、React Query 的开发者工具、React DevTools 的 Profiler，三件套基本上覆盖了从数据流到渲染性能的所有追踪需求。对比之前用过的某些一体化框架，出问题时经常只能靠 console.log 盲猜，这次的体验简直是天壤之别。

当然也有过犹豫。比如要不要用 Next.js 做服务端渲染。考虑再三，这个管理系统是内部工具型应用，对 SEO 没有要求，首屏加载时间虽然重要，但不至于到非要 SSR 不可的程度，而且 SSR 会带来服务端运维成本和更复杂的部署流程，权衡下来感觉不划算，最终选择了纯客户端渲染加路由级代码分割。

2. 核心细节解析与实操要点

2.1 状态管理的分层策略

状态管理的第一个原则：不要把所有的状态都放到全局 Store 里。

我把状态分成三类：

• 服务端状态：数据来自后端 API，需要缓存和失效管理——交给 React Query
• 全局客户端状态：登录用户信息、主题配置、权限标识——交给 Zustand
• 局部组件状态：弹窗开关、表单值、下拉框选中项——老老实实放 useState 和 useReducer

这个分层策略最大的作用，是避免 Zustand Store 变成一个装垃圾的大仓库。很多人写代码很容易图省事，什么东西都想往全局 Store 里放，结果一个 Store 几百个字段，任何地方改了一个字段，所有监听这个 Store 的组件都要检查是不是需要重新渲染——性能问题就是这么出现的。

以这个管理系统为例，Zustand 里只放了这么几个东西：

interface GlobalState { userInfo: UserInfo | null permissions: string[] themeMode: 'light' | 'dark' sidebarCollapsed: boolean setUserInfo: (user: UserInfo | null) => void setPermissions: (perms: string[]) => void toggleTheme: () => void toggleSidebar: () => void }

你看，这里面没有任何业务列表数据，全是跟整个应用生命周期相关的全局信息。业务数据全部走 React Query 的路由级缓存。这样 Zustand 的状态变化频率极低，几乎不会引发多余的组件渲染。

2.2 组件划分的粒度把控

组件划分粒度是个经验活，太粗了复用性差，太细了过度设计。我的原则是“按业务能力划分，不以 DOM 大小论英雄”。

比如一个“工单详情”页面，我不会按照“头部区域”“中部区域”“底部区域”这种纯展示结构来拆组件，而是按照“工单基本信息”“流转记录时间线”“关联附件列表”“操作按钮组”这种业务模块来拆分。每个业务模块自包含数据获取逻辑和 UI 展示，这样模块之间可以独立修改、独立测试、独立复用。

一个小技巧：在组件内部通过自定义 Hook 封装数据请求逻辑。比如：

function useWorkOrderDetail(orderId: string) { return useQuery({ queryKey: ['workOrder', orderId], queryFn: () => fetchWorkOrderDetail(orderId), staleTime: 5 * 60 * 1000, }) }

组件文件里只处理渲染逻辑，数据逻辑全在 Hook 里。换接口、加缓存策略、做乐观更新，都只改 Hook，完全不碰组件代码。这是我特别推荐的一种组织方式，代码会变得非常干净。

2.3 权限控制的实现思路

管理系统的权限控制是个绕不开的坎。我们把权限分成了两个维度：路由级权限和按钮级权限。

路由级权限在 React Router v6 里通过一个封装好的<AuthGuard>组件实现。用户登录后，后端返回一个权限码数组，我们根据权限码动态生成路由表，没有权限的路由直接不注册，也就无法访问：

const routeMap = { dashboard: { element: <Dashboard />, permission: 'dashboard.view' }, workOrder: { element: <WorkOrder />, permission: 'workorder.view' }, userManagement: { element: <UserManagement />, permission: 'user.manage' }, } const accessibleRoutes = Object.entries(routeMap) .filter(([, config]) => hasPermission(config.permission)) .map(([path, config]) => ({ path, element: config.element }))

按钮级权限通过一个自定义指令风格的组件控制，没有权限时不渲染按钮：

function CanAccess({ permission, children }: { permission: string, children: React.ReactNode }) { const { permissions } = useGlobalStore() return hasPermission(permissions, permission) ? <>{children}</> : null }

这里有个容易踩坑的点：前端权限控制只是用户体验层面的隐藏，真正的安全校验必须在后端做。前端控制做到“友好”，后端校验做到“可靠”，两条腿走路才安全。

2.4 样式方案与主题切换

样式方案简要说明一下用了 CSS Modules。它在编译阶段给类名加上局部哈希，避免全局污染，又不会像 CSS-in-JS 那样带来运行时性能开销。

主题切换则用 CSS 变量配合 Ant Design 的 ConfigProvider 实现。在:root下定义语义化的设计变量：

:root { --color-primary: #1677ff; --color-bg: #ffffff; --color-text: #1f1f1f; } [data-theme='dark'] { --color-primary: #4d9fff; --color-bg: #141414; --color-text: #e0e0e0; }

Zustand 里的themeMode变化后，自动给document.documentElement打上>npm create vite@latest rea-project -- --template react-ts cd rea-project npm install

紧接着装一堆必要的依赖：

npm install react-router-dom zustand @tanstack/react-query antd axios dayjs npm install -D eslint prettier @typescript-eslint/parser @typescript-eslint/eslint-plugin

Vite 在开发体验上的确比老一代的 Webpack 舒服太多，依赖预构建、按需编译、热更新秒级响应，起步几乎没有等待感。构建速度对于中大型项目来说，后期也能节省不少工时。

后端接口的统一封装我单独写了一个模块，基于 axios 实例统一处理 baseURL、token 注入、错误码拦截：

const http = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, timeout: 10000, }) http.interceptors.request.use((config) => { const token = useGlobalStore.getState().userInfo?.token if (token) { config.headers.Authorization = `Bearer ${token}` } return config }) http.interceptors.response.use( (response) => { if (response.data.code !== 0) { message.error(response.data.message) return Promise.reject(new Error(response.data.message)) } return response.data.data }, (error) => { if (error.response?.status === 401) { // 清空用户信息，跳转登录页 useGlobalStore.getState().setUserInfo(null) window.location.href = '/login' } return Promise.reject(error) } )

3.2 搭建可插拔的路由框架

路由骨架直接决定项目的拓展性。我把路由拆成了静态路由和动态路由两部分。静态路由是登录页、404页这类所有用户都能访问的页面；动态路由是根据登录用户权限生成的路由数组。

React Router v6 里的useRoutes这个 Hook 让我摆脱了以前Switch+Route的繁琐写法：

function AppRoutes() { const routes = useMemo(() => buildAccessibleRoutes(), [permissions]) return useRoutes([ { path: '/login', element: <LoginPage /> }, { path: '/', element: <MainLayout />, children: routes }, { path: '*', element: <NotFoundPage /> }, ]) }

每个业务模块的路由都做懒加载。懒加载是这里最关键的优化手段，不然首屏 bundle 会越来越大——做过前端都应该清楚，bundle 大小和首屏加载速度直接挂钩：

const WorkOrderPage = lazy(() => import('@/pages/WorkOrder'))

路由层面还做了一个“路由切换进度条”的效果，模仿某个知名后台框架的体验：在useEffect里监听路由变化，如果组件懒加载超过 200ms 就显示一个顶部进度条。这个小东西很提升使用体感，实现也不复杂，花了不到半天。

3.3 数据请求与管理的最佳实践

React Query 里一个重要的设计是保持queryKey的统一规划。我习惯把一个领域的查询 key 集中定义在一个常量表里：

export const queryKeys = { workOrder: { detail: (id: string) => ['workOrder', 'detail', id], list: (params: WorkOrderQueryParams) => ['workOrder', 'list', params], }, user: { list: (params: UserQueryParams) => ['user', 'list', params], }, }

这样使用时语义清晰，而且任何地方需要让某个缓存失效时，可以通过queryClient.invalidateQueries({ queryKey: ['workOrder'] })精确地控制失效范围，不会误伤其他数据。

做表单提交时，React Query 的useMutation配合乐观更新是一个非常实用的技巧。以“更新工单状态”为例，先展示给用户 UI 已经更新，再发后端请求：

const mutation = useMutation({ mutationFn: updateWorkOrderStatus, onMutate: async (newStatus) => { await queryClient.cancelQueries({ queryKey: ['workOrder', orderId] }) const previousData = queryClient.getQueryData(['workOrder', orderId]) queryClient.setQueryData(['workOrder', orderId], (old) => ({ ...old, status: newStatus, })) return { previousData } }, onError: (_err, _vars, context) => { queryClient.setQueryData(['workOrder', orderId], context?.previousData) }, onSettled: () => { queryClient.invalidateQueries({ queryKey: ['workOrder'] }) }, })

这套模式让整个交互体验非常丝滑，后端返回失败时自动回滚。

3.4 关键页面的实现复盘

数据看板页面是这次项目的重头戏。页面里有四个统计卡片、一个趋势折线图、一个分类饼图、一个实时动态列表。我的做法是：统计卡片的数据用useQuery并行抓取，但如果一个接口挂了不能影响其他模块。

并行请求用Promise.allSettled包了一层，这样即使某个接口异常，页面其他区域依然能正常展示。这也是一个从实际项目中总结出来的思路：不要把鸡蛋放在一个篮子里，单一接口的错误不应当导致整个页面白屏。

工单列表页则是典型的查、筛、分页场景。搜索条件我用useState保存，通过useQuery的queryKey关联筛选条件，每次筛选变化都会自动触发请求，配合keepPreviousData: true，切换分页时上一页数据会保留展示，避免加载闪烁。

useQuery({ queryKey: queryKeys.workOrder.list(params), queryFn: () => fetchWorkOrderList(params), keepPreviousData: true, })

这都是 React Query 的现成能力，但用好了以后用户体验确实上了一个档次。

实时消息提醒模块开始时用了 WebSocket，后来发现后端同学提供的推送频率不高，数据量也不大，换成轮询反而更稳定，每 15 秒拉一次未读消息，加上refetchInterval配置：

useQuery({ queryKey: ['unreadMessages'], queryFn: fetchUnreadMessages, refetchInterval: 15000, })

3.5 构建配置与部署细节

构建阶段做了几件关键事情。

第一是拆包。Vite 默认会把所有依赖和业务代码打到一个 chunk 里，虽然现代浏览器支持 HTTP/2，但首屏解析一个大文件的时间仍然不理想。我在vite.config.ts里用manualChunks手动拆分：

build: { rollupOptions: { output: { manualChunks: { 'react-vendor': ['react', 'react-dom', 'react-router-dom'], 'antd-vendor': ['antd', '@ant-design/icons'], 'chart-vendor': ['echarts'], }, }, }, }

这样公共依赖单独缓存，浏览器下次加载时命中的概率更高，整体加载体验更好。

第二是移除调试代码。生产构建时通过环境变量判断，把console.log和debugger语句剔除，保证生产环境日志干净。

第三是静态资源走 CDN 配置。项目部署后，图片和字体等静态资源加上了内容哈希指纹，配合 CDN 缓存，回源请求数量大幅下降。

4. 常见问题与排查技巧实录

4.1 组件无限重渲染的噩梦

开发中遇到过最头疼的问题之一，是某页面一打开就卡死，CPU 直接飙满。排查后发现问题出在useEffect的依赖数组里放了一个未记忆化的对象。

问题伪代码如下：

const config = { pageSize: 10, sortBy: 'createTime' } useEffect(() => { fetchData(config) }, [config])

由于config是每次渲染都新建的对象，引用地址每次都不同，useEffect的依赖比较永远不相等，导致重复请求 -> 更新数据 -> 重新渲染 -> 重新创建 config -> 重复请求……直接死循环。

从这次的问题我总结出一个教训：所有用于useEffect依赖的引用类型值，都要用useMemo或useCallback稳定引用，或者直接把基本类型的参数一个一个列出来。不能偷懒传一个对象。

4.2 React Query 缓存未失效导致的数据陈旧

使用 React Query 之后，“数据不刷新”是容易被忽视的问题。有一次测试反馈说修改了工单备注后，详情页还是显示旧内容，排查发现我忘记在修改备注的mutation里调用invalidateQueries。

这个坑说白了就是：React Query 默认缓存不会自动知道你的后端数据变了，你得主动告诉它“这个数据过时了”。添加一行失效刷新之后问题就解决了。

经验是在每次mutation成功的回调里，把关联查询全部失效。如果你发现自己频繁忘了，可以在mutation的onSettled里统一处理，不要只依赖单个调用的onSuccess。

4.3 样式主题切换后的残留问题

主题切换在刚开始的实现中踩过一个坑。Ant Design 5 的ConfigProvider默认通过cssVar: true启用 CSS 变量模式，但自定义的组件如果用了自己的定色值，切到深色模式时就会出现“一半深色一半浅色”的割裂感。

排查后发现是某些组件的行内样式直接写死了颜色，不经过 CSS 变量。后来我专门做了一个代码扫描，把所有写死的十六进制颜色都替换成了 CSS 变量引用，并规定后续新增代码必须使用设计系统的变量，代码审查环节会专门检查这一点。

4.4 路由懒加载导致的首屏白屏

路由懒加载虽然能缩减 bundle 体积，但也会引入一个体验问题：网络较慢时，切换路由会有一段白屏时间。后来通过加了一个“全局加载状态”组件解决：在Suspense的fallback里挂一个和导航栏一体的顶部进度条。这样用户明确感知到“正在加载”，而不是“卡死了”。

<Route path="/workOrder" element={ <Suspense fallback={<PageLoading />}> <WorkOrderPage /> </Suspense> } />

4.5 排查技巧速查表

4.6 调试技巧

React Query DevTools 是排查缓存问题的最强工具。安装接入只需要三行：

import { ReactQueryDevtools } from '@tanstack/react-query-devtools' // 开发环境下挂载 <ReactQueryDevtools initialIsOpen={false} />

有了它，你能直观看到每个查询的缓存状态、最后更新时间、被哪些组件订阅。这在追查“为什么页面数据不新”这种问题时效率极高，比反复查接口日志舒服多了。

4.7 性能优化实录

项目后期做了一次性能体检，用 Lighthouse 测出来的首屏性能分数从 68 提到了 90 以上，主要做了三件事。

第一件事，减少首屏不必要的 JS。利用React.lazy把看板页面的图表库单独拆出去，因为图表库（体积不小）在首屏是不需要的，等用户滚动到图表区域再加载即可。这个简单操作让首屏 JS 总量减少了约 30%。

第二件事，图片懒加载。管理系统的列表页有很多上传的截图附件，直接用<img loading="lazy" />原生属性就解决了，没有任何额外成本。

第三件事，优化大列表渲染。工单列表一页 50 条数据，每条数据里有富文本内容，渲染时明显卡顿。后来对列表项做了React.memo，并为富文本内容做了缓存，滚动体验立刻好了很多。

5. 从进阶视角再看“rea”这个项目

5.1 团队协作规范的沉淀

做完这个项目，我们沉淀了一套适合中小型前端团队的协作规范，核心是三份文档：组件命名与目录结构规范、状态管理使用规范、代码审查检查清单。

组件命名上我特别重视路径即身份的命名方式，比如src/components/WorkOrder/StatusTag.tsx，只看路径就知道它是工单域下的状态标签组件。不用src/components/Common/StatusTag.tsx，因为 Common 是垃圾场，什么都能往里丢，最终什么都找不到。

状态管理使用规范里明确列了三条红线：

• 禁止在全局 Store 里存放接口返回的业务列表数据
• 禁止在组件里直接用store.dispatch以外的副作用操作全局状态
• 全局 Store 更新时注意不可变更新方式，没有做浅层比较的 Store 更新会引发全部订阅者重渲染

代码审查清单则是保护项目质量的最低防线：有没有写死颜色值、有没有未使用的 imports、有没有绕过权限校验的直连接口调用、有没有 useEffect 依赖数组里引用了外部对象。

5.2 未来的扩展思路

这个项目后续如果要演进，方向上我考虑了三条路。

第一条是引入微前端架构。如果未来多个团队要并行开发不同业务线，微前端能干这事，把大应用拆成若干个独立部署、独立升级的子应用。目前项目还不到需要拆分的地步，真到了那份上，我倾向用 qiankun 之类的成熟框架，自研微前端加载器看起来很美，但成本真的很吓人。

第二条是迁移部分页面到服务端渲染。如果业务开始对 SEO 或首屏秒开有要求，可以挑选核心页面用 Next.js 重构，而不是全部推翻重来。渐进式迁移才是低风险路径。

第三条是接入单元测试和端到端测试的完整流水线。目前测试覆盖率只有核心工具函数和几个关键组件，后续应该把工单流转这条主干链路用 Playwright 跑一遍端到端，避免每次发版都要人肉回归。

5.3 踩过坑后的几点体感

整个项目做到最后，回头看不只是技术层面的收获。有些经验是写代码写不出来，非得在项目里踩了坑才能体会到的。

一是对“约定大于配置”的理解。架构定的规范和约定越明确，团队成员越多，沟通成本节省得越明显。特别是封装好了数据请求、权限判断、路由生成这些基建后，写业务页面的同学几乎只需要关心 UI 交互本身。

二是对“过早优化”的克制。一开始有几个同事提议马上引入测试覆盖率门槛和 CI 流水线，但项目前期需求变化极快，早期设计大量调整时，如果把时间大量消耗在维护测试上，反而拖慢迭代。后来在核心链路稳定之后再把测试补上，成本低得多，价值也更高。

三是对技术选型的敬畏。回头看 Zustand 可能不是每个项目的首选，但在我们的场景下确实够用、好用。技术选型没有什么一招鲜，核心思路始终是：结合团队实际情况权衡投入产出比，选择学习成本适中、生态成熟、退路清晰的方案。很多时候，不用最时髦的框架，反而能走得最远。

React 这套生态之丰富，给了开发者很多自由，但也正因为自由空间大，更容易走偏。一个项目的成功，往往不在于用了什么新技术，而在于把已经足够好的技术用出了体系、用出了规范。这大概就是我在这个项目里最深的感受吧。