# Nextjs React Expert

> 来自 Vercel Engineering 的 React 与 Next.js 性能优化规则。适用于构建组件、优化性能、消除瀑布式请求（waterfalls）、缩减 bundle、性能代码审查与服务端/客户端优化实现。

- Skill: `misonl/nextjs-react-expert` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add misonl/nextjs-react-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/misonl/nextjs-react-expert/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: misonl (https://skillmd.com/u/misonl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/misonl/nextjs-react-expert

---


# Next.js 与 React 性能专家

> **来自 Vercel Engineering** - 按影响优先级整理的 57 条优化规则  
> **哲学：** 先消除 waterfall，再优化 bundle，最后再做微优化。

---

##  选择性阅读规则（强制）

**只阅读与当前任务相关的章节！** 先看下面内容地图，再按需加载。

> [CRITICAL]  **进行性能评审时：先看 CRITICAL（1-2），再看 HIGH/MEDIUM。**

---

##  内容地图

| 文件                                    | 影响等级            | 规则数 | 阅读时机                                                       |
| --------------------------------------- | ------------------- | ------ | -------------------------------------------------------------- |
| `1-async-eliminating-waterfalls.md`     | [CRITICAL]  **CRITICAL**     | 5 条   | 页面加载慢、串行 API 调用、数据获取 waterfall（瀑布式请求）    |
| `2-bundle-bundle-size-optimization.md`  | [CRITICAL]  **CRITICAL**     | 5 条   | bundle 体积过大、TTI 慢、首屏加载问题                          |
| `3-server-server-side-performance.md`   |  **HIGH**         | 7 条   | SSR 缓慢、API Route 优化、服务端 waterfall（瀑布式请求）       |
| `4-client-client-side-data-fetching.md` | [SUGGESTION]  **MEDIUM-HIGH**  | 4 条   | 客户端数据管理、SWR 模式、请求去重                             |
| `5-rerender-re-render-optimization.md`  | [SUGGESTION]  **MEDIUM**       | 12 条  | 过度重渲染、React 性能、memoization                            |
| `6-rendering-rendering-performance.md`  | [SUGGESTION]  **MEDIUM**       | 9 条   | 渲染瓶颈、虚拟列表、图像优化                                   |
| `7-js-javascript-performance.md`        |  **LOW-MEDIUM**   | 12 条  | 微优化、缓存、循环性能                                         |
| `8-advanced-advanced-patterns.md`       |  **VARIABLE**     | 3 条   | 高级 React 模式、useLatest、init-once                          |

**总计：8 大类，共 57 条规则**

---

##  快速决策树

**你的性能问题属于哪一类？**

```
 页面加载慢 / 可交互时间（Time to Interactive，TTI）长
  -> 阅读第 1 节：消除瀑布式请求（Eliminating Waterfalls）
  -> 阅读第 2 节：包体积优化（Bundle Size Optimization）

 bundle 体积过大（> 200KB）
  -> 阅读第 2 节：包体积优化（Bundle Size Optimization）
  -> 检查：动态导入（dynamic imports）、桶文件导入（barrel imports）、tree-shaking

 服务端渲染慢（SSR）
  -> 阅读第 3 节：服务端性能（Server-Side Performance）
  -> 检查：并行数据获取、streaming

[RUN]  重渲染过多 / UI 卡顿
  -> 阅读第 5 节：重渲染优化（Re-render Optimization）
  -> 检查：React.memo、useMemo、useCallback

 渲染性能问题
  -> 阅读第 6 节：渲染性能（Rendering Performance）
  -> 检查：虚拟化、layout thrashing

 客户端数据获取问题
  -> 阅读第 4 节：客户端数据获取（Client-Side Data Fetching）
  -> 检查：SWR 去重（deduplication）、localStorage

 需要高级模式
  -> 阅读第 8 节：高级模式（Advanced Patterns）
```

---

##  影响优先级指南

**进行全量优化时，按以下顺序：**

```
1⃣ CRITICAL（收益最大，先做）：
   +- 第 1 节：消除瀑布式请求（Eliminating Waterfalls）
   |  +- 每个 waterfall 都会引入完整网络延迟（100-500ms+）
   +- 第 2 节：包体积优化（Bundle Size Optimization）
      +- 直接影响可交互时间（Time to Interactive）与最大内容绘制（LCP）

2⃣ HIGH（显著收益，第二步）：
   +- 第 3 节：服务端性能（Server-Side Performance）
      +- 消除服务端 waterfall，提升响应速度

3⃣ MEDIUM（中等收益，第三步）：
   +- 第 4 节：客户端数据获取（Client-Side Data Fetching）
   +- 第 5 节：重渲染优化（Re-render Optimization）
   +- 第 6 节：渲染性能（Rendering Performance）

4⃣ LOW（打磨项，最后做）：
   +- 第 7 节：JavaScript 性能（JavaScript Performance）
   +- 第 8 节：高级模式（Advanced Patterns）
```

---

##  相关技能

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

---

## [OK]  性能评审清单

上线前检查：

**Critical（必须修复）：**

- [ ] 无串行数据获取（waterfall 瀑布式请求已消除）
- [ ] 主 bundle（包）< 200KB
- [ ] 应用代码中无 barrel imports（桶文件导入）
- [ ] 大组件已使用动态导入（dynamic imports）
- [ ] 可并行的数据获取已并行化

**High Priority（高优先级）：**

- [ ] 合适场景使用 Server Components（服务端组件）
- [ ] API Routes（接口路由）已优化（无 N+1 查询）
- [ ] 数据获取路径配置了 Suspense（挂起）边界
- [ ] 可静态生成内容已采用 SSG（静态生成）

**Medium Priority（中优先级）：**

- [ ] 高开销计算已 memoize（记忆化）
- [ ] 大列表（>100 项）已虚拟化
- [ ] 图片通过 `next/image` 优化
- [ ] 无不必要重渲染

**Low Priority（打磨）：**

- [ ] 热路径循环已优化
- [ ] RegExp 已提升至循环外
- [ ] 循环内属性访问已缓存

---

## [FAIL]  反模式

**不要这样做（DON'T）：**

- [FAIL]  对互不依赖任务使用串行 `await`
- [FAIL]  只用一个函数却导入整个库
- [FAIL]  在应用代码中使用 barrel exports（`index.ts` 重导出）
- [FAIL]  大组件/大库不做动态导入（dynamic imports）
- [FAIL]  `useEffect` 拉数据却不做去重
- [FAIL]  高开销计算不做 memoization（记忆化）
- [FAIL]  本可用 server component 却硬用 client component

**推荐做法（DO）：**

- [OK]  使用 `Promise.all()` 并行获取数据
- [OK]  使用动态导入：`const Comp = dynamic(() => import('./Heavy'))`
- [OK]  精确导入：`import { specific } from 'library/specific'`
- [OK]  用 Suspense（挂起）边界提升体验
- [OK]  利用 React Server Components（服务端组件）
- [OK]  优化前先测量
- [OK]  使用 Next.js 内建优化（`next/image`、`next/font`）

---

##  如何使用本技能

### 新功能开发场景：

1. 开发阶段优先检查 **Section 1 & 2**（预防 waterfall 瀑布式请求，控制 bundle 包体积）
2. 默认优先考虑 server components（服务端组件，Section 3）
3. 对高开销操作应用 memoization（记忆化，Section 5）

### 性能评审场景：

1. 从 **Section 1** 开始（waterfall 影响最大）
2. 再看 **Section 2**（bundle 体积）
3. 再看 **Section 3**（服务端性能）
4. 最后按需补充其他章节

### 慢性能排障场景：

1. 先识别症状（慢加载、卡顿等）
2. 使用上方快速决策树
3. 阅读对应章节
4. 按优先级顺序落地修复

---

##  学习路径

**初级（先抓关键）：**  
-> 第 1 节：消除瀑布式请求（Eliminating Waterfalls）  
-> 第 2 节：包体积优化（Bundle Size Optimization）

**中级（补齐高优先级）：**  
-> 第 3 节：服务端性能（Server-Side Performance）  
-> 第 5 节：重渲染优化（Re-render Optimization）

**高级（全量优化）：**  
-> 全章节 + 第 8 节：高级模式（Advanced Patterns）

---

##  验证脚本

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

---

##  章节说明

### 第 1 节：消除瀑布式请求（CRITICAL）

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

### 第 2 节：包体积优化（CRITICAL）

**影响：** 直接影响 TTI（可交互时间）、LCP（最大内容绘制）  
**关键概念：** 动态导入、tree-shaking（摇树优化）、避免 barrel imports（桶文件导入）

### 第 3 节：服务端性能（HIGH）

**影响：** 更快服务端响应、更好 SEO  
**关键概念：** 服务端并行获取、streaming、API Route（接口路由）优化

### 第 4 节：客户端数据获取（MEDIUM-HIGH）

**影响：** 减少冗余请求、提升 UX（用户体验）  
**关键概念：** SWR 去重、localStorage 缓存、事件监听

### 第 5 节：重渲染优化（MEDIUM）

**影响：** UI 更流畅、减少无效计算  
**关键概念：** `React.memo`、`useMemo`、`useCallback`、组件结构

### 第 6 节：渲染性能（MEDIUM）

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

### 第 7 节：JavaScript 性能（LOW-MEDIUM）

**影响：** 热路径增量优化  
**关键概念：** 循环优化、缓存、RegExp 提升

### 第 8 节：高级模式（VARIABLE）

**影响：** 特定场景收益明显  
**关键概念：** `useLatest` hook（钩子）、init-once 模式、event handler refs（事件处理引用）

---

##  最佳实践总结

**黄金法则：**

1. **先测量再优化** - 使用 React DevTools Profiler、Chrome DevTools
2. **先做高收益项** - Waterfalls（瀑布式请求）-> Bundle（包体积）-> Server（服务端）-> Micro（微优化）
3. **避免过度优化** - 聚焦真实瓶颈
4. **善用平台能力** - Next.js 内建大量优化
5. **关注真实用户环境** - 不是只看本机结果

**性能思维：**

- 串行 `await` 可能就是 waterfall（瀑布式请求）
- 每个 `import` 都可能引入 bundle（包体积）膨胀
- 每次无意义重渲染都是浪费
- server components（服务端组件）能减少下发 JS
- 用数据说话，不靠猜测

---

**来源：** Vercel Engineering  
**日期：** 2026 年 1 月  
**版本：** 1.0.0  
**规则总数：** 57 条，分 8 大类