react-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js & React Performance Expert

Next.js & React 性能优化专家

From Vercel Engineering - 57 optimization rules prioritized by impact Philosophy: Eliminate waterfalls first, optimize bundles second, then micro-optimize.

来自Vercel Engineering - 57条按影响优先级排序的优化规则 核心理念： 先消除请求瀑布，再优化包体积，最后进行微优化。

🎯 Selective Reading Rule (MANDATORY)

🎯 选择性阅读规则（强制要求）

Read ONLY sections relevant to your task! Check the content map below and load what you need.

🔴 For performance reviews: Start with CRITICAL sections (1-2), then move to HIGH/MEDIUM.

仅阅读与你的任务相关的章节！ 查看下方内容导图，按需阅读对应部分。

🔴 性能审查场景：从CRITICAL（1-2）章节开始，再依次阅读HIGH/MEDIUM章节。

📑 Content Map

📑 内容导图

File	Impact	Rules	When to Read
`1-async-eliminating-waterfalls.md`	🔴 CRITICAL	5 rules	Slow page loads, sequential API calls, data fetching waterfalls
`2-bundle-bundle-size-optimization.md`	🔴 CRITICAL	5 rules	Large bundle size, slow Time to Interactive, First Load issues
`3-server-server-side-performance.md`	🟠 HIGH	7 rules	Slow SSR, API route optimization, server-side waterfalls
`4-client-client-side-data-fetching.md`	🟡 MEDIUM-HIGH	4 rules	Client data management, SWR patterns, deduplication
`5-rerender-re-render-optimization.md`	🟡 MEDIUM	12 rules	Excessive re-renders, React performance, memoization
`6-rendering-rendering-performance.md`	🟡 MEDIUM	9 rules	Rendering bottlenecks, virtualization, image optimization
`7-js-javascript-performance.md`	⚪ LOW-MEDIUM	12 rules	Micro-optimizations, caching, loop performance
`8-advanced-advanced-patterns.md`	🔵 VARIABLE	3 rules	Advanced React patterns, useLatest, init-once
`9-cache-components.md`	🔴 CRITICAL	4 sections	Next.js 16+ Only: `use cache` , `cacheLife` , PPR, `cacheTag`

Total: 57 rules across 8 categories

文件名称	影响等级	规则数量	适用场景
`1-async-eliminating-waterfalls.md`	🔴 CRITICAL	5条	页面加载缓慢、API请求串行、数据获取存在请求瀑布
`2-bundle-bundle-size-optimization.md`	🔴 CRITICAL	5条	包体积过大、交互时间延迟、首次加载问题
`3-server-server-side-performance.md`	🟠 HIGH	7条	SSR缓慢、API路由优化、服务端请求瀑布
`4-client-client-side-data-fetching.md`	🟡 MEDIUM-HIGH	4条	客户端数据管理、SWR模式、请求去重
`5-rerender-re-render-optimization.md`	🟡 MEDIUM	12条	重复渲染过多、React性能问题、记忆化处理
`6-rendering-rendering-performance.md`	🟡 MEDIUM	9条	渲染瓶颈、虚拟化、图片优化
`7-js-javascript-performance.md`	⚪ LOW-MEDIUM	12条	微优化、缓存、循环性能优化
`8-advanced-advanced-patterns.md`	🔵 VARIABLE	3条	高级React模式、useLatest、一次性初始化
`9-cache-components.md`	🔴 CRITICAL	4部分	仅适用于Next.js 16+： `use cache` 、 `cacheLife` 、PPR、 `cacheTag`

总计：8个分类下的57条规则

🚀 Quick Decision Tree

🚀 快速决策树

What's your performance issue?

🐌 Slow page loads / Long Time to Interactive
  → Read Section 1: Eliminating Waterfalls
  → Read Section 2: Bundle Size Optimization

📦 Large bundle size (> 200KB)
  → Read Section 2: Bundle Size Optimization
  → Check: Dynamic imports, barrel imports, tree-shaking

🖥️ Slow Server-Side Rendering
  → Read Section 3: Server-Side Performance
  → Check: Parallel data fetching, streaming

