Vercel React 最佳实践

由 Vercel 维护的 React 与 Next.js 应用全面性能优化指南。涵盖 8 个类别共 45 条规则，按影响程度排序，以指导自动化重构与代码生成。

适用场景

在以下情况下可参考本指南：

• 重构现有 React/Next.js 代码
• 编写新的 React 组件或 Next.js 页面
• 修复视觉不稳定或布局偏移（CLS）问题
• 防止从 localStorage 或 cookies 读取数据时出现闪烁
• 处理因客户端专属数据导致的水合不匹配（hydration mismatch）
• 优化字体加载（避免 FOIT/FOUT）
• 为图片及动态内容添加恰当的尺寸信息

按优先级划分的规则类别

快速查阅

1. 消除瀑布式请求（CRITICAL）

• async-defer-await — 将 await 移至实际使用它的分支中
• async-parallel — 对相互独立的操作使用 Promise.all()
• async-dependencies — 使用 better-all 处理部分依赖关系
• async-api-routes — 在 API 路由中尽早启动 Promise，延迟 await
• async-suspense-boundaries — 使用 Suspense 流式传输内容

2. 包体积优化（CRITICAL）

• bundle-barrel-imports — 直接导入模块，避免通过 barrel 文件导入
• bundle-dynamic-imports — 对重型组件使用 next/dynamic
• bundle-defer-third-party — 在水合完成后再加载分析/日志等第三方脚本
• bundle-conditional — 仅在功能启用时才加载对应模块
• bundle-preload — 在悬停（hover）或聚焦（focus）时预加载资源，提升感知速度

3. 服务端性能（HIGH）

• server-cache-react — 使用 React.cache() 实现每个请求内的去重缓存
• server-cache-lru — 使用 LRU 缓存实现跨请求缓存
• server-serialization — 最小化传递给客户端组件的数据量
• server-parallel-fetching — 重构组件结构，使多个 fetch 请求并行执行
• server-after-nonblocking — 使用 after() 执行非阻塞操作

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

• client-swr-dedup — 使用 SWR 实现自动请求去重
• client-event-listeners — 去重全局事件监听器

5. 重渲染优化（MEDIUM）

• rerender-defer-reads — 不要订阅仅在回调中使用的状态
• rerender-memo — 将耗时计算提取到 memoized 组件中
• rerender-dependencies — 在 useEffect 等副作用中使用原始类型作为依赖项
• rerender-derived-state — 订阅派生布尔值而非原始值
• rerender-functional-setstate — 使用函数式 setState 保证回调稳定性
• rerender-lazy-state-init — 对于开销较大的初始值，向 useState 传入初始化函数
• rerender-transitions — 对非紧急更新使用 startTransition

6. 渲染性能（MEDIUM）

• rendering-animate-svg-wrapper — 动画作用于 div 包裹层，而非 SVG 元素本身
• rendering-content-visibility — 对长列表使用 content-visibility
• rendering-hoist-jsx — 将静态 JSX 提取到组件外部
• rendering-svg-precision — 降低 SVG 坐标精度
• rendering-hydration-no-flicker — 使用内联 script 注入客户端专属数据，避免闪烁
• rendering-activity — 使用 Activity 组件控制显示/隐藏逻辑
• rendering-conditional-render — 条件渲染优先使用三元运算符，而非 &&

7. JavaScript 性能（LOW-MEDIUM）

• js-batch-dom-css — 通过 class 或 cssText 批量修改 CSS
• 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 — 函数中尽早 return 退出
• js-hoist-regexp — 将正则表达式创建提升至循环外部
• js-min-max-loop — 使用循环而非 sort 查找最小/最大值
• js-set-map-lookups — 使用 Set/Map 实现 O(1) 时间复杂度查找
• js-tosorted-immutable — 使用 toSorted() 保证不可变性

8. 高级模式（LOW）

• advanced-event-handler-refs — 将事件处理器存储在 ref 中
• advanced-use-latest — 使用 useLatest 获取稳定的回调 ref

如何使用

请阅读各条规则的独立文件，获取详细说明与代码示例：

rules/async-parallel.md
rules/bundle-barrel-imports.md
rules/_sections.md

每条规则文件均包含以下内容：

• 该规则重要性的简要说明
• 错误代码示例及其问题分析
• 正确代码示例及其优化原理
• 补充上下文与参考资料