react-best-practices

React 最佳实践

归属：vercel-labs/agent-skills 的分支。本仓库中已包含所有文档和参考资料，无需访问网络。

概览

这是一份全面的 React 和 Next.js 应用性能优化指南，包含 8 个类别的 40 多条规则。规则按影响程度排序，以指导自动重构和代码生成。

适用场景

遇到以下情况时，请参考这些指南：

• 编写新的 React 组件或 Next.js 页面
• 实现数据获取（客户端或服务端）
• 检查代码中的性能问题
• 重构现有的 React/Next.js 代码
• 优化包大小或加载时间

按优先级排序的指南

规则按影响程度排序：

优先级	类别	影响
1	消除瀑布式请求	CRITICAL
2	优化包大小	CRITICAL
3	服务端性能	HIGH
4	客户端数据获取	MEDIUM-HIGH
5	优化重新渲染	MEDIUM
6	渲染性能	MEDIUM
7	JavaScript 性能	LOW-MEDIUM
8	高级模式	LOW

快速参考

关键模式（优先应用）

消除瀑布式请求：

• 将 await 推迟到需要时再执行（移入分支）
• 对相互独立的异步操作使用 Promise.all()
• 尽早启动 Promise，尽晚等待结果
• 使用 better-all 处理部分依赖
• 使用 Suspense 边界流式传输内容

减小包大小：

• 避免从 barrel 文件导入（直接从源文件导入）
• 对大型组件使用 next/dynamic
• 延迟加载非关键的第三方库
• 根据用户意图预加载

高影响的服务端模式

• 使用 React.cache() 在每个请求内去重
• 使用 LRU 缓存实现跨请求缓存
• 尽量减少 RSC 边界上的序列化
• 通过组件组合并行获取数据

中等影响的客户端模式

• 使用 SWR 自动去重请求
• 将状态读取推迟到实际使用的位置
• 对开销较大的值使用惰性状态初始化
• 使用派生状态订阅
• 对非紧急更新应用 startTransition

渲染模式

• 为 SVG 外层包装元素添加动画，而非直接为 SVG 元素添加动画
• 对长列表使用 content-visibility: auto
• 使用内联脚本防止水合不匹配
• 使用显式条件渲染（用 ? :，而非 &&）

JavaScript 模式

• 通过类批量修改 DOM CSS
• 为重复查找构建索引映射
• 缓存重复的函数调用
• 为保持不可变性，使用 toSorted() 代替 sort()
• 比较数组前先检查长度

参考资料

包含代码示例的完整文档位于：

• references/react-performance-guidelines.md - 包含所有模式的完整指南
• references/rules/ - 按类别整理的单项规则文件

要查找特定模式，请在规则目录中使用 grep：

grep -l "suspense" references/rules/
grep -l "barrel" references/rules/
grep -l "swr" references/rules/

references/rules/ 中的规则类别

• async-* - 消除瀑布式请求的模式
• bundle-* - 包大小优化
• server-* - 服务端性能
• client-* - 客户端数据获取
• rerender-* - 重新渲染优化
• rendering-* - DOM 渲染性能
• js-* - JavaScript 微优化
• advanced-* - 高级模式