react-best-practices

Next.js & React 性能专家

来自 Vercel Engineering - 按影响排序的 57 条优化规则 理念： 优先消除瀑布流，其次优化包体积，最后进行微优化。

---

🎯 选择性阅读规则（必须遵守）

只阅读与你的任务相关的章节！ 查看下方的内容地图，并按需加载。

🔴 进行性能评审时：先从关键章节（1-2）开始，然后再看高优先级和中优先级章节。

---

📑 内容地图

文件	影响	规则	阅读时机
1-async-eliminating-waterfalls.md	🔴 关键	5 条规则	页面加载缓慢、API 调用串行、数据获取瀑布流
2-bundle-bundle-size-optimization.md	🔴 关键	5 条规则	包体积过大、交互时间过长、首次加载问题
3-server-server-side-performance.md	🟠 高	7 条规则	SSR 缓慢、API 路由优化、服务端瀑布流
4-client-client-side-data-fetching.md	🟡 中高	4 条规则	客户端数据管理、SWR 模式、去重
5-rerender-re-render-optimization.md	🟡 中	12 条规则	过度重新渲染、React 性能、记忆化
6-rendering-rendering-performance.md	🟡 中	9 条规则	渲染瓶颈、虚拟化、图像优化
7-js-javascript-performance.md	⚪ 中低	12 条规则	微优化、缓存、循环性能
8-advanced-advanced-patterns.md	🔵 可变	3 条规则	高级 React 模式、useLatest、仅初始化一次
9-cache-components.md	🔴 关键	4 个章节	仅适用于 Next.js 16+：use cache、cacheLife、PPR、cacheTag

总计：8 个类别中的 57 条规则

---

🚀 快速决策树

你的性能问题是什么？

🐌 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️⃣ 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)

---

🔗 相关技能

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

---

✅ 性能评审检查清单

发布到生产环境前：

关键（必须修复）：

• 没有串行数据获取（已消除瀑布流）
• 主包体积 < 200KB
• 应用代码中没有 barrel 导入
• 大型组件使用了动态导入
• 尽可能并行获取数据

高优先级：

• 在适当情况下使用服务端组件
• 已优化 API 路由（没有 N+1 查询）
• 数据获取使用了 Suspense 边界
• 尽可能使用静态生成

中优先级：

• 已对开销大的计算进行记忆化
• 列表渲染已虚拟化（如果超过 100 项）
• 使用 next/image 优化图像
• 没有不必要的重新渲染

低优先级（润色）：

• 已优化热路径循环
• 已将 RegExp 模式提升到循环外
• 已在循环中缓存属性访问

---

❌ 反模式（常见错误）

不要：

• ❌ 对相互独立的操作使用顺序 await
• ❌ 只需要一个函数时导入整个库
• ❌ 在应用代码中使用 barrel exports（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）

---

🎯 如何使用这项技能

开发新功能时：

1. 构建时查看第 1 和第 2 节（避免瀑布式请求，保持包体积小）
2. 默认使用服务器组件（第 3 节）
3. 对开销大的操作应用记忆化（第 5 节）

进行性能审查时：

1. 从第 1 节开始（瀑布式请求影响最大）
2. 然后查看第 2 节（包体积）
3. 接着查看第 3 节（服务器端）
4. 最后根据需要查看其他章节

调试性能缓慢的问题时：

1. 确定症状（加载缓慢、卡顿等）
2. 使用上方的快速决策树
3. 阅读相关章节
4. 按优先级顺序应用修复

---

📚 学习路径

初级（重点关注关键内容）： → 第 1 节：消除瀑布式请求 → 第 2 节：优化包体积

中级（增加高优先级内容）： → 第 3 节：服务器端性能 → 第 5 节：优化重新渲染

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

---

🔍 验证脚本

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

---

📖 章节详情

第 1 节：消除瀑布式请求（关键）

**影响：**每个瀑布式请求都会增加 100-500ms 以上的延迟 **关键概念：**并行获取、Promise.all()、Suspense 边界、预加载

第 2 节：优化包体积（关键）

**影响：**直接影响交互时间和最大内容绘制时间 **关键概念：**动态导入、摇树优化、避免通过 barrel 导入

第 3 节：服务器端性能（高）

**影响：**更快的服务器响应，更好的 SEO **关键概念：**服务器端并行获取、流式传输、优化 API 路由

第 4 节：客户端数据获取（中高）

**影响：**减少冗余请求，改善用户体验 **关键概念：**SWR 去重、localStorage 缓存、事件监听器

第 5 节：优化重新渲染（中）

**影响：**界面更流畅，减少无用计算 **关键概念：**React.memo、useMemo、useCallback、组件结构

第 6 节：渲染性能（中）

**影响：**提升渲染效率 **关键概念：**虚拟化、图像优化、布局抖动

第 7 节：JavaScript 性能（低至中）

**影响：**改善热点路径的性能 **关键概念：**循环优化、缓存、提升 RegExp

第 8 节：高级模式（视情况而定）

**影响：**针对特定用例 **关键概念：**useLatest hook、仅初始化一次的模式、事件处理器引用

---

🎓 最佳实践总结

黄金法则：

1. 先测量 - 使用 React DevTools Profiler、Chrome DevTools
2. 先解决影响最大的问题 - 瀑布流 → Bundle → 服务端 → 微优化
3. 不要过度优化 - 关注实际瓶颈
4. 使用平台功能 - Next.js 内置了优化功能
5. 为用户着想 - 真实环境下的情况很重要

性能思维：

• 顺序执行的每个 await = 潜在的瀑布流
• 每个 import = 潜在的 Bundle 臃肿
• 每次重新渲染 = 浪费计算（如果没有必要）
• 服务端组件 = 需要发送的 JavaScript 更少
• 测量，不要猜测

---

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