🔄 Too many re-renders / UI lag
  → Read Section 5: Re-render Optimization
  → Check: React.memo, useMemo, useCallback

🎨 Rendering performance issues
  → Read Section 6: Rendering Performance
  → Check: Virtualization, layout thrashing

🌐 Client-side data fetching problems
  → Read Section 4: Client-Side Data Fetching
  → Check: SWR deduplication, localStorage

✨ Need advanced patterns
  → Read Section 8: Advanced Patterns

🚀 **Next.js 16+ Performance (Caching & PPR)**
  → Read Section 9: Cache Components

你的性能问题是什么？

🐌 页面加载缓慢 / 交互时间过长
  → 阅读章节1：消除请求瀑布
  → 阅读章节2：包体积优化

📦 包体积过大（>200KB）
  → 阅读章节2：包体积优化
  → 检查：动态导入、桶式导入、Tree-shaking

🖥️ 服务端渲染缓慢
  → 阅读章节3：服务端性能优化
  → 检查：并行数据获取、流式渲染

🔄 重复渲染过多 / UI卡顿
  → 阅读章节5：重复渲染优化
  → 检查：React.memo、useMemo、useCallback

🎨 渲染性能问题
  → 阅读章节6：渲染性能优化
  → 检查：虚拟化布局、布局抖动

🌐 客户端数据获取问题
  → 阅读章节4：客户端数据获取优化
  → 检查：SWR请求去重、localStorage缓存

✨ 需要使用高级模式
  → 阅读章节8：高级模式

🚀 **Next.js 16+ 性能优化（缓存与PPR）**
  → 阅读章节9：缓存组件

📊 Impact Priority Guide

📊 影响优先级指南

Use this order when doing comprehensive optimization:

1️⃣ CRITICAL (Biggest Gains - Do First):
   ├─ Section 1: Eliminating Waterfalls
   │  └─ Each waterfall adds full network latency (100-500ms+)
   └─ Section 2: Bundle Size Optimization
      └─ Affects Time to Interactive and Largest Contentful Paint

2️⃣ HIGH (Significant Impact - Do Second):
   └─ Section 3: Server-Side Performance
      └─ Eliminates server-side waterfalls, faster response times

3️⃣ MEDIUM (Moderate Gains - Do Third):
   ├─ Section 4: Client-Side Data Fetching
   ├─ Section 5: Re-render Optimization
   └─ Section 6: Rendering Performance

4️⃣ LOW (Polish - Do Last):
   ├─ Section 7: JavaScript Performance
   └─ Section 8: Advanced Patterns

🔥 **MODERN (Next.js 16+):**
   └─ Section 9: Cache Components (Replaces most traditional revalidation)

全面优化时请遵循以下顺序：

1️⃣ CRITICAL（收益最大 - 优先处理）：
   ├─ 章节1：消除请求瀑布
   │  └─ 每个请求瀑布会增加完整的网络延迟（100-500ms+）
   └─ 章节2：包体积优化
      └─ 影响交互时间和最大内容绘制指标

2️⃣ HIGH（影响显著 - 其次处理）：
   └─ 章节3：服务端性能优化
      └─ 消除服务端请求瀑布，提升响应速度

3️⃣ MEDIUM（收益中等 - 第三处理）：
   ├─ 章节4：客户端数据获取优化
   ├─ 章节5：重复渲染优化
   └─ 章节6：渲染性能优化

4️⃣ LOW（细节优化 - 最后处理）：
   ├─ 章节7：JavaScript性能优化
   └─ 章节8：高级模式

🔥 **现代Next.js 16+特性：**
   └─ 章节9：缓存组件（替代大多数传统重新验证方式）

🔗 Related Skills

🔗 相关技能

Need	Skill
API design patterns	`@[skills/api-patterns]`
Database optimization	`@[skills/database-design]`
Testing strategies	`@[skills/testing-patterns]`
UI/UX design principles	`@[skills/frontend-design]`
TypeScript patterns	`@[skills/typescript-expert]`
Deployment & DevOps	`@[skills/deployment-procedures]`

