Vercel React 最佳实践指南：45条性能优化规则与代码示例

react-best-practices by supercent-io/skills-template

3,200 周安装量

88 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/supercent-io/skills-template --skill react-best-practices

开发开发运维

🇨🇳中文介绍

Vercel React 最佳实践

由 Vercel 维护的 React 和 Next.js 应用程序综合性能优化指南。包含 8 个类别共 45 条规则，按影响优先级排序，以指导自动化重构和代码生成。

何时应用

在以下情况下参考这些指南：

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

按优先级划分的规则类别

优先级	类别	影响	前缀
1	消除瀑布流	关键	`async-`
2	包大小优化	关键	`bundle-`
3	服务端性能	高

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1. 消除瀑布流（关键）

async-defer-await - 将 await 移至实际使用的分支中
async-parallel - 对独立操作使用 Promise.all()
async-dependencies - 对部分依赖使用 better-all
async-api-routes - 在 API 路由中尽早启动 Promise，稍后等待
async-suspense-boundaries - 使用 Suspense 流式传输内容

2. 包大小优化（关键）

bundle-barrel-imports - 直接导入，避免使用桶文件
bundle-dynamic-imports - 对重型组件使用 next/dynamic
bundle-defer-third-party - 在注水后加载分析/日志记录
bundle-conditional - 仅在功能激活时加载模块
bundle-preload - 在悬停/聚焦时预加载以提高感知速度

3. 服务端性能（高）

server-cache-react - 使用 React.cache() 进行请求级去重
server-cache-lru - 使用 LRU 缓存进行跨请求缓存
server-serialization - 最小化传递给客户端组件的数据
server-parallel-fetching - 重构组件以实现并行获取
server-after-nonblocking - 对非阻塞操作使用 after()

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

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

5. 重新渲染优化（中）

rerender-defer-reads - 不要订阅仅在回调中使用的状态
rerender-memo - 将昂贵的工作提取到记忆化组件中
rerender-dependencies - 在 effect 中使用原始依赖项
rerender-derived-state - 订阅派生的布尔值，而非原始值
rerender-functional-setstate - 使用函数式 setState 以获得稳定的回调
rerender-lazy-state-init - 向 useState 传递函数以初始化昂贵值
rerender-transitions - 对非紧急更新使用 startTransition

6. 渲染性能（中）

rendering-animate-svg-wrapper - 动画化 div 包装器，而非 SVG 元素
rendering-content-visibility - 对长列表使用 content-visibility
rendering-hoist-jsx - 将静态 JSX 提取到组件外部
rendering-svg-precision - 降低 SVG 坐标精度
rendering-hydration-no-flicker - 对仅客户端数据使用内联脚本
rendering-activity - 使用 Activity 组件进行显示/隐藏
rendering-conditional-render - 使用三元运算符，而非 && 进行条件渲染

7. JavaScript 性能（低中）

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() 实现不可变性

8. 高级模式（低）

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

有关详细解释和代码示例，请阅读完整的编译文档：AGENTS.md

每条规则包含：

简要说明其重要性
错误代码示例及解释
正确代码示例及解释
额外上下文和参考资料

对独立操作使用 Promise.all（关键）

// ❌ 顺序执行：3 次往返
const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

// ✅ 并行执行：1 次往返
const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

避免桶文件导入（关键）

// ❌ 导入整个库（200-800ms 导入成本）
import { Check, X, Menu } from 'lucide-react'

// ✅ 仅导入所需内容
import Check from 'lucide-react/dist/esm/icons/check'
import X from 'lucide-react/dist/esm/icons/x'

对重型组件使用动态导入（关键）

// ❌ Monaco 与主块捆绑 ~300KB
import { MonacoEditor } from './monaco-editor'

// ✅ Monaco 按需加载
import dynamic from 'next/dynamic'
const MonacoEditor = dynamic(
  () => import('./monaco-editor').then(m => m.MonacoEditor),
  { ssr: false }
)

使用函数式 setState（中）

// ❌ 需要状态作为依赖项，存在陈旧闭包风险
const addItems = useCallback((newItems) => {
  setItems([...items, ...newItems])
}, [items])

// ✅ 稳定的回调，无陈旧闭包
const addItems = useCallback((newItems) => {
  setItems(curr => [...curr, ...newItems])
}, [])

必需规则（必须）

消除瀑布流：使用 Promise.all、Suspense
包优化：禁止桶导入，使用动态导入
RSC 边界：仅序列化所需数据

禁止规则（禁止）

顺序 await：不要顺序执行独立的获取操作
数组突变：使用 toSorted() 替代 sort()
React.cache 中的内联对象：导致缓存未命中

当前版本：1.0.0
最后更新：2026-01-22
支持平台：Claude、ChatGPT、Gemini
来源：vercel/agent-skills

performance-optimization：通用性能优化
state-management：状态管理

