react-best-practices

React 最佳实践

客户端 React 应用的性能优化指南。包含 8 个类别、47 条规则，并按影响程度排序。改编自 Vercel Engineering 的指南，筛选适用于纯客户端 React + Vite 的内容（不含 Next.js / SSR）。

适用场景

在以下场景中参考这些指南：

• 编写新的 React 组件或钩子
• 检查代码中的性能问题
• 重构现有 React 代码
• 优化包体积或渲染性能
• 编写或检查 useEffect 的用法

按优先级排列的规则类别

优先级	类别	影响	前缀
1	消除瀑布流	CRITICAL	async-
2	优化包体积	CRITICAL	bundle-
3	客户端数据获取	MEDIUM-HIGH	client-
4	优化重新渲染	MEDIUM	rerender-
5	useEffect 模式	MEDIUM	useeffect-
6	渲染性能	MEDIUM	rendering-
7	JavaScript 性能	LOW-MEDIUM	js-
8	高级模式	LOW	advanced-

快速参考

1. 消除瀑布流（CRITICAL）

• async-defer-await — 将 await 移入实际使用它的分支
• async-parallel — 对独立操作使用 Promise.all()
• async-dependencies — 对部分依赖使用 Promise 链
• async-api-routes — 尽早启动 Promise，尽晚等待

2. 优化包体积（CRITICAL）

• bundle-barrel-imports — 直接导入，避免使用汇总导出文件
• bundle-conditional — 仅在功能启用时加载模块
• bundle-defer-third-party — 在挂载后加载分析/日志工具
• bundle-preload — 在悬停/聚焦时预加载，提升感知速度

3. 客户端数据获取（MEDIUM-HIGH）

• client-event-listeners — 对全局事件侦听器去重
• client-passive-event-listeners — 对滚动/触摸事件使用被动侦听器
• client-swr-dedup — 使用 SWR 自动对请求去重
• client-localstorage-schema — 为 localStorage 数据设置版本并精简数据

4. 优化重新渲染（MEDIUM）

• rerender-derived-state-no-effect — 在渲染期间派生状态，而非在 effect 中派生
• rerender-defer-reads — 不要订阅仅在回调中使用的状态
• rerender-simple-expression-in-memo — 简单原始值无需使用 memo
• rerender-memo-with-default-value — 将默认的非原始值属性提升到组件外部
• rerender-memo — 将耗时操作提取到经过记忆化的组件中
• rerender-dependencies — 在 effect 中使用原始值作为依赖项
• rerender-move-effect-to-event — 将交互逻辑放入事件处理程序
• rerender-derived-state — 订阅派生的布尔值，而非原始值
• rerender-functional-setstate — 使用函数式 setState 实现稳定的回调
• rerender-lazy-state-init — 对耗时的初始值，将函数传给 useState
• rerender-transitions — 对非紧急更新使用 startTransition
• rerender-use-ref-transient-values — 使用 ref 保存频繁变化的临时值

5. useEffect 模式（MEDIUM）

• useeffect-anti-patterns — 常见错误：在 effect 中派生状态、串联 effect、通知父组件
• useeffect-alternatives — 决策树和替代方案：派生状态、key 属性、事件处理程序、useSyncExternalStore

6. 渲染性能（MEDIUM）

• rendering-animate-svg-wrapper — 为 div 包装元素添加动画，而非 SVG 元素
• rendering-content-visibility — 对长列表使用 content-visibility
• rendering-hoist-jsx — 将静态 JSX 提取到组件外部
• rendering-svg-precision — 降低 SVG 坐标精度
• rendering-conditional-render — 条件渲染使用三元运算符，而非 &&
• rendering-usetransition-loading — 加载状态优先使用 useTransition

7. JavaScript 性能优化（低-中）

• js-batch-dom-css — 批量读取/写入 DOM，避免布局抖动
• js-index-maps — 为重复查找构建 Map
• js-cache-property-access — 在循环中缓存对象属性
• js-cache-function-results — 在模块级 Map 中缓存函数结果
• js-cache-storage — 缓存 localStorage/sessionStorage 读取结果
• js-combine-iterations — 将多个 filter/map 合并到一个循环中
• js-length-check-first — 在进行开销较大的比较前检查数组长度
• js-early-exit — 在函数中提前返回
• js-hoist-regexp — 将 RegExp 的创建移到循环外
• js-min-max-loop — 使用循环而非排序来查找最小值/最大值
• js-set-map-lookups — 使用 Set/Map 进行 O(1) 查找
• js-tosorted-immutable — 使用 toSorted() 保持不可变性

8. 高级模式（低）

• advanced-init-once — 每次应用加载时仅初始化一次
• advanced-event-handler-refs — 在 refs 中存储事件处理程序
• advanced-use-latest — 使用 useEffectEvent 保持回调 refs 稳定

使用方法

阅读各个参考文件，了解详细说明和代码示例：

references/async-parallel.md
references/rerender-derived-state-no-effect.md
references/useeffect-anti-patterns.md

每个参考文件都包含：

• 简要说明其重要性
• 错误代码示例及说明
• 正确代码示例及说明
• 补充背景信息和参考资料