Vercel React Best Practices 是一份面向 React 与 Next.js 应用的综合性性能优化指南,由 Vercel 维护。它包含 70 条规则,分布在 8 个类别中,并按影响程度划分优先级,用于指导自动化重构与代码生成。
适用时机
在以下场景可参考这些指南:
- 编写新的 React 组件或 Next.js 页面
- 实现数据获取(客户端或服务端)
- 审查代码中的性能问题
- 重构已有的 React/Next.js 代码
- 优化包体积或加载时间
规则类别与优先级
按优先级从高到低排列:
- 消除请求瀑布(CRITICAL,前缀 async-)
- 包体积优化(CRITICAL,前缀 bundle-)
- 服务端性能(HIGH,前缀 server-)
- 客户端数据获取(MEDIUM-HIGH,前缀 client-)
- 重渲染优化(MEDIUM,前缀 rerender-)
- 渲染性能(MEDIUM,前缀 rendering-)
- JavaScript 性能(LOW-MEDIUM,前缀 js-)
- 高级模式(LOW,前缀 advanced-)
快速参考
- 消除请求瀑布(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 流式传输内容
- 包体积优化(CRITICAL)
- bundle-barrel-imports:直接导入,避免 barrel 文件
- bundle-analyzable-paths:优先使用可静态分析的导入与文件系统路径,避免宽泛的打包与追踪
- bundle-dynamic-imports:对重型组件使用 next/dynamic
- bundle-defer-third-party:在水合之后再加载分析/日志
- bundle-conditional:仅在功能被激活时加载模块
- bundle-preload:在悬停/聚焦时预加载以提升感知速度
- 服务端性能(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()
- 客户端数据获取(MEDIUM-HIGH)
- client-swr-dedup:使用 SWR 实现自动请求去重
- client-event-listeners:去重全局事件监听器
- client-passive-event-listeners:对滚动使用被动监听器
- client-localstorage-schema:对 localStorage 数据做版本管理并最小化
- 重渲染优化(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:不要在组件内部定义组件
- 渲染性能(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
- 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:将非关键工作推迟到浏览器空闲时间
- 高级模式(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。