react-best-practices

React 最佳实践

面向性能敏感型产品开发的实用 React 和 Next.js 指南。

此技能将 Vercel 的 React 性能指南提炼为独立内容，因此可直接安装并在 Spellbook 中使用。

适用场景

当用户要求执行以下操作时，使用此技能：

• 构建或重构 React 组件
• 提升 Next.js 性能
• 减小打包体积
• 消除数据获取瀑布
• 修复开销较大的重复渲染
• 检查前端代码中的性能问题

优先级顺序

始终先检查优先级较高的类别。

优先级	类别	重点
1	瀑布请求	尽早启动异步任务，尽晚等待，将互不依赖的请求并行化
2	打包体积	避免使用汇总导入，延迟加载庞大的代码，按功能拆分
3	服务端性能	去重任务，尽量减少序列化，优先在服务端执行
4	客户端数据获取	对请求去重，避免冗余监听器和客户端频繁变更
5	重复渲染	减少订阅，稳定依赖，将开销较大的任务移出渲染路径
6	渲染	避免水合闪烁，减少 DOM/SVG 开销，优化长列表
7	JavaScript 热点路径	缓存重复查找，合并迭代，尽早退出
8	高级模式	针对边缘情况使用稳定的 ref 和回调模式

硬性规则

1. 优先消除瀑布请求

• 并行启动互不依赖的请求。
• 除非确实存在依赖关系，否则不要串行执行异步任务。
• 在 API 路由和服务端组件中，尽早创建 promise，并尽可能晚地等待它们。
• 在流式传输内容有助于解除渲染阻塞时，使用 Suspense 边界。

2. 控制打包体积

• 在热点路径中，优先使用直接导入，而非汇总文件。
• 对庞大或不常使用的组件使用动态导入。
• 在水合完成后，再加载分析、日志记录和其他非关键第三方代码。
• 仅在启用相关功能时加载可选模块。

3. 优先在服务端而非客户端处理任务

• 尽可能在服务端执行数据获取和繁重的转换操作。
• 尽量减少序列化到客户端组件中的数据。
• 在请求模式允许的情况下，缓存服务端重复执行的任务。

4. 控制重复渲染

• 仅订阅渲染所需的状态。
• 尽可能使用基本类型作为 effect 依赖项。
• 如果使用函数式 setState 可以移除不稳定的依赖项，就使用它。
• 延迟初始化开销较大的状态。
• 对非紧急的 UI 更新使用 startTransition。

5. 优化渲染路径

• 适当情况下，对长列表使用虚拟化或 content-visibility。
• 如果使用包装元素即可实现效果，就避免直接为开销较大的 SVG 节点添加动画。
• 只有在 JSX 确实为常量时，才将其提升到渲染路径之外。
• 渲染条件较重要时，优先使用明确的三元表达式，而不是脆弱的 && 分支。

6. 清理 JavaScript 热点

• 对重复的成员检查使用 Map 或 Set。
• 在紧密循环中缓存重复的属性访问或派生结果。
• 对性能敏感的路径，合并相邻的 filter / map 遍历。
• 尽早从分支返回，避免继续执行不必要的操作。

检查清单

检查 React 或 Next.js 代码时，请留意：

1. 是否有可以并行化的顺序异步调用
2. 热点组件中是否使用了汇总导入或大型依赖
3. 是否有可以移到服务端的数据获取逻辑
4. effect 或回调是否依赖不稳定的对象或函数
5. 是否存在可通过 Map 或 Set 优化的重复列表遍历
6. 是否出现用户可见的加载闪烁或水合闪烁

输出要求

使用此技能时，输出应当：

• 首先指出影响最大的类别
• 解释当前模式为何开销较大
• 提出最小且有效的改动
• 提供具体的验证方法，例如比较打包体积差异、使用性能分析器或检查渲染次数

参考资料

• React 文档：react.dev
• Next.js 文档：nextjs.org
• SWR 文档：swr.vercel.app
• Vercel 工程性能文章