看到标题“rea”，很多做前端的朋友应该都不陌生，这就是 React 在社区里、在代码仓库里最常用的简称。但正是因为太常见了，反而容易让人忽略它背后那一整套完整的前端工程化思维。这篇内容我不打算讲官方文档上已有的 API 清单，而是想换个角度，从“拿到一个项目标题、需求只有一句话”时，一个老手是怎么思考、怎么拆解、怎么一步步把页面搭起来、把状态管好、把性能抠出来、最后踩坑排雷的完整过程。这些经验大多来自实际开发中的复盘，希望对正在用 React 做项目的你有一点参考价值。无论你是刚接触 React 的初学者，还是已经用了两三年但总觉得在“照着文档写组件”的开发，这篇文章都会有点用处。我会从设计思路、工程化选型、核心实现，再到问题排查，完整过一遍 React 项目的落地流程。每一条都不会是空泛的理论，而是可以照着做、照着调的东西。1. 拿到需求别急着写代码：先理清组件边界和状态模型很多初学者拿到项目需求，第一反应是“这个页面长这样，我来照着写”。框架本身确实允许你这么快开始，但实际项目里，这种做法的返工率极高。React 的核心理念是“以组件为单位构建 UI”，但组件怎么拆、状态放哪儿、数据怎么流动，这些决策比写 JSX 本身重要得多。1.1 组件拆分：按职责而不是按视觉分区我见过不少项目，组件目录是照着设计稿的视觉区块建的：一个 Header 组件、一个 Sidebar 组件、一个 Content 组件。这种方式的直观问题在于，视觉区块和业务职责往往并不一致。更好的做法是按业务职责和复用粒度来拆。比如一个电商后台的订单列表页，按照视觉区块你会拆成：顶部筛选区、表格区、分页器、弹窗详情。但按职责来拆，应该是：OrderFilter（负责筛选条件状态）、OrderTable（负责列表数据和列配置）、OrderDetailDialog（负责详情展示和操作交互）、Pagination（通用组件）。这样拆的好处是每个组件的 props 和 state 都相对清晰，改动一个业务逻辑时不需要在多个“视觉区块”里来回找。判断一个组件职责是否合理，有一个很朴素的标准：如果你要给这个组件写一段“它负责什么”的描述，这段描述是否超过两句话。超过两句话，大概率这个组件管得太多了，应该再拆。1.2 状态模型设计：哪些放本地 state，哪些放全局 store状态管理是 React 项目里的争议重灾区。我见过一个中型项目把所有的数据都放进全局 store，结果组件刷新、内存占用、调试成本全线告急；也见过相反的情况，连登录用户信息都放在组件本地 state 里，导致刷新页面就丢状态。我的经验是分三挡来决策：第一挡，组件本地 state：只影响当前组件 UI 的临时状态，比如弹窗开合、选项卡索引、表单某个字段的临时值。这类状态用useState就好，根本不需要全局化。第二挡，跨组件共享但不需要持久化的数据：比如多个兄弟组件都要读某个筛选条件，或者某个计算结果被多个地方复用。这时候用useContext配合useReducer或者直接提升 state 到最近的公共父组件，已经足够。第三挡，需要跨页面共享、涉及复杂数据交互、或者需要缓存的服务端数据：这才需要真正的全局 store。一个很容易被忽略的原则是：能放本地的就不要放全局，能放近的不要放远的。全局状态越少，项目的可维护性越高。这个原则没有变化，任何时候做 React 项目都适用，因为全局数据一多，必然面临“这个状态是从哪来、要被谁改、当前是什么值”的三连拷问。1.3 从数据流反推组件层级确定状态模型之后，再顺着数据流把组件层级排出来，比先画视觉再想数据要顺得多。核心思路是：找一个状态需要被哪些组件读取，找到这些组件的最近公共父组件，让状态待在父组件里，通过 props 向下传递。举一个实际例子：筛选条件区域和一个结果列表区域其实是联动的。筛选条件的某个值变更，列表需要重新请求并展示。最合理的结构是把筛选条件和列表数据同时放在它们共同的父组件里，父组件持有筛选条件的 state 和列表数据的 state，传递一个onFilterChange给筛选组件，传递data给列表组件。这个结构简单清晰，两个子组件完全可以独立复用。2. 工程化选型有讲究：脚手架、路由、请求层和样式方案一个 React 项目的工程化选型直接决定了项目的开发体验和长期可维护性。这部分我不会推荐“唯一正确答案”，因为不同的团队风格、项目周期、部署环境，正确答案不一样。我重点是讲明白每个选型背后的考量，这样你拿到自己的项目时能做出适合自己的判断。2.1 初始化方式：为什么你仍然需要一个构建工具现在初始化 React 项目最主流的命令已经不是手动配置 Webpack 了。社区推荐的方式是用官方脚手架或社区维护的起步模板，它们把构建、转译、热更新、代码规范都集成好了。我在实际项目里更看重的是模板对 TypeScript 的支持是否开箱即用，因为类型系统在项目规模上去之后，带来的收益是实实在在的。如果一个模板还要你自己去配置 tsconfig、编辑器和构建插件之间的集成，那我建议换一个模板，省下的时间用来写业务逻辑更划算。2.2 路由设计：不是加一个库那么简单React 应用大多是单页富应用，路由库是很基础的一层。选路由方案时，我特别关注三点：是否支持嵌套路由对应的组件嵌套结构。因为实际业务里，一个主布局下面往往有多级页面，路由的嵌套结构如果能和组件树的结构一一对应，理解成本会大幅降低。是否支持动态路由和按需加载。大型项目的首屏性能很大程度依赖路由级代码分割。路由参数的类型安全。路由设计上有一个容易被忽略的细节：把路由配置收敛到一个独立文件里集中管理。哪怕刚开始只有两三个页面，也建议这么做。因为后续增加页面、权限控制、面包屑导航、页面标题设置，都可以依托这一份配置来实现。我自己习惯在每个页面配置里带上title、icon、permission等元信息字段，后续做导航菜单和权限拦截时就能直接用，不用额外维护一份重复的菜单配置文件。2.3 数据请求层：fetch 封装、缓存与请求状态处理数据请求层是 React 项目里最容易写乱的部分。我见过那种在组件里到处写 fetch 然后 .then 回调，最后全项目布满了 loading 状态的方式——不是说不能用，但项目一复杂就很容易乱。更稳妥的方式是封装一个统一的请求客户端，基于浏览器原生 fetch 或者基于 XMLHttpRequest 的库封一层，统一处理：请求头的注入（比如认证 token）。响应拦截（比如统一处理后端返回的 code，data，message 结构）。错误处理（网络错误、业务错误、登录过期跳转登录页）。重复请求取消。请求状态的管理我建议用自定义 Hook 的方式收敛，比如useFetchList、useMutation这类对外暴露data、loading、error、refresh等方法的封装。组件只用关心自己的数据从哪来，请求被打到哪里、怎么重试、取消请求这些问题，统一封装在前端。2.4 样式方案：CSS Modules 还是 CSS-in-JS开发时这个选择的优先级很高，跟前端项目的兼容和团队协作关系很大。我个人的经验是：对大多数中小型项目，CSS Modules 通常是最稳妥的方案，因为它不引入额外的运行时，样式的局部作用域可以避免写长选择器互相覆盖，而且写起来就是普通 CSS，团队成员上手成本很低。CSS-in-JS 方案的优点是样式和逻辑在同一个文件里，动态样式处理很灵活。但运行时开销和调试成本还是现实问题。如果是组件库或需要大量动态样式的项目，CSS-in-JS 更有优势，具体只能看团队的项目情况定，没有放之四海皆准的标准答案。3. 核心细节解析：Hooks 落地的几个硬核技巧React 16.8 之后，函数组件加 Hooks 已经是绝对的主流写法。但 Hooks 的粒度怎么控制、依赖数组怎么填、副作用怎么处理，才是从“会用”到“用得好”的分水岭。3.1 useState 的惰性初始化和函数式更新useState有个容易被忽略的细节：初始值如果是通过复杂计算得到的，应该传一个函数进去，让它只在组件首次渲染时执行一次，而不是每次渲染都重复算。这个优化在初始值是数组、要经过 map/filter 等遍历计算时，收益是肉眼可见的。另一个重要细节是依赖前一个状态更新时，应该用函数式更新的形式。看这个场景：const [count, setCount] = useState(0); // 不推荐：当多次连续调用 setCount 时会基于同一个旧值计算 setCount(count + 1); setCount(count + 1); // 推荐：每次都是基于最新值计算 setCount(prev => prev + 1);虽然 React 的批处理机制能缓解不少问题，但在复杂交互下（比如快速点击、异步回调中更新），函数式更新是更稳的写法。3.2 useEffect 的依赖数组：不是随便填的useEffect的依赖数组是新手最容易踩的坑。不填依赖数组（每次渲染都执行）、填空数组（只在挂载时执行一次）、填部分依赖（可能漏掉某个变量），三种情况各自都有问题。最实用的原则：依赖数组里应该列出 effect 中引用的每一个响应式值。如果你发现依赖数组里东西太多导致 effect 频繁触发，正确的做法不是强行忽略依赖，而是重新审视代码结构，把多个职责拆开。一个 effect 只做一件事，依赖就会更清晰。还有一个经常踩的坑是：在 effect 里使用了某个 props 或 state，但依赖数组里漏掉了它。结果就是 effect 执行时用的还是旧值，这个问题排查起来很隐蔽，因为不是每次都会复现。所以我现在写代码有个习惯，写完之后会先看一眼 effect 里引用了哪些外部变量，再对照依赖数组确认它们是否都列出来了。3.3 useMemo 和 useCallback：为性能服务，但别滥用很多开发者一听说性能优化，就开始到处塞useMemo和useCallback。但这两个 API 是有代价的，它们本身也是有一定开销的：需要额外的内存保存依赖、需要比对依赖是否变化。如果一个计算本身很轻量，或者一个函数本身很稳定，就不值得用它们去包一层。性能优化第一步永远是分析真正的瓶颈，而不是凭直觉盲优化。合理的场景是：useMemo：复杂数据转换、列表过滤排序、大对象深度对比等。useCallback：需要传递给被React.memo包裹的子组件的函数，或者作为 effect 依赖的函数。判断取舍的一个技巧是：先把代码写清楚，性能测试发现确实有问题了，再针对性地加记忆化。盲目加 useMemo 会让代码可读性下降，而且依赖数组本身也是一个心智负担。3.4 自定义 Hooks：把逻辑抽到组件之外，但不要把组件拆得太碎自定义 Hooks 是 React 工程化项目里提升复用度的最佳手段之一。比如一个有“输入内容并防抖请求”需求的搜索框，通常的做法是直接写到组件里，但更合理的做法是把它抽成useDebouncedSearch。这样搜索逻辑的细节被藏起来，组件里只需要关心要不要显示 loading，以及拿到的列表数据。不过自定义 Hooks 也有一个边界问题：不要把所有东西都拆成 Hooks。如果一个 Hook 只被一个组件使用，而且里面的逻辑很简单，那抽出来反而增加跳转成本。先写在组件里，发现有一大坨逻辑导致组件难以阅读时，再抽出去，这样的节奏最自然。4. 实操过程：从零到一搭建一个 React 项目（完整步骤演练）这一部分我用一个模拟项目 X（企业内部的数据分析看板前端）为例，带你完整走一遍从初始化到核心功能实现的流程。这个项目规模适中，包含了列表页、详情页、表单提交、数据可视化图表展示，非常适合用来演示 React 工程化的完整套路。4.1 项目初始化和目录结构规划第1步是用你选定的脚手架初始化项目，然后在项目根目录下规划目录结构。我的习惯是按下图这样划分：src/ ├── api/ # 接口请求函数 ├── assets/ # 静态资源 ├── components/ # 通用业务组件 ├── hooks/ # 自定义 Hooks ├── layouts/ # 布局组件 ├── pages/ # 页面级组件 ├── routes/ # 路由配置 ├── stores/ # 全局状态 ├── styles/ # 全局样式 ├── utils/ # 工具函数 └── types/ # 类型定义这个划分不一定适合所有项目，但有一件事很重要：目录结构在项目第一天就定好。后期再调整目录的成本非常高，因为每个路径引用都要改动一遍。4.2 路由层配置和按需加载路由配置我倾向于把所有路由收敛到一个数组里集中管理，然后用循环生成路由。这样页面组件维护在一个文件里，新增页面时只需要加一段配置。// routes/index.js const routes = [ { path: '/dashboard', component: () => import('@/pages/Dashboard'), meta: { title: '数据看板', requiresAuth: true } }, { path: '/orders', component: () => import('@/pages/Orders'), meta: { title: '订单列表', requiresAuth: true }, children: [ { path: 'detail/:id', component: () => import('@/pages/OrderDetail'), meta: { title: '订单详情', requiresAuth: true } } ] } ];这里用到动态import()实现路由级按需加载，首屏只加载当前路由需要的代码块，而不是整个应用打包成一个文件。这个优化对中大型项目效果非常明显。4.3 封装请求客户端和接口管理请求客户端的封装我在第2.3节说过基本思路，这里展示一个更具体的落地版本：// utils/request.ts const request = async (config) => { try { const response = await fetch(config.url, { method: config.method || 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${getToken()}`, ...config.headers }, body: config.data ? JSON.stringify(config.data) : undefined }); const result = await response.json(); if (result.code !== 0) { // 统一处理业务错误 if (result.code === 401) { redirectToLogin(); } throw new Error(result.message); } return result.data; } catch (error) { // 统一处理网络错误和异常 notification.error(error.message); throw error; } };接口函数的组织方式是每一个接口一个函数，全部挂在@/api目录下。这样做的好处是接口的入参、出参、错误信息都收敛在一个地方，业务组件里去调用时非常轻量，而且便于后续接口变更时集中修改。4.4 核心功能实现：列表页 + 筛选 + 分页模拟项目 X 的核心页面是订单列表页。这个页面包含了 React 项目最常见的几个组合：筛选表单、列表表格、分页、交互反馈。父组件结构大概是这样的：function OrdersPage() { const [filter, setFilter] = useState({ status: '', dateRange: [] }); const { data, loading, total, refresh } = useFetchList('/api/orders', filter); const handleFilterChange = useCallback((values) => { setFilter(values); // 筛选条件变化后，一般需要重置到第一页 }, []); return ( <div> <FilterPanel values={filter} onChange={handleFilterChange} /> <OrderTable data={data} loading={loading} /> <Pagination total={total} onChange={refresh} /> </div> ); }这里useFetchList是一个自定义 Hook，负责封装列表请求的完整生命周期：参数变化时自动请求、loading 状态、错误状态、手动刷新等。这样组件代码里不会到处散落 fetch 调用，逻辑也更好测试。4.5 详情页交互和跨页面状态传递从列表页进入详情页，常见的状态传递方式有两种：一种是通过路由动态参数传id，详情页自己拉数据；另一种是把整个详情对象塞进全局 store，但这样刷新页面就丢了。实际开发中我习惯用第一种，因为更可靠，刷新页面也能恢复，而且数据源更清晰。详情页内部还会涉及一些复杂的交互，比如操作日志折叠、状态流转按钮、负责人分配弹窗等。这也正是自定义 Hook 发挥作用的场景：useOrderDetail(id)负责详情数据加载和基础操作，useOperateOrder(id)负责提交操作类动作。组件保持轻量，逻辑都在 Hook 层。5. 常见问题与排查技巧实录React 项目开发到一定规模后，总会遇到一些反复出现的经典问题。下面这些是我在实战中高频踩过、也帮其他人排查过的问题，整理成速查表方便对照处理。5.1 组件不更新的排查路径表现：props 或 state 明明变了，组件就是不重新渲染。排查思路按顺序走：先确认是不是用了React.memo包裹了子组件，而父组件传入的 props 是内联对象/匿名函数。这种情况下每次父组件渲染，子组件接收到的 props 虽然内容一样，但引用不同，memo 失效，或者反过来 memo 生效导致不更新。再确认是不是更新了 state 本身，而不是修改了 state 对象的某个属性。React 的状态比较是浅比较，直接修改state.obj.name而不更换state.obj的引用，React 会认为状态没变。最后确认是否在正确的组件里修改了状态。很多“不更新”其实是状态放在子组件中，父组件里的其它 UI 当然不会感知到。这个问题的根子大多出在“状态引用不变”或“状态位置不对”上面，找到位置再改基本上就能解决。5.2 useEffect 重复执行表现：一次操作，effect 执行了两次，或者请求发出两遍。最常见原因：框架的严格模式会在开发环境下故意调用两次 effect，用于帮助开发者发现自己代码里的隐患。生产环境不受影响，所以要先区分是环境差异，还是真的重复。如果确实是自己的代码导致重复，常见原因是依赖数组里放了对象或数组，每次渲染都是新的引用，导致 effect 每次都执行。处理方法是依赖项只放基础类型的值，或者用useMemo把对象缓存起来。还有一种情况是事件触发链路写重了：比如点了按钮触发一次，然后组件又在上层响应了这个变化又触发一次。这种排查起来要顺着事件流走一遍，能看到比较直接的线索。5.3 状态更新后页面卡顿表现：打字输入表单，敲一个字卡一下；列表很长时筛选，明显迟滞。通常原因有几种，最典型的是每次输入都触发了全链路的数据请求，而请求很慢，导致输入响应被阻塞。解决办法是把受控输入和请求分离：用本地 state 保存输入值，输入时只更新本地状态，等停止输入一段时间后再触发请求（防抖）。另一个原因是列表组件没有做记忆化，每次输入变化，整个列表重新渲染。处理方式是对列表子组件使用React.memo包裹，并且确保传给列表的 props 引用稳定。还有一个常见原因是渲染了超大列表且没有做虚拟化。几千行的表格全部渲染，DOM 节点太多，自然卡顿。这种情况建议引入虚拟滚动库处理长列表，渲染性能会好很多。5.4 表单组件受控与非受控混用表现：明明给了 defaultValue，输入框输入后值却不更新，或者编辑表单时初始值变了，输入框内容没跟着变。这通常是因为把某个中途变化的 props 当作defaultValue传给了输入框。defaultValue只在组件首次挂载时生效，后续 props 变化不会更新输入框的内容。正确做法是使用value加onChange完全受控，或者直接使用key来强制重新挂载表单组件。实际项目中，编辑页很容易踩这个坑：打开弹窗、异步拿到详情、再把详情传给表单组件，结果表单内容不刷新。解决方式就是在拿到详情数据后，给表单组件设置一个关键的key，比如key={detailId}，让 React 在数据变化后重新创建表单组件实例。5.5 状态管理中的数据同步问题表现：两个组件都用同一个全局状态，A 修改了，B 没变。绝大多数时候，这个问题的原因是 B 组件读的不是同一个状态，比如有的组件直接从 store 读，有的组件把 store 的值复制到了自己的本地 state 里，本地 state 只有挂载时同步一次，之后 store 怎么变，本地 state 都无感知。排查思路：在 B 组件里打日志看刷新时拿到的值是不是最新，再确认 B 是不是被某个 parent 挡住了（比如 parent 没有正确订阅 store）。另外一个隐蔽点是 selector 的写法，如果 selector 返回的是新引用的对象，配合某些库时会造成死循环或频繁重渲染，用shallow相等比较能解决。6. 性能优化的几个实际手段性能优化这个话题很大，我挑几个在 React 项目里最常用、最见效的手段，按收益从高到低排一下。6.1 路由级代码分割上面提到过的动态import()是 React 项目性能优化里性价比最高的一步。初始打包的 bundle 会被分割成多个 chunk，首屏只加载当前路由对应的 chunk。尤其是中后台项目，登录之后不同部门、不同角色的页面差异很大，首屏加载全部页面代码实在没意义。实际测量中，一个包含 20 多个路由的页面，做路由级分割后，首屏 JS 体积通常能减掉一半以上，加载时间可以快不少。这一步的实现成本很低，但收益很明显。6.2 大数据列表的虚拟化当列表长度达到几千甚至上万条时，DOM 节点的数量会直接拖垮渲染性能。虚拟化的核心思想是只渲染可视区域内的那几十个节点，滚动时动态替换内容。这个方案对于表格、长列表、聊天记录这类场景非常有效。引入一个成熟的虚拟滚动组件，把列表区域的高度固定，数据走虚拟列表，滚动流畅度会有质的提升。需要注意的地方是：虚拟列表的每一项最好有稳定且唯一的 key，否则滚动时会出现错乱；测量行高的方式要统一，否则滚动位置会抖动。6.3 减少不必要的重新渲染减少不必要的重新渲染，靠的不是疯狂加React.memo，而是提升组件设计本身的质量。比较实用的拆法有两种：把“频繁变化的部分”和“稳定部分”拆开。比如列表页里，筛选条件区域和表格区域拆成独立组件，筛选条件输入变化时，表格不应该刷新。让状态尽量靠近真正使用它的组件，不要让无关组件因为某个状态变化而都刷新一遍。用 React DevTools 的 Profiler 面板记录交互操作的渲染耗时，能直观看到哪些组件渲染了、耗时多少。对照着这种数据去优化，远比盲猜要靠谱。6.4 图片资源和静态体积的控制中后台项目可能对图片体积不那么敏感，但对前端整体性能而言，静态资源的处理同样重要。图片尽量用现代格式、按需压缩；图标尽量用字体图标或 SVG 而不是一张张图片；公共的工具函数库要按需引入，避免把整个库打包进主 bundle。一个比较容易忽略的点是：引入的第三方库如果支持按需加载，尽量按需引，不然打包后的体积会很难控制。7. 一些在真实项目中总结的经验细节最后一部分，分享几个比较零散、不容易在官方文档里看到的个人经验。这些细节影响面不算大，但积累多了会让代码质量上一个台阶。7.1 给列表项加稳定 key 的重要性列表渲染时给每一项设置key是 React 的基础要求。很多人图省事用数组索引当 key，这在列表项不增删、不排序的静态场景里能用，但一旦涉及增删、排序、拖拽，用索引作为 key 就会引发很多诡异 bug：项状态错乱、输入框内容串位、动画错乱等。可靠的做法是使用业务 id 作为 key，如果没有 id，也要构造一个稳定的唯一标识，比如复合字段拼接。关键点都在于 key 必须能唯一标识这一项在整个列表中的身份，而不是标识它的位置。7.2 配置项尽量收敛，不要散落各处项目里经常会遇到一些业务配置，比如状态枚举的文案和颜色、路由的标题和权限、表单项的校验规则。这些配置如果散落在各个组件里，后续改动起来非常痛苦。我习惯把这类业务配置收敛到单独的配置文件中统一维护。比如订单状态有几种、每种的状态值、展示文字、徽章颜色，集中放在一个文件里，组件中通过工具函数引用。这样做的额外好处是：做权限控制、做筛选下拉选项、做导出数据映射，都可以复用这同一份配置，保证数据的一致。7.3 错误边界和兜底展示不是可有可无React 组件在渲染过程中如果发生未捕获的异常，会导致整个应用白屏。这不是一个“加了更好”的优化项，而是一个必须做的兜底措施。主流做法是配置错误边界组件，在组件树中包住业务区域，一旦子组件抛出错误，就降级渲染为友好的错误提示页面，而不是让整个应用崩溃。轻微一点的，也可以给数据加载失败、为空的情况设计统一的空状态和重试按钮，这是产品体验的一部分，不能省略。7.4 组件命名和信息架构要提前对齐React 项目里组件文件命名、组件内部变量命名、props 的命名，看似琐碎，但在协作项目里影响很大。最好在项目开始几天内就形成一套约定，而不是每个开发者各写各的。例如所有组件文件从语义角度命名，变量一律不用缩写，布尔型 props 统一以is、can、has开头。这些约定一旦成行，后面读代码、修 bug 的体验会很不一样。如果团队风格还没有统一，最简单的建议就是社区里通行的那套：组件文件用大驼峰命名，普通工具函数用小驼峰命名，布尔变量用isXxx这种格式。先统一命名，再谈维护性，这个顺序不能反。写在最后的个人体会用了这么久 React，我最大的体会是：React 本身只是一层视图层能力，你对工程化、状态拆分和数据流组织的理解和实践，才真正决定这个项目能撑到多大。很多项目的代码复杂，其实不是 React 用错了，而是组件划分、状态归属、数据请求这些基础问题没想清楚，日积月累变成了庞大难维护的代码体。每次重构后链路顺畅、组件拆得干净的那种感觉，真的比多写几个组件更让人觉得踏实。最后分享一个维护老项目的小技巧：如果拿到一个别人写的 React 项目，不要先把所有代码都看完，先整理出路由表、组件树、状态分布图，用这三张图作为地图去读代码，会省下很多时间。这个习惯我在接手任何一个新项目时都会用，很管用。希望这篇经验对你有参考价值。
看到标题“rea”，很多做前端的朋友应该都不陌生，这就是 React 在社区里、在代码仓库里最常用的简称。但正是因为太常见了，反而容易让人忽略它背后那一整套完整的前端工程化思维。这篇内容我不打算讲官方文档上已有的 API 清单，而是想换个角度，从“拿到一个项目标题、需求只有一句话”时，一个老手是怎么思考、怎么拆解、怎么一步步把页面搭起来、把状态管好、把性能抠出来、最后踩坑排雷的完整过程。这些经验大多来自实际开发中的复盘，希望对正在用 React 做项目的你有一点参考价值。无论你是刚接触 React 的初学者，还是已经用了两三年但总觉得在“照着文档写组件”的开发，这篇文章都会有点用处。我会从设计思路、工程化选型、核心实现，再到问题排查，完整过一遍 React 项目的落地流程。每一条都不会是空泛的理论，而是可以照着做、照着调的东西。1. 拿到需求别急着写代码：先理清组件边界和状态模型很多初学者拿到项目需求，第一反应是“这个页面长这样，我来照着写”。框架本身确实允许你这么快开始，但实际项目里，这种做法的返工率极高。React 的核心理念是“以组件为单位构建 UI”，但组件怎么拆、状态放哪儿、数据怎么流动，这些决策比写 JSX 本身重要得多。1.1 组件拆分：按职责而不是按视觉分区我见过不少项目，组件目录是照着设计稿的视觉区块建的：一个 Header 组件、一个 Sidebar 组件、一个 Content 组件。这种方式的直观问题在于，视觉区块和业务职责往往并不一致。更好的做法是按业务职责和复用粒度来拆。比如一个电商后台的订单列表页，按照视觉区块你会拆成：顶部筛选区、表格区、分页器、弹窗详情。但按职责来拆，应该是：OrderFilter（负责筛选条件状态）、OrderTable（负责列表数据和列配置）、OrderDetailDialog（负责详情展示和操作交互）、Pagination（通用组件）。这样拆的好处是每个组件的 props 和 state 都相对清晰，改动一个业务逻辑时不需要在多个“视觉区块”里来回找。判断一个组件职责是否合理，有一个很朴素的标准：如果你要给这个组件写一段“它负责什么”的描述，这段描述是否超过两句话。超过两句话，大概率这个组件管得太多了，应该再拆。1.2 状态模型设计：哪些放本地 state，哪些放全局 store状态管理是 React 项目里的争议重灾区。我见过一个中型项目把所有的数据都放进全局 store，结果组件刷新、内存占用、调试成本全线告急；也见过相反的情况，连登录用户信息都放在组件本地 state 里，导致刷新页面就丢状态。我的经验是分三挡来决策：第一挡，组件本地 state：只影响当前组件 UI 的临时状态，比如弹窗开合、选项卡索引、表单某个字段的临时值。这类状态用useState就好，根本不需要全局化。第二挡，跨组件共享但不需要持久化的数据：比如多个兄弟组件都要读某个筛选条件，或者某个计算结果被多个地方复用。这时候用useContext配合useReducer或者直接提升 state 到最近的公共父组件，已经足够。第三挡，需要跨页面共享、涉及复杂数据交互、或者需要缓存的服务端数据：这才需要真正的全局 store。一个很容易被忽略的原则是：能放本地的就不要放全局，能放近的不要放远的。全局状态越少，项目的可维护性越高。这个原则没有变化，任何时候做 React 项目都适用，因为全局数据一多，必然面临“这个状态是从哪来、要被谁改、当前是什么值”的三连拷问。1.3 从数据流反推组件层级确定状态模型之后，再顺着数据流把组件层级排出来，比先画视觉再想数据要顺得多。核心思路是：找一个状态需要被哪些组件读取，找到这些组件的最近公共父组件，让状态待在父组件里，通过 props 向下传递。举一个实际例子：筛选条件区域和一个结果列表区域其实是联动的。筛选条件的某个值变更，列表需要重新请求并展示。最合理的结构是把筛选条件和列表数据同时放在它们共同的父组件里，父组件持有筛选条件的 state 和列表数据的 state，传递一个onFilterChange给筛选组件，传递data给列表组件。这个结构简单清晰，两个子组件完全可以独立复用。2. 工程化选型有讲究：脚手架、路由、请求层和样式方案一个 React 项目的工程化选型直接决定了项目的开发体验和长期可维护性。这部分我不会推荐“唯一正确答案”，因为不同的团队风格、项目周期、部署环境，正确答案不一样。我重点是讲明白每个选型背后的考量，这样你拿到自己的项目时能做出适合自己的判断。2.1 初始化方式：为什么你仍然需要一个构建工具现在初始化 React 项目最主流的命令已经不是手动配置 Webpack 了。社区推荐的方式是用官方脚手架或社区维护的起步模板，它们把构建、转译、热更新、代码规范都集成好了。我在实际项目里更看重的是模板对 TypeScript 的支持是否开箱即用，因为类型系统在项目规模上去之后，带来的收益是实实在在的。如果一个模板还要你自己去配置 tsconfig、编辑器和构建插件之间的集成，那我建议换一个模板，省下的时间用来写业务逻辑更划算。2.2 路由设计：不是加一个库那么简单React 应用大多是单页富应用，路由库是很基础的一层。选路由方案时，我特别关注三点：是否支持嵌套路由对应的组件嵌套结构。因为实际业务里，一个主布局下面往往有多级页面，路由的嵌套结构如果能和组件树的结构一一对应，理解成本会大幅降低。是否支持动态路由和按需加载。大型项目的首屏性能很大程度依赖路由级代码分割。路由参数的类型安全。路由设计上有一个容易被忽略的细节：把路由配置收敛到一个独立文件里集中管理。哪怕刚开始只有两三个页面，也建议这么做。因为后续增加页面、权限控制、面包屑导航、页面标题设置，都可以依托这一份配置来实现。我自己习惯在每个页面配置里带上title、icon、permission等元信息字段，后续做导航菜单和权限拦截时就能直接用，不用额外维护一份重复的菜单配置文件。2.3 数据请求层：fetch 封装、缓存与请求状态处理数据请求层是 React 项目里最容易写乱的部分。我见过那种在组件里到处写 fetch 然后 .then 回调，最后全项目布满了 loading 状态的方式——不是说不能用，但项目一复杂就很容易乱。更稳妥的方式是封装一个统一的请求客户端，基于浏览器原生 fetch 或者基于 XMLHttpRequest 的库封一层，统一处理：请求头的注入（比如认证 token）。响应拦截（比如统一处理后端返回的 code，data，message 结构）。错误处理（网络错误、业务错误、登录过期跳转登录页）。重复请求取消。请求状态的管理我建议用自定义 Hook 的方式收敛，比如useFetchList、useMutation这类对外暴露data、loading、error、refresh等方法的封装。组件只用关心自己的数据从哪来，请求被打到哪里、怎么重试、取消请求这些问题，统一封装在前端。2.4 样式方案：CSS Modules 还是 CSS-in-JS开发时这个选择的优先级很高，跟前端项目的兼容和团队协作关系很大。我个人的经验是：对大多数中小型项目，CSS Modules 通常是最稳妥的方案，因为它不引入额外的运行时，样式的局部作用域可以避免写长选择器互相覆盖，而且写起来就是普通 CSS，团队成员上手成本很低。CSS-in-JS 方案的优点是样式和逻辑在同一个文件里，动态样式处理很灵活。但运行时开销和调试成本还是现实问题。如果是组件库或需要大量动态样式的项目，CSS-in-JS 更有优势，具体只能看团队的项目情况定，没有放之四海皆准的标准答案。3. 核心细节解析：Hooks 落地的几个硬核技巧React 16.8 之后，函数组件加 Hooks 已经是绝对的主流写法。但 Hooks 的粒度怎么控制、依赖数组怎么填、副作用怎么处理，才是从“会用”到“用得好”的分水岭。3.1 useState 的惰性初始化和函数式更新useState有个容易被忽略的细节：初始值如果是通过复杂计算得到的，应该传一个函数进去，让它只在组件首次渲染时执行一次，而不是每次渲染都重复算。这个优化在初始值是数组、要经过 map/filter 等遍历计算时，收益是肉眼可见的。另一个重要细节是依赖前一个状态更新时，应该用函数式更新的形式。看这个场景：const [count, setCount] = useState(0); // 不推荐：当多次连续调用 setCount 时会基于同一个旧值计算 setCount(count + 1); setCount(count + 1); // 推荐：每次都是基于最新值计算 setCount(prev => prev + 1);虽然 React 的批处理机制能缓解不少问题，但在复杂交互下（比如快速点击、异步回调中更新），函数式更新是更稳的写法。3.2 useEffect 的依赖数组：不是随便填的useEffect的依赖数组是新手最容易踩的坑。不填依赖数组（每次渲染都执行）、填空数组（只在挂载时执行一次）、填部分依赖（可能漏掉某个变量），三种情况各自都有问题。最实用的原则：依赖数组里应该列出 effect 中引用的每一个响应式值。如果你发现依赖数组里东西太多导致 effect 频繁触发，正确的做法不是强行忽略依赖，而是重新审视代码结构，把多个职责拆开。一个 effect 只做一件事，依赖就会更清晰。还有一个经常踩的坑是：在 effect 里使用了某个 props 或 state，但依赖数组里漏掉了它。结果就是 effect 执行时用的还是旧值，这个问题排查起来很隐蔽，因为不是每次都会复现。所以我现在写代码有个习惯，写完之后会先看一眼 effect 里引用了哪些外部变量，再对照依赖数组确认它们是否都列出来了。3.3 useMemo 和 useCallback：为性能服务，但别滥用很多开发者一听说性能优化，就开始到处塞useMemo和useCallback。但这两个 API 是有代价的，它们本身也是有一定开销的：需要额外的内存保存依赖、需要比对依赖是否变化。如果一个计算本身很轻量，或者一个函数本身很稳定，就不值得用它们去包一层。性能优化第一步永远是分析真正的瓶颈，而不是凭直觉盲优化。合理的场景是：useMemo：复杂数据转换、列表过滤排序、大对象深度对比等。useCallback：需要传递给被React.memo包裹的子组件的函数，或者作为 effect 依赖的函数。判断取舍的一个技巧是：先把代码写清楚，性能测试发现确实有问题了，再针对性地加记忆化。盲目加 useMemo 会让代码可读性下降，而且依赖数组本身也是一个心智负担。3.4 自定义 Hooks：把逻辑抽到组件之外，但不要把组件拆得太碎自定义 Hooks 是 React 工程化项目里提升复用度的最佳手段之一。比如一个有“输入内容并防抖请求”需求的搜索框，通常的做法是直接写到组件里，但更合理的做法是把它抽成useDebouncedSearch。这样搜索逻辑的细节被藏起来，组件里只需要关心要不要显示 loading，以及拿到的列表数据。不过自定义 Hooks 也有一个边界问题：不要把所有东西都拆成 Hooks。如果一个 Hook 只被一个组件使用，而且里面的逻辑很简单，那抽出来反而增加跳转成本。先写在组件里，发现有一大坨逻辑导致组件难以阅读时，再抽出去，这样的节奏最自然。4. 实操过程：从零到一搭建一个 React 项目（完整步骤演练）这一部分我用一个模拟项目 X（企业内部的数据分析看板前端）为例，带你完整走一遍从初始化到核心功能实现的流程。这个项目规模适中，包含了列表页、详情页、表单提交、数据可视化图表展示，非常适合用来演示 React 工程化的完整套路。4.1 项目初始化和目录结构规划第1步是用你选定的脚手架初始化项目，然后在项目根目录下规划目录结构。我的习惯是按下图这样划分：src/ ├── api/ # 接口请求函数 ├── assets/ # 静态资源 ├── components/ # 通用业务组件 ├── hooks/ # 自定义 Hooks ├── layouts/ # 布局组件 ├── pages/ # 页面级组件 ├── routes/ # 路由配置 ├── stores/ # 全局状态 ├── styles/ # 全局样式 ├── utils/ # 工具函数 └── types/ # 类型定义这个划分不一定适合所有项目，但有一件事很重要：目录结构在项目第一天就定好。后期再调整目录的成本非常高，因为每个路径引用都要改动一遍。4.2 路由层配置和按需加载路由配置我倾向于把所有路由收敛到一个数组里集中管理，然后用循环生成路由。这样页面组件维护在一个文件里，新增页面时只需要加一段配置。// routes/index.js const routes = [ { path: '/dashboard', component: () => import('@/pages/Dashboard'), meta: { title: '数据看板', requiresAuth: true } }, { path: '/orders', component: () => import('@/pages/Orders'), meta: { title: '订单列表', requiresAuth: true }, children: [ { path: 'detail/:id', component: () => import('@/pages/OrderDetail'), meta: { title: '订单详情', requiresAuth: true } } ] } ];这里用到动态import()实现路由级按需加载，首屏只加载当前路由需要的代码块，而不是整个应用打包成一个文件。这个优化对中大型项目效果非常明显。4.3 封装请求客户端和接口管理请求客户端的封装我在第2.3节说过基本思路，这里展示一个更具体的落地版本：// utils/request.ts const request = async (config) => { try { const response = await fetch(config.url, { method: config.method || 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${getToken()}`, ...config.headers }, body: config.data ? JSON.stringify(config.data) : undefined }); const result = await response.json(); if (result.code !== 0) { // 统一处理业务错误 if (result.code === 401) { redirectToLogin(); } throw new Error(result.message); } return result.data; } catch (error) { // 统一处理网络错误和异常 notification.error(error.message); throw error; } };接口函数的组织方式是每一个接口一个函数，全部挂在@/api目录下。这样做的好处是接口的入参、出参、错误信息都收敛在一个地方，业务组件里去调用时非常轻量，而且便于后续接口变更时集中修改。4.4 核心功能实现：列表页 + 筛选 + 分页模拟项目 X 的核心页面是订单列表页。这个页面包含了 React 项目最常见的几个组合：筛选表单、列表表格、分页、交互反馈。父组件结构大概是这样的：function OrdersPage() { const [filter, setFilter] = useState({ status: '', dateRange: [] }); const { data, loading, total, refresh } = useFetchList('/api/orders', filter); const handleFilterChange = useCallback((values) => { setFilter(values); // 筛选条件变化后，一般需要重置到第一页 }, []); return ( <div> <FilterPanel values={filter} onChange={handleFilterChange} /> <OrderTable data={data} loading={loading} /> <Pagination total={total} onChange={refresh} /> </div> ); }这里useFetchList是一个自定义 Hook，负责封装列表请求的完整生命周期：参数变化时自动请求、loading 状态、错误状态、手动刷新等。这样组件代码里不会到处散落 fetch 调用，逻辑也更好测试。4.5 详情页交互和跨页面状态传递从列表页进入详情页，常见的状态传递方式有两种：一种是通过路由动态参数传id，详情页自己拉数据；另一种是把整个详情对象塞进全局 store，但这样刷新页面就丢了。实际开发中我习惯用第一种，因为更可靠，刷新页面也能恢复，而且数据源更清晰。详情页内部还会涉及一些复杂的交互，比如操作日志折叠、状态流转按钮、负责人分配弹窗等。这也正是自定义 Hook 发挥作用的场景：useOrderDetail(id)负责详情数据加载和基础操作，useOperateOrder(id)负责提交操作类动作。组件保持轻量，逻辑都在 Hook 层。5. 常见问题与排查技巧实录React 项目开发到一定规模后，总会遇到一些反复出现的经典问题。下面这些是我在实战中高频踩过、也帮其他人排查过的问题，整理成速查表方便对照处理。5.1 组件不更新的排查路径表现：props 或 state 明明变了，组件就是不重新渲染。排查思路按顺序走：先确认是不是用了React.memo包裹了子组件，而父组件传入的 props 是内联对象/匿名函数。这种情况下每次父组件渲染，子组件接收到的 props 虽然内容一样，但引用不同，memo 失效，或者反过来 memo 生效导致不更新。再确认是不是更新了 state 本身，而不是修改了 state 对象的某个属性。React 的状态比较是浅比较，直接修改state.obj.name而不更换state.obj的引用，React 会认为状态没变。最后确认是否在正确的组件里修改了状态。很多“不更新”其实是状态放在子组件中，父组件里的其它 UI 当然不会感知到。这个问题的根子大多出在“状态引用不变”或“状态位置不对”上面，找到位置再改基本上就能解决。5.2 useEffect 重复执行表现：一次操作，effect 执行了两次，或者请求发出两遍。最常见原因：框架的严格模式会在开发环境下故意调用两次 effect，用于帮助开发者发现自己代码里的隐患。生产环境不受影响，所以要先区分是环境差异，还是真的重复。如果确实是自己的代码导致重复，常见原因是依赖数组里放了对象或数组，每次渲染都是新的引用，导致 effect 每次都执行。处理方法是依赖项只放基础类型的值，或者用useMemo把对象缓存起来。还有一种情况是事件触发链路写重了：比如点了按钮触发一次，然后组件又在上层响应了这个变化又触发一次。这种排查起来要顺着事件流走一遍，能看到比较直接的线索。5.3 状态更新后页面卡顿表现：打字输入表单，敲一个字卡一下；列表很长时筛选，明显迟滞。通常原因有几种，最典型的是每次输入都触发了全链路的数据请求，而请求很慢，导致输入响应被阻塞。解决办法是把受控输入和请求分离：用本地 state 保存输入值，输入时只更新本地状态，等停止输入一段时间后再触发请求（防抖）。另一个原因是列表组件没有做记忆化，每次输入变化，整个列表重新渲染。处理方式是对列表子组件使用React.memo包裹，并且确保传给列表的 props 引用稳定。还有一个常见原因是渲染了超大列表且没有做虚拟化。几千行的表格全部渲染，DOM 节点太多，自然卡顿。这种情况建议引入虚拟滚动库处理长列表，渲染性能会好很多。5.4 表单组件受控与非受控混用表现：明明给了 defaultValue，输入框输入后值却不更新，或者编辑表单时初始值变了，输入框内容没跟着变。这通常是因为把某个中途变化的 props 当作defaultValue传给了输入框。defaultValue只在组件首次挂载时生效，后续 props 变化不会更新输入框的内容。正确做法是使用value加onChange完全受控，或者直接使用key来强制重新挂载表单组件。实际项目中，编辑页很容易踩这个坑：打开弹窗、异步拿到详情、再把详情传给表单组件，结果表单内容不刷新。解决方式就是在拿到详情数据后，给表单组件设置一个关键的key，比如key={detailId}，让 React 在数据变化后重新创建表单组件实例。5.5 状态管理中的数据同步问题表现：两个组件都用同一个全局状态，A 修改了，B 没变。绝大多数时候，这个问题的原因是 B 组件读的不是同一个状态，比如有的组件直接从 store 读，有的组件把 store 的值复制到了自己的本地 state 里，本地 state 只有挂载时同步一次，之后 store 怎么变，本地 state 都无感知。排查思路：在 B 组件里打日志看刷新时拿到的值是不是最新，再确认 B 是不是被某个 parent 挡住了（比如 parent 没有正确订阅 store）。另外一个隐蔽点是 selector 的写法，如果 selector 返回的是新引用的对象，配合某些库时会造成死循环或频繁重渲染，用shallow相等比较能解决。6. 性能优化的几个实际手段性能优化这个话题很大，我挑几个在 React 项目里最常用、最见效的手段，按收益从高到低排一下。6.1 路由级代码分割上面提到过的动态import()是 React 项目性能优化里性价比最高的一步。初始打包的 bundle 会被分割成多个 chunk，首屏只加载当前路由对应的 chunk。尤其是中后台项目，登录之后不同部门、不同角色的页面差异很大，首屏加载全部页面代码实在没意义。实际测量中，一个包含 20 多个路由的页面，做路由级分割后，首屏 JS 体积通常能减掉一半以上，加载时间可以快不少。这一步的实现成本很低，但收益很明显。6.2 大数据列表的虚拟化当列表长度达到几千甚至上万条时，DOM 节点的数量会直接拖垮渲染性能。虚拟化的核心思想是只渲染可视区域内的那几十个节点，滚动时动态替换内容。这个方案对于表格、长列表、聊天记录这类场景非常有效。引入一个成熟的虚拟滚动组件，把列表区域的高度固定，数据走虚拟列表，滚动流畅度会有质的提升。需要注意的地方是：虚拟列表的每一项最好有稳定且唯一的 key，否则滚动时会出现错乱；测量行高的方式要统一，否则滚动位置会抖动。6.3 减少不必要的重新渲染减少不必要的重新渲染，靠的不是疯狂加React.memo，而是提升组件设计本身的质量。比较实用的拆法有两种：把“频繁变化的部分”和“稳定部分”拆开。比如列表页里，筛选条件区域和表格区域拆成独立组件，筛选条件输入变化时，表格不应该刷新。让状态尽量靠近真正使用它的组件，不要让无关组件因为某个状态变化而都刷新一遍。用 React DevTools 的 Profiler 面板记录交互操作的渲染耗时，能直观看到哪些组件渲染了、耗时多少。对照着这种数据去优化，远比盲猜要靠谱。6.4 图片资源和静态体积的控制中后台项目可能对图片体积不那么敏感，但对前端整体性能而言，静态资源的处理同样重要。图片尽量用现代格式、按需压缩；图标尽量用字体图标或 SVG 而不是一张张图片；公共的工具函数库要按需引入，避免把整个库打包进主 bundle。一个比较容易忽略的点是：引入的第三方库如果支持按需加载，尽量按需引，不然打包后的体积会很难控制。7. 一些在真实项目中总结的经验细节最后一部分，分享几个比较零散、不容易在官方文档里看到的个人经验。这些细节影响面不算大，但积累多了会让代码质量上一个台阶。7.1 给列表项加稳定 key 的重要性列表渲染时给每一项设置key是 React 的基础要求。很多人图省事用数组索引当 key，这在列表项不增删、不排序的静态场景里能用，但一旦涉及增删、排序、拖拽，用索引作为 key 就会引发很多诡异 bug：项状态错乱、输入框内容串位、动画错乱等。可靠的做法是使用业务 id 作为 key，如果没有 id，也要构造一个稳定的唯一标识，比如复合字段拼接。关键点都在于 key 必须能唯一标识这一项在整个列表中的身份，而不是标识它的位置。7.2 配置项尽量收敛，不要散落各处项目里经常会遇到一些业务配置，比如状态枚举的文案和颜色、路由的标题和权限、表单项的校验规则。这些配置如果散落在各个组件里，后续改动起来非常痛苦。我习惯把这类业务配置收敛到单独的配置文件中统一维护。比如订单状态有几种、每种的状态值、展示文字、徽章颜色，集中放在一个文件里，组件中通过工具函数引用。这样做的额外好处是：做权限控制、做筛选下拉选项、做导出数据映射，都可以复用这同一份配置，保证数据的一致。7.3 错误边界和兜底展示不是可有可无React 组件在渲染过程中如果发生未捕获的异常，会导致整个应用白屏。这不是一个“加了更好”的优化项，而是一个必须做的兜底措施。主流做法是配置错误边界组件，在组件树中包住业务区域，一旦子组件抛出错误，就降级渲染为友好的错误提示页面，而不是让整个应用崩溃。轻微一点的，也可以给数据加载失败、为空的情况设计统一的空状态和重试按钮，这是产品体验的一部分，不能省略。7.4 组件命名和信息架构要提前对齐React 项目里组件文件命名、组件内部变量命名、props 的命名，看似琐碎，但在协作项目里影响很大。最好在项目开始几天内就形成一套约定，而不是每个开发者各写各的。例如所有组件文件从语义角度命名，变量一律不用缩写，布尔型 props 统一以is、can、has开头。这些约定一旦成行，后面读代码、修 bug 的体验会很不一样。如果团队风格还没有统一，最简单的建议就是社区里通行的那套：组件文件用大驼峰命名，普通工具函数用小驼峰命名，布尔变量用isXxx这种格式。先统一命名，再谈维护性，这个顺序不能反。写在最后的个人体会用了这么久 React，我最大的体会是：React 本身只是一层视图层能力，你对工程化、状态拆分和数据流组织的理解和实践，才真正决定这个项目能撑到多大。很多项目的代码复杂，其实不是 React 用错了，而是组件划分、状态归属、数据请求这些基础问题没想清楚，日积月累变成了庞大难维护的代码体。每次重构后链路顺畅、组件拆得干净的那种感觉，真的比多写几个组件更让人觉得踏实。最后分享一个维护老项目的小技巧：如果拿到一个别人写的 React 项目，不要先把所有代码都看完，先整理出路由表、组件树、状态分布图，用这三张图作为地图去读代码，会省下很多时间。这个习惯我在接手任何一个新项目时都会用，很管用。希望这篇经验对你有参考价值。