vercel-react-best-practices（Vercel React 最佳实践）

Vercel React 最佳实践

面向 React 和 Next.js 应用的性能优化指南，由 Vercel 维护。包含 8 大类共 57 条规则，按影响程度排序，用于指导自动化重构与代码生成。

何时使用

在以下场景参考本指南：

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

规则类别与优先级

速查

1. 消除瀑布请求（关键）

• async-defer-await - 将 await 移到实际使用的分支内
• async-parallel - 独立操作用 Promise.all()
• async-dependencies - 部分依赖用 better-all
• async-api-routes - API 路由中早创建 promise、晚 await
• async-suspense-boundaries - 用 Suspense 流式输出内容

2. 打包体积优化（关键）

• bundle-barrel-imports - 直接导入，避免 barrel 文件
• bundle-dynamic-imports - 重型组件用 next/dynamic
• bundle-defer-third-party - hydration 后再加载分析/日志
• bundle-conditional - 仅在该功能激活时加载模块
• bundle-preload - hover/focus 时预加载，提升感知速度

3. 服务端性能（高）

• server-auth-actions - Server Actions 像 API 路由一样做鉴权
• server-cache-react - 用 React.cache() 做请求级去重
• server-cache-lru - 跨请求缓存用 LRU
• server-dedup-props - 避免 RSC props 重复序列化
• server-serialization - 传给 Client 组件的数据尽量精简
• server-parallel-fetching - 调整组件结构以并行请求
• server-after-nonblocking - 非阻塞操作用 after()

4. 客户端数据获取（中高）

• client-swr-dedup - 用 SWR 自动请求去重
• client-event-listeners - 全局事件监听去重
• client-passive-event-listeners - 滚动用 passive 监听
• client-localstorage-schema - localStorage 数据版本化并精简

5. 重渲染优化（中）

• rerender-defer-reads - 不在仅用于回调的 state 上订阅
• rerender-memo - 昂贵逻辑抽到 memo 组件
• rerender-memo-with-default-value - 非原始类型默认 props 提升
• rerender-dependencies - effect 依赖用原始类型
• rerender-derived-state - 订阅派生布尔值而非原始值
• rerender-derived-state-no-effect - 在 render 中派生，不用 effect
• rerender-functional-setstate - 用函数式 setState 保持回调稳定
• rerender-lazy-state-init - 昂贵初始值用函数传 useState
• rerender-simple-expression-in-memo - 简单原始类型不必 memo
• rerender-move-effect-to-event - 交互逻辑放进事件处理
• rerender-transitions - 非紧急更新用 startTransition
• rerender-use-ref-transient-values - 瞬态频繁值用 ref

6. 渲染性能（中）

• 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-hydration-suppress-warning - 预期不一致时压制警告
• rendering-activity - 显隐用 Activity 组件
• rendering-conditional-render - 条件渲染用三元而非 &&
• rendering-usetransition-loading - 加载态优先 useTransition

7. JavaScript 性能（低中）

• 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 - 昂贵比较前先查 length
• js-early-exit - 函数内尽早 return
• js-hoist-regexp - RegExp 提到循环外
• js-min-max-loop - min/max 用循环代替 sort
• js-set-map-lookups - O(1) 查找用 Set/Map
• js-tosorted-immutable - 不可变排序用 toSorted()

8. 高级模式（低）

• advanced-event-handler-refs - 事件处理存 ref
• advanced-init-once - 应用级只初始化一次
• advanced-use-latest - useLatest 稳定回调 ref

使用方式

阅读单条规则文件获取说明与示例：

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

每条规则包含：为何重要、错误示例、正确示例、补充说明与参考。

完整展开版见 rules/ 目录下各 .md 规则文件。