需求场景	技能关联
API设计模式	`@[skills/api-patterns]`
数据库优化	`@[skills/database-design]`
测试策略	`@[skills/testing-patterns]`
UI/UX设计原则	`@[skills/frontend-design]`
TypeScript模式	`@[skills/typescript-expert]`
部署与DevOps	`@[skills/deployment-procedures]`

✅ Performance Review Checklist

✅ 性能审查清单

❌ Anti-Patterns (Common Mistakes)

❌ 反模式（常见错误）

DON'T:

❌ Use sequential
```
await
```
for independent operations
❌ Import entire libraries when you need one function
❌ Use barrel exports (
```
index.ts
```
re-exports) in app code
❌ Skip dynamic imports for large components/libraries
❌ Fetch data in useEffect without deduplication
❌ Forget to memoize expensive computations
❌ Use client components when server components work

DO:

✅ Fetch data in parallel with
```
Promise.all()
```

✅ Use dynamic imports:

const Comp = dynamic(() => import('./Heavy'))

✅ Import directly:

import { specific } from 'library/specific'

✅ Use Suspense boundaries for better UX
✅ Leverage React Server Components
✅ Measure performance before optimizing
✅ Use Next.js built-in optimizations (next/image, next/font)

禁止操作：

❌ 对独立操作使用串行
```
await
```
❌ 仅需单个函数时导入整个库
❌ 业务代码中使用桶式导出（
```
index.ts
```
重导出）
❌ 大型组件/库未使用动态导入
❌ 在useEffect中获取数据但未做去重
❌ 忘记对昂贵计算添加记忆化处理
❌ 服务端组件可满足场景下使用客户端组件

推荐操作：

✅ 使用
```
Promise.all()
```
并行获取数据

✅ 使用动态导入：

const Comp = dynamic(() => import('./Heavy'))

✅ 直接导入：

import { specific } from 'library/specific'

✅ 使用Suspense边界提升用户体验
✅ 充分利用React Server Components
✅ 优化前先测量性能指标
✅ 使用Next.js内置优化能力（next/image、next/font）

🎯 How to Use This Skill

🎯 本指南使用方法

For New Features:

新功能开发场景：

Check Section 1 & 2 while building (prevent waterfalls, keep bundle small)
Use server components by default (Section 3)
Apply memoization for expensive operations (Section 5)

开发过程中参考章节1 & 2（预防请求瀑布，控制包体积）
默认使用服务端组件（章节3）
对昂贵操作添加记忆化处理（章节5）

For Performance Reviews:

性能审查场景：

Start with Section 1 (waterfalls = biggest impact)
Then Section 2 (bundle size)
Then Section 3 (server-side)
Finally other sections as needed

从章节1开始（请求瀑布影响最大）
接着查看章节2（包体积）
然后查看章节3（服务端性能）
最后按需查看其他章节

For Debugging Slow Performance:

性能问题调试场景：

Identify the symptom (slow load, lag, etc.)
Use Quick Decision Tree above
Read relevant section
Apply fixes in priority order

定位症状（加载慢、卡顿等）
使用上方快速决策树
阅读对应章节
按优先级顺序应用修复方案

📚 Learning Path

📚 学习路径

Beginner (Focus on Critical): → Section 1: Eliminating Waterfalls → Section 2: Bundle Size Optimization

Intermediate (Add High Priority): → Section 3: Server-Side Performance → Section 5: Re-render Optimization

Advanced (Full Optimization): → All sections + Section 8: Advanced Patterns

入门级（聚焦Critical内容）： → 章节1：消除请求瀑布 → 章节2：包体积优化

进阶级（添加High Priority内容）： → 章节3：服务端性能优化 → 章节5：重复渲染优化

专家级（全面优化）： → 所有章节 + 章节8：高级模式

🔍 Validation Script

🔍 验证脚本

Script	Purpose	Command
`scripts/react_performance_checker.py`	Automated performance audit	`python scripts/react_performance_checker.py <project_path>`

脚本名称	用途	命令
`scripts/react_performance_checker.py`	自动化性能审计	`python scripts/react_performance_checker.py <project_path>`

📖 Section Details

📖 章节详情

