Vercel React Best Practices

核心用法

该技能为Vercel官方维护的React/Next.js性能优化指南，包含62条结构化规则，按影响优先级分为8大类别。开发者可在代码编写、审查、重构阶段调用，覆盖从关键渲染路径到微优化的全链路场景。

关键触发场景：

• 新建React组件或Next.js页面时自动校验
• 数据获取层（客户端/服务端）架构设计
• 性能瓶颈诊断与Bundle体积优化
• 代码审查阶段的自动化规则引用

规则体系：

| 优先级 | 类别 | 核心策略 |

|--------|------|----------|

| P1 | 瀑布流消除 | `Promise.all`并行化、Suspense流式渲染 |

| P2 | Bundle优化 | 避免barrel导入、`next/dynamic`懒加载 |

| P3 | 服务端性能 | React.cache()去重、RSC序列化精简 |

| P4-P8 | 客户端/渲染/JS/高级模式 | SWR去重、useMemo策略、DOM批处理等 |

每条规则遵循统一结构：问题说明 → 错误代码 → 正确代码 → 深层原理，支持规则级精读或快速索引。

显著优点

1. 来源权威性：Vercel作为Next.js开发主体，规则与框架演进同步，规避社区方案滞后风险
2. 工程化分级：CRITICAL/HIGH/MEDIUM/LOW四级优先级，资源紧张时精准投入高ROI优化点
3. 可执行性强：62条规则均含代码对照，拒绝抽象原则，直接映射到代码变更
4. 覆盖维度完整：从网络层（瀑布流）到渲染层（RSC/RSC hydratio）再到JS运行时（Map缓存、循环优化），形成性能优化闭环

潜在局限

1. Next.js专属倾向：虽名为React最佳实践，部分规则（next/dynamic、after()、React.cache）依赖Next.js/App Router特性，纯React项目需筛选适用
2. 规则粒度较细：62条规则可能造成决策疲劳，需结合AGENTS.md全盘文档做统筹规划
3. 生态锁定风险：better-all等工具引用、Vercel边缘运行时优化建议，存在Vendor-specific隐含假设

适合人群

• Next.js应用开发者：尤其使用App Router、Server Components的现代化栈团队
• 性能专项负责人：需系统性清单排查渲染瀑布、Bundle体积、CLS/TTFB等指标
• 代码审查者：为团队建立可量化的React代码质量标准

常规风险

1. 过度优化陷阱：LOW优先级规则（如js-hoist-regexp）在大多数场景收益有限，盲目应用反增代码复杂度
2. Suspense边界误用：async-suspense-boundaries需配合Streaming SSR环境，传统CSR应用可能引入hydration不匹配
3. 缓存策略冲突：server-cache-react与自定义LRU缓存混用时，需明确请求级/跨请求缓存边界，避免内存泄漏或数据过期

核心用法

本 Skill 是一套面向 React 和 Next.js 开发者的系统性性能优化指南，由 Vercel Engineering 团队官方维护。其核心用法体现在代码编写、审查和重构三个场景中：在编写新组件时，可直接参考规则避免常见性能陷阱；在代码审查环节，可作为检查清单识别潜在问题；在重构遗留代码时，提供按优先级排序的优化路径。

指南采用「触发词 + 规则前缀」的智能化设计，8 大类别共 62 条规则均有明确优先级标注（CRITICAL/HIGH/MEDIUM/LOW）。开发者可通过 async-、bundle-、server- 等前缀快速定位相关规则，每条规则均包含错误示例、正确实现及详细原理解释，形成完整的知识闭环。

显著优点

来源权威性无可比拟。作为 Next.js 官方平台的工程团队出品，规则直接源于 Vercel 平台海量应用的实战经验，与 React 核心团队保持紧密协作，确保建议与最新框架演进同步。

体系化程度高。不同于零散的博客文章，本指南构建了从网络层（消除请求瀑布流）到渲染层（重渲染优化）再到 JavaScript 执行层（底层性能技巧）的完整知识图谱，62 条规则覆盖现代 React 应用性能优化的全链路。

实战导向明确。每条规则均标注影响等级（如 CRITICAL 级别的 Bundle Size Optimization），并提供可直接落地的代码片段。特别是对 Next.js App Router、Server Components、Suspense 等新特性的优化建议，具有极强的时效性和实用性。

零安全负担。纯文档型 Skill，无可执行代码、无外部依赖、无网络调用，可完全隔离于敏感环境使用。

潜在局限

框架绑定较深。大量规则围绕 Next.js 特有 API（如 next/dynamic、React Server Components）设计，对纯 Create React App 或 Vite 项目的适用性有所折损，非 Next.js 用户需进行语境转换。

规则粒度较细。62 条规则覆盖全面但也带来认知负荷，新手开发者可能陷入「优化过度」陷阱，在简单场景套用复杂模式反而增加维护成本。

更新依赖官方节奏。React 生态迭代迅速（如 React 19 的新特性），规则集更新可能滞后于框架最新版本，需关注 Vercel 官方仓库同步。

缺乏自动化能力。作为文档型指南，无法直接集成到 CI/CD 流水线进行自动检测，需配合 ESLint 插件或其他工具实现规则自动化执行。

适合人群

本 Skill 主要面向三类开发者：一是追求极致性能的 Next.js 全栈工程师，尤其是处理高流量、SEO 敏感的生产级应用；二是需要进行代码审查的技术负责人，可将其作为团队性能基线的标准参考；三是希望系统提升 React 性能认知的中高级前端开发者，规则背后的原理解释具有极高学习价值。

对于刚接触 React 的新手，建议优先理解 CRITICAL 和 HIGH 级别规则，避免在低优先级优化上过度投入。

使用风险

作为纯文档型 Skill，无常规安全风险如代码注入、数据泄露等。但需注意以下使用层面的风险：

性能优化反模式风险。部分规则（如过度使用 useMemo、不必要的代码分割）在特定场景下可能适得其反，建议结合 React DevTools Profiler 等工具验证实际效果，避免「为了优化而优化」。

团队认知对齐成本。引入 62 条规则可能增加团队学习成本，建议渐进式采纳，优先实施 CRITICAL 级别规则，建立性能监控基线后再逐步深入。

版本兼容性风险。部分规则针对 Next.js 14+ 的 App Router 设计，若团队仍使用 Pages Router 或旧版 React，需甄别规则适用性，避免直接套用导致运行时错误。