SuperAPI AI 工具集

vercel-react-best-practices

编程与开发

查看项目

更新于 10-16 07:30

技能介绍

Vercel React Best Practices 是一份面向 React 与 Next.js 应用的综合性性能优化指南,由 Vercel 维护。它包含 70 条规则,分布在 8 个类别中,并按影响程度划分优先级,用于指导自动化重构与代码生成。

适用时机

在以下场景可参考这些指南:

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

规则类别与优先级

按优先级从高到低排列:

  1. 消除请求瀑布(CRITICAL,前缀 async-)
  2. 包体积优化(CRITICAL,前缀 bundle-)
  3. 服务端性能(HIGH,前缀 server-)
  4. 客户端数据获取(MEDIUM-HIGH,前缀 client-)
  5. 重渲染优化(MEDIUM,前缀 rerender-)
  6. 渲染性能(MEDIUM,前缀 rendering-)
  7. JavaScript 性能(LOW-MEDIUM,前缀 js-)
  8. 高级模式(LOW,前缀 advanced-)

快速参考

  1. 消除请求瀑布(CRITICAL)
  • async-cheap-condition-before-await:在 await 标志或远程值之前先检查低成本的同步条件
  • async-defer-await:将 await 移入实际使用的分支
  • async-parallel:对独立操作使用 Promise.all()
  • async-dependencies:使用 better-all 处理部分依赖
  • async-api-routes:在 API 路由中提早启动 promise、延迟 await
  • async-suspense-boundaries:使用 Suspense 流式传输内容
  1. 包体积优化(CRITICAL)
  • bundle-barrel-imports:直接导入,避免 barrel 文件
  • bundle-analyzable-paths:优先使用可静态分析的导入与文件系统路径,避免宽泛的打包与追踪
  • bundle-dynamic-imports:对重型组件使用 next/dynamic
  • bundle-defer-third-party:在水合之后再加载分析/日志
  • bundle-conditional:仅在功能被激活时加载模块
  • bundle-preload:在悬停/聚焦时预加载以提升感知速度
  1. 服务端性能(HIGH)
  • server-auth-actions:像对待 API 路由一样对服务端 action 进行鉴权
  • server-cache-react:使用 React.cache() 做每请求去重
  • server-cache-lru:使用 LRU 缓存做跨请求缓存
  • server-dedup-props:避免 RSC props 中的重复序列化
  • server-hoist-static-io:将静态 I/O(字体、logo)提升到模块级别
  • server-no-shared-module-state:避免在 RSC/SSR 中使用模块级可变请求状态
  • server-serialization:最小化传递给客户端组件的数据
  • server-parallel-fetching:重构组件以并行化获取
  • server-parallel-nested-fetching:在 Promise.all 中为每个条目串联嵌套获取
  • server-after-nonblocking:对非阻塞操作使用 after()
  1. 客户端数据获取(MEDIUM-HIGH)
  • client-swr-dedup:使用 SWR 实现自动请求去重
  • client-event-listeners:去重全局事件监听器
  • client-passive-event-listeners:对滚动使用被动监听器
  • client-localstorage-schema:对 localStorage 数据做版本管理并最小化
  1. 重渲染优化(MEDIUM)
  • rerender-defer-reads:不要订阅仅在回调中使用的状态
  • rerender-memo:将高开销工作提取到已记忆化组件
  • rerender-memo-with-default-value:将非基元默认 props 提升
  • rerender-dependencies:在 effect 中使用基元依赖
  • rerender-derived-state:订阅派生布尔值而非原始值
  • rerender-derived-state-no-effect:在渲染期间派生状态,而非在 effect 中
  • rerender-functional-setstate:使用函数式 setState 保持回调稳定
  • rerender-lazy-state-init:对高开销值向 useState 传入函数
  • rerender-simple-expression-in-memo:避免对简单基元使用 memo
  • rerender-split-combined-hooks:拆分具有独立依赖的 hooks
  • rerender-move-effect-to-event:将交互逻辑放入事件处理器
  • rerender-transitions:对非紧急更新使用 startTransition
  • rerender-use-deferred-value:延迟高开销渲染以保持输入响应
  • rerender-use-ref-transient-values:对瞬态高频值使用 ref
  • rerender-no-inline-components:不要在组件内部定义组件
  1. 渲染性能(MEDIUM)
  • rendering-animate-svg-wrapper:为 div 包装器添加动画,而非 SVG 元素
  • rendering-content-visibility:对长列表使用 content-visibility
  • rendering-hoist-jsx:将静态 JSX 提取到组件外
  • rendering-svg-precision:降低 SVG 坐标精度
  • rendering-hydration-no-flicker:对仅客户端数据使用内联脚本
  • rendering-hydration-suppress-warning:抑制预期的水合不匹配
  • rendering-activity:使用 Activity 组件进行显示/隐藏
  • rendering-conditional-render:条件渲染使用三元表达式而非 &&
  • rendering-usetransition-loading:加载状态优先使用 useTransition
  • rendering-resource-hints:使用 React DOM 资源提示进行预加载
  • rendering-script-defer-async:在 script 标签上使用 defer 或 async
  1. JavaScript 性能(LOW-MEDIUM)
  • js-batch-dom-css:通过类名或 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:从函数中提前返回
  • js-hoist-regexp:将 RegExp 创建提升到循环外
  • js-min-max-loop:用循环求最小/最大值而非 sort
  • js-set-map-lookups:使用 Set/Map 进行 O(1) 查找
  • js-tosorted-immutable:使用 toSorted() 保证不可变性
  • js-flatmap-filter:使用 flatMap 在一次遍历中完成映射与过滤
  • js-request-idle-callback:将非关键工作推迟到浏览器空闲时间
  1. 高级模式(LOW)
  • advanced-effect-event-deps:不要将 useEffectEvent 的结果放入 effect 依赖
  • advanced-event-handler-refs:将事件处理器存储在 ref 中
  • advanced-init-once:每次应用加载只初始化一次
  • advanced-use-latest:使用 useLatest 保持回调 ref 稳定

如何使用

阅读各条规则文件以获取详细说明和代码示例,例如:

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

每个规则文件包含:

  • 该规则为何重要的简要说明
  • 错误代码示例及解释
  • 正确代码示例及解释
  • 补充背景与参考

完整汇总文档

如需包含所有规则展开内容的完整指南,请参阅 AGENTS.md。