Section 1: Eliminating Waterfalls (CRITICAL)

章节1：消除请求瀑布（CRITICAL）

Impact: Each waterfall adds 100-500ms+ latency Key Concepts: Parallel fetching, Promise.all(), Suspense boundaries, preloading

影响： 每个请求瀑布会增加100-500ms+的延迟 核心概念： 并行获取、Promise.all()、Suspense边界、预加载

Section 2: Bundle Size Optimization (CRITICAL)

章节2：包体积优化（CRITICAL）

Impact: Directly affects Time to Interactive, Largest Contentful Paint Key Concepts: Dynamic imports, tree-shaking, barrel import avoidance

影响： 直接影响交互时间和最大内容绘制指标 核心概念： 动态导入、Tree-shaking、避免桶式导入

Section 3: Server-Side Performance (HIGH)

章节3：服务端性能优化（HIGH）

Impact: Faster server responses, better SEO Key Concepts: Parallel server fetching, streaming, API route optimization

影响： 提升服务端响应速度，优化SEO 核心概念： 服务端并行获取、流式渲染、API路由优化

Section 4: Client-Side Data Fetching (MEDIUM-HIGH)

章节4：客户端数据获取优化（MEDIUM-HIGH）

Impact: Reduces redundant requests, better UX Key Concepts: SWR deduplication, localStorage caching, event listeners

影响： 减少重复请求，提升用户体验 核心概念： SWR请求去重、localStorage缓存、事件监听

Section 5: Re-render Optimization (MEDIUM)

章节5：重复渲染优化（MEDIUM）

Impact: Smoother UI, less wasted computation Key Concepts: React.memo, useMemo, useCallback, component structure

影响： 提升UI流畅度，减少无效计算 核心概念： React.memo、useMemo、useCallback、组件结构

Section 6: Rendering Performance (MEDIUM)

章节6：渲染性能优化（MEDIUM）

Impact: Better rendering efficiency Key Concepts: Virtualization, image optimization, layout thrashing

影响： 提升渲染效率 核心概念： 虚拟化、图片优化、布局抖动

Section 7: JavaScript Performance (LOW-MEDIUM)

章节7：JavaScript性能优化（LOW-MEDIUM）

Impact: Incremental improvements in hot paths Key Concepts: Loop optimization, caching, RegExp hoisting

影响： 热点路径的渐进式性能提升 核心概念： 循环优化、缓存、正则表达式提升作用域

Section 8: Advanced Patterns (VARIABLE)

章节8：高级模式（VARIABLE）

Impact: Specific use cases Key Concepts: useLatest hook, init-once patterns, event handler refs

影响： 特定场景下的优化 核心概念： useLatest钩子、一次性初始化模式、事件处理引用

🎓 Best Practices Summary

🎓 最佳实践总结

Golden Rules:

Measure first - Use React DevTools Profiler, Chrome DevTools
Biggest impact first - Waterfalls → Bundle → Server → Micro
Don't over-optimize - Focus on real bottlenecks
Use platform features - Next.js has optimizations built-in
Think about users - Real-world conditions matter

Performance Mindset:

Every
```
await
```
in sequence = potential waterfall
Every
```
import
```
= potential bundle bloat
Every re-render = wasted computation (if unnecessary)
Server components = less JavaScript to ship
Measure, don't guess

Source: Vercel Engineering Date: January 2026 Version: 1.0.0 Total Rules: 57 across 8 categories

黄金法则：

先测量 - 使用React DevTools Profiler、Chrome DevTools
先处理影响最大的问题 - 请求瀑布 → 包体积 → 服务端 → 微优化
不要过度优化 - 聚焦真实瓶颈
利用平台特性 - Next.js内置多种优化能力
以用户为中心 - 考虑真实环境下的体验

性能优化思维：

每一个串行
```
await
```
都可能产生请求瀑布
每一个
```
import
```
都可能导致包体积膨胀
每一次不必要的重复渲染都是无效计算
服务端组件可减少需要下发的JavaScript
凭数据说话，不要主观猜测

来源： Vercel Engineering 日期： 2026年1月 版本： 1.0.0 总规则数： 8个分类下的57条规则