#React #Next.js #performance #optimization #vercel #waterfalls #bundle-size #RSC #frontend

🇺🇸English

Vercel React Best Practices

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

Writing new React components or Next.js pages
Implementing data fetching (client or server-side)
Reviewing code for performance issues
Refactoring existing React/Next.js code
Optimizing bundle size or load times

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Eliminating Waterfalls	CRITICAL	`async-`
2	Bundle Size Optimization	CRITICAL	`bundle-`
3	Server-Side Performance	HIGH	`server-`
4	Client-Side Data Fetching	MEDIUM-HIGH	`client-`
5	Re-render Optimization	MEDIUM	`rerender-`
6	Rendering Performance	MEDIUM	`rendering-`
7	JavaScript Performance	LOW-MEDIUM	`js-`
8	Advanced Patterns	LOW	`advanced-`

Quick Reference

1. Eliminating Waterfalls (CRITICAL)

async-defer-await - Move await into branches where actually used
async-parallel - Use Promise.all() for independent operations
async-dependencies - Use better-all for partial dependencies
async-api-routes - Start promises early, await late in API routes
async-suspense-boundaries - Use Suspense to stream content

2. Bundle Size Optimization (CRITICAL)

bundle-barrel-imports - Import directly, avoid barrel files
bundle-dynamic-imports - Use next/dynamic for heavy components
bundle-defer-third-party - Load analytics/logging after hydration
bundle-conditional - Load modules only when feature is activated
bundle-preload - Preload on hover/focus for perceived speed

3. Server-Side Performance (HIGH)

server-cache-react - Use React.cache() for per-request deduplication
server-cache-lru - Use LRU cache for cross-request caching
server-serialization - Minimize data passed to client components
server-parallel-fetching - Restructure components to parallelize fetches
server-after-nonblocking - Use after() for non-blocking operations

4. Client-Side Data Fetching (MEDIUM-HIGH)

client-swr-dedup - Use SWR for automatic request deduplication
client-event-listeners - Deduplicate global event listeners

5. Re-render Optimization (MEDIUM)

rerender-defer-reads - Don't subscribe to state only used in callbacks
rerender-memo - Extract expensive work into memoized components
rerender-dependencies - Use primitive dependencies in effects
rerender-derived-state - Subscribe to derived booleans, not raw values
rerender-functional-setstate - Use functional setState for stable callbacks
rerender-lazy-state-init - Pass function to useState for expensive values
rerender-transitions - Use startTransition for non-urgent updates

6. Rendering Performance (MEDIUM)

rendering-animate-svg-wrapper - Animate div wrapper, not SVG element
rendering-content-visibility - Use content-visibility for long lists
rendering-hoist-jsx - Extract static JSX outside components
rendering-svg-precision - Reduce SVG coordinate precision
rendering-hydration-no-flicker - Use inline script for client-only data
rendering-activity - Use Activity component for show/hide
rendering-conditional-render - Use ternary, not && for conditionals

7. JavaScript Performance (LOW-MEDIUM)

js-batch-dom-css - Group CSS changes via classes or cssText
js-index-maps - Build Map for repeated lookups
js-cache-property-access - Cache object properties in loops
js-cache-function-results - Cache function results in module-level Map
js-cache-storage - Cache localStorage/sessionStorage reads
js-combine-iterations - Combine multiple filter/map into one loop
js-length-check-first - Check array length before expensive comparison
js-early-exit - Return early from functions
js-hoist-regexp - Hoist RegExp creation outside loops

8. Advanced Patterns (LOW)

advanced-event-handler-refs - Store event handlers in refs
advanced-use-latest - useLatest for stable callback refs

How to Use

For detailed explanations and code examples, read the full compiled document: AGENTS.md

Each rule contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

Key Examples

Promise.all for Independent Operations (CRITICAL)

// ❌ Sequential: 3 round trips
const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

// ✅ Parallel: 1 round trip
const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

Avoid Barrel File Imports (CRITICAL)

// ❌ Imports entire library (200-800ms import cost)
import { Check, X, Menu } from 'lucide-react'

// ✅ Imports only what you need
import Check from 'lucide-react/dist/esm/icons/check'
import X from 'lucide-react/dist/esm/icons/x'

Dynamic Imports for Heavy Components (CRITICAL)

// ❌ Monaco bundles with main chunk ~300KB
import { MonacoEditor } from './monaco-editor'

// ✅ Monaco loads on demand
import dynamic from 'next/dynamic'
const MonacoEditor = dynamic(
  () => import('./monaco-editor').then(m => m.MonacoEditor),
  { ssr: false }
)

Use Functional setState (MEDIUM)

// ❌ Requires state as dependency, stale closure risk
const addItems = useCallback((newItems) => {
  setItems([...items, ...newItems])
}, [items])

// ✅ Stable callback, no stale closures
const addItems = useCallback((newItems) => {
  setItems(curr => [...curr, ...newItems])
}, [])