Vercel React 最佳实践：8 大分类的 React/Next.js 性能优化规则体系解析

导读

本文基于 open-slide 仓库内嵌的.agents/skills/vercel-react-best-practices/技能规则库，系统解析 Vercel Engineering 维护的 React/Next.js 性能优化知识体系。该规则库将性能优化工作拆解为 8 个按影响优先级排序的分类，共约 70 条规则，每条规则均提供错误与正确代码对照。读完本文，你将掌握这套分类体系的结构、优先级依据、文件名前缀约定，以及每个分类下的代表性优化手法，可直接用于编写、审查与重构 React/Next.js 代码时的性能排查。

一、规则库是什么：面向 Agent 的性能优化知识体系

该技能位于仓库的.agents/skills/vercel-react-best-practices/目录，其元数据（见 SKILL.md）显示：名称为vercel-react-best-practices，作者为 Vercel，版本 1.0.0，采用 MIT 许可。它的定位非常明确——当编写、审查或重构 React/Next.js 代码时，用于确保最优性能模式，触发场景包括 React 组件、Next.js 页面、数据获取、bundle 优化与性能改进。

该规则库由三部分构成：

• rules/目录：规则源文件，其中_sections.md是分类索引（即本文主体）、_template.md是新建规则的模板，其余 70 个文件为具体规则（如async-parallel.md、bundle-barrel-imports.md）；
• AGENTS.md：由全部规则编译生成的完整文档，含 8 大章节与全部代码示例；
• README.md与metadata.json：维护说明与文档元数据。

根据 SKILL.md 的说明，这份文档"主要面向 Agent 和 LLM"，用于在自动化工作流中保持一致性的代码生成与重构，人类开发者同样可以受益。

二、8 大分类总览：优先级、影响级别与文件名前缀

_sections.md的核心作用，是定义所有分类的标题、排序、影响级别与描述。其中一条关键约定是：分类 ID（括号内）即规则文件的文件名前缀，用于将规则文件分组。例如async-前缀的规则文件全部属于"Eliminating Waterfalls"分类。

以下是 _sections.md 中定义的完整分类骨架：

从整体结构看，分类排序遵循"收益递减"原则：影响级别从 CRITICAL 逐级过渡到 LOW，排名越靠前的分类，投入同样的精力获得的性能收益越大。这也是 _sections.md 刻意设计排序的原因——它要指导自动化的重构与代码生成优先处理收益最高的问题。

三、分类 1：Eliminating Waterfalls（async-）—— CRITICAL

该分类的核心观点是：瀑布流是 #1 性能杀手，每个顺序 await 都会叠加完整的网络往返延迟，消除瀑布流能带来最大的性能收益。SKILL.md 中列出了该分类的 6 条规则：

• async-cheap-condition-before-await：在 await 标志位或远程值之前，先检查廉价的同步条件；
• async-defer-await：把 await 移入实际使用它的分支；
• async-parallel：对相互独立的操作使用Promise.all()；
• async-dependencies：对存在部分依赖的操作使用 better-all 最大化并行；
• async-api-routes：在 API 路由中尽早启动 promise、尽量晚 await；
• async-suspense-boundaries：使用 Suspense 流式输出内容。

以 async-parallel.md 为例，顺序 await 会产生 3 次网络往返，而并行执行只产生 1 次：

// Incorrect: 顺序执行，3 次往返 const user = await fetchUser() const posts = await fetchPosts() const comments = await fetchComments() // Correct: 并行执行，1 次往返 const [user, posts, comments] = await Promise.all([ fetchUser(), fetchPosts(), fetchComments() ])

async-defer-await则强调把 await 移入实际使用它的分支，避免阻塞不需要该数据的代码路径——例如当skipProcessing为真时，函数应立即返回而不必等待fetchUserData。这一优化在"被跳过的分支经常命中"或"被推迟的操作很昂贵"时价值尤其突出。

四、分类 2：Bundle Size Optimization（bundle-）—— CRITICAL

该分类的观点是：减小初始 bundle 体积能改善 Time to Interactive 与 Largest Contentful Paint。包含 6 条规则：

• bundle-barrel-imports：直接导入，避免 barrel 文件；
• bundle-analyzable-paths：优先使用可静态分析的导入与文件系统路径，避免产生宽泛的 bundle 与 trace；
• bundle-dynamic-imports：对重型组件使用next/dynamic；
• bundle-defer-third-party：在 hydration 之后再加载分析/日志类三方库；
• bundle-conditional：仅在功能激活时加载模块；
• bundle-preload：在 hover/focus 时预加载，提升感知速度。

bundle-barrel-imports是最具代表性的规则之一。Barrel 文件（如index.js中的export * from './module'）会一次性转发大量模块的导出。流行的图标与组件库的入口文件中可能有高达上万个 re-export，导入它们需要 200-800ms，同时拖慢开发速度与生产冷启动。需要特别注意的是"tree-shaking 为何帮不上忙"：当库被标记为 external（不打进 bundle）时，打包器无法优化它；而为了开启 tree-shaking 将其打入 bundle，又会因分析整个模块图而显著拖慢构建。

在 Next.js 13.5+ 项目中，推荐的做法是保持标准导入写法，由构建器（optimizePackageImports）在编译期将其转换为直接导入，从而保留 TypeScript 类型安全与编辑器自动补全：

// next.config.js 中声明需要优化的包 experimental: { optimizePackageImports: ['lucide-react', '@mui/material'] } // 组件中保持标准导入写法，构建期自动转成直接导入 import { Check, X, Menu } from 'lucide-react'

非 Next.js 项目则建议直接深度导入：import Button from '@mui/material/Button'。文中同时给出了类型安全警示：部分库（如lucide-react）不为深度导入路径提供.d.ts文件，在strict或noImplicitAny下会解析为隐式any，应优先使用optimizePackageImports或先验证库的路径导出。

五、分类 3：Server-Side Performance（server-）—— HIGH

该分类聚焦服务端渲染与数据获取，目标是消除服务端瀑布流并降低响应时间。包含 10 条规则：

• server-auth-actions：像 API 路由一样对 Server Actions 做鉴权；
• server-cache-react：用React.cache()做单请求内去重；
• server-cache-lru：用 LRU 缓存做跨请求缓存；
• server-dedup-props：避免 RSC props 中的重复序列化；
• server-hoist-static-io：将字体、Logo 等静态 I/O 提升到模块级别；
• server-no-shared-module-state：避免在 RSC/SSR 中使用模块级可变请求状态；
• server-serialization：最小化传给客户端组件的数据；
• server-parallel-fetching：重构组件结构以并行化请求；
• server-parallel-nested-fetching：在Promise.all中按条目链式执行嵌套请求；
• server-after-nonblocking：用after()执行非阻塞操作。

server-auth-actions强调：Server Actions（"use server"函数）与 API 路由一样是公开端点，必须在每个 Action 内部校验身份与授权，不能只依赖 middleware 或页面级守卫。规范代码会在内部先verifySession()，再做角色/资源归属校验，最后才执行数据库变更，并配合 Zod 等工具先校验输入。

server-cache-react展示了React.cache()的用法与一个关键陷阱——缓存命中采用浅比较（Object.is），因此内联对象参数每次都会产生新引用导致永远无法命中缓存：

import { cache } from 'react' export const getCurrentUser = cache(async () => { const session = await auth() if (!session?.user?.id) return null return await db.user.findUnique({ where: { id: session.user.id } }) }) // 错误：每次调用创建新对象，永远缓存未命中 getUser({ uid: 1 }) getUser({ uid: 1 }) // Cache miss // 正确：传入同一引用，第二次命中缓存 const params = { uid: 1 } getUser(params) // Query runs getUser(params) // Cache hit

server-cache-lru则补充了跨请求场景：React.cache()只在单请求内生效，用户连续点击 A、B 按钮这类跨请求共享数据，应使用lru-cache（如max: 1000, ttl: 5 * 60 * 1000）实现跨请求缓存。

六、分类 4：Client-Side Data Fetching（client-）—— MEDIUM-HIGH

该分类通过自动去重与高效数据获取模式，减少冗余网络请求。包含 4 条规则：

• client-swr-dedup：用 SWR 实现请求自动去重；
• client-event-listeners：去重全局事件监听器；
• client-passive-event-listeners：滚动监听使用 passive 模式；
• client-localstorage-schema：为 localStorage 数据添加版本号并最小化存储内容。

client-swr-dedup是最核心的一条：多个组件实例使用同一 key 调用useSWR('/api/users', fetcher)时，只会发起一次请求，天然获得去重、缓存与重新验证能力；不可变数据可用 immutable 模式，写操作可用useSWRMutation。

client-passive-event-listeners则解释了滚动卡顿的一个常见根因：浏览器默认会等待监听器执行完毕以确认是否调用preventDefault()，导致滚动延迟。对 touch/wheel 监听添加{ passive: true }即可让浏览器立即滚动；但自定义手势、缩放等需要preventDefault()的场景不能使用 passive。

七、分类 5：Re-render Optimization（rerender-）—— MEDIUM

该分类通过减少不必要的重渲染，最小化浪费的计算并提升 UI 响应性。共 15 条规则，是规则数量最多的分类：

• rerender-defer-reads：不要订阅只在回调中使用的状态；
• rerender-memo：把昂贵工作提取到 memoized 组件；
• rerender-memo-with-default-value：把非原始类型的默认 props 提升为常量；
• rerender-dependencies：effect 依赖使用原始类型；
• rerender-derived-state：订阅派生布尔值而非原始连续值；
• rerender-derived-state-no-effect：在渲染期间派生状态，而非在 effect 中；
• rerender-functional-setstate：用函数式 setState 保持回调稳定；
• rerender-lazy-state-init：为昂贵的初始值向 useState 传入函数；
• rerender-simple-expression-in-memo：简单原始表达式不要包 useMemo；
• rerender-split-combined-hooks：拆分依赖独立的组合 hooks；
• rerender-move-effect-to-event：把交互逻辑放进事件处理器；
• rerender-transitions：非紧急更新使用 startTransition；
• rerender-use-deferred-value：延迟昂贵渲染，保持输入框响应；
• rerender-use-ref-transient-values：高频临时值用 ref 存储；
• rerender-no-inline-components：不要在组件内部定义组件。

rerender-no-inline-components值得重点关注：在组件内部定义组件，每次渲染都会产生新的组件类型，React 会将其视为不同组件并整体卸载重挂，导致输入框失焦、动画重启、effect 重复执行、滚动位置重置等典型症状。正确做法是提取为独立组件并传 props。

rerender-derived-state-no-effect则展示了最常见的反模式：用 state + effect 派生fullName，完全可以用渲染期直接计算替代，既避免多余渲染又防止状态漂移。

八、分类 6：Rendering Performance（rendering-）—— MEDIUM

该分类优化渲染过程本身，减少浏览器需要做的工作。共 11 条规则：

• rendering-animate-svg-wrapper：动画 div 包装层而非 SVG 元素本身；
• rendering-content-visibility：长列表使用 content-visibility；
• rendering-hoist-jsx：把静态 JSX 提取到组件外部；
• rendering-svg-precision：降低 SVG 坐标精度；
• rendering-hydration-no-flicker：用内联脚本处理仅客户端数据，避免闪烁；
• rendering-hydration-suppress-warning：抑制预期内的 hydration 不匹配告警；
• rendering-activity：显示/隐藏用 Activity 组件；
• rendering-conditional-render：条件渲染用三元而非&&；
• rendering-usetransition-loading：加载态优先用 useTransition；
• rendering-resource-hints：用 React DOM 资源提示做预加载；
• rendering-script-defer-async：script 标签使用 defer 或 async。

rendering-content-visibility展示了如何用 CSS 直接跳过视口外内容的布局与绘制：对列表项施加content-visibility: auto; contain-intrinsic-size: 0 80px;，渲染 1000 条消息时浏览器可跳过约 990 条屏外内容的布局/绘制，显著加快首屏渲染。

rendering-resource-hints整理了 React DOM 的 6 个资源预加载 API 及其适用场景：prefetchDNS（稍后连接的第三方域名）、preconnect（即将请求的 API/CDN）、preload（当前页面关键资源）、preloadModule（可能的下一次导航 JS 模块）、preinit（需尽早执行的样式/脚本）、preinitModule（需尽早执行的 ES 模块）。在 Server Components 中调用这些 API，可在客户端收到 HTML 之前就开始加载资源。

九、分类 7：JavaScript Performance（js-）—— LOW-MEDIUM

该分类收集热点路径上的微优化，单条收益不大，但累积起来可观。共 14 条规则：

• js-batch-dom-css：用 class 或 cssText 分组修改 CSS，避免布局抖动（layout thrashing）；
• 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：用循环求 min/max，而不是排序；
• js-set-map-lookups：用 Set/Map 做 O(1) 查找；
• js-tosorted-immutable：用toSorted()保证不可变；
• js-flatmap-filter：用 flatMap 一次完成映射与过滤；
• js-request-idle-callback：把非关键工作推迟到浏览器空闲时间。

js-index-maps给出了量化的收益：1000 个订单 × 1000 个用户场景下，用new Map(users.map(u => [u.id, u]))替代每次.find()，操作数从 100 万次降到 2000 次。js-tosorted-immutable则提醒：.sort()会原地修改数组，破坏 React 的不可变模型，应改用返回新数组的.toSorted()（以及toReversed()、toSpliced()、with()），旧环境可用展开运算符[...items].sort()兜底。

十、分类 8：Advanced Patterns（advanced-）—— LOW

该分类收录需要谨慎实现的特定场景高级模式。共 4 条规则：

• advanced-effect-event-deps：不要把useEffectEvent的结果放进 effect 依赖数组；
• advanced-event-handler-refs：把事件处理器存进 refs；
• advanced-init-once：每次应用加载只初始化一次；
• advanced-use-latest：用 useLatest 保持回调引用稳定。

advanced-effect-event-deps解释了一个容易踩坑的点：Effect Event 函数的身份在每次渲染时都会变化，把它们加入useEffect依赖数组会导致 effect 每次渲染都重跑并触发 Hooks lint 规则。正确做法是以真正响应式值为依赖，在 effect 内部调用 Effect Event。advanced-init-once则针对"应用级初始化"场景：不要放在组件的useEffect([])中（组件会重挂、effect 会重跑），而应使用模块级守卫标志didInit或入口模块的顶层初始化。

十一、影响级别体系：从 CRITICAL 到 LOW 的收益分级

README.md 明确了完整的 6 档影响级别：

• CRITICAL：最高优先级，主要性能收益；
• HIGH：显著性能提升；
• MEDIUM-HIGH：中高收益；
• MEDIUM：中等性能改进；
• LOW-MEDIUM：中低收益；
• LOW：增量改进。

这套分级与 8 大分类一一对应，构成"先修瀑布流和 bundle，再优化服务端与客户端数据获取，最后处理重渲染、渲染与 JS 微优化"的执行顺序，让自动化重构能按 ROI 排序投入。

十二、规则文件规范：命名约定与统一结构

_sections.md末尾的括号 ID 与文件名前缀的映射，在 README.md 中被落实为具体的维护规范：

• 规则文件采用area-description.md命名，例如async-parallel.md；
• 下划线开头的文件（_sections.md、_template.md）是特殊文件，不参与编译；
• 分类（section）从文件名前缀自动推断，规则按标题在分类内自动排序，无需人工编号；
• 构建期自动生成 ID（如 1.1、1.2）。

_template.md 定义了每条规则的统一结构：frontmatter（标题、影响级别、可选的影响描述、标签）+ 规则正文（为什么重要）+ 错误示例及说明 + 正确示例及说明 + 参考链接。编译后的完整文档即 AGENTS.md，其中每条规则都包含完整代码对照与补充语境。

十三、在 open-slide 仓库中的应用场景

该技能被 open-slide 以 skill 形式收纳在.agents/skills/目录（见 skills-lock.json 中的引用），其 AGENTS.md 在开头明确了适用人群与定位："这份文档主要供 Agent 与 LLM 在维护、生成或重构 React/Next.js 代码库时遵循，人类读者也能从中受益，但此处指引针对 AI 辅助工作流的一致性进行了优化。"

结合 SKILL.md 的 When to Apply 章节，实际使用场景包括：

• 编写新的 React 组件或 Next.js 页面；
• 实现客户端或服务端的数据获取；
• 审查代码中的性能问题；
• 重构现有 React/Next.js 代码；
• 优化 bundle 体积或加载时间。

具体使用时，可按"先查分类总览定位问题域 → 再读该分类下的规则文件获取错误/正确代码对照 → 最后在 AGENTS.md 中查阅编译后的完整版"的路径查阅，也可直接按文件名前缀（如bundle-、server-）在rules/目录中检索目标规则。

结语

这套 8 大分类的规则体系，本质上是把 React/Next.js 性能优化从"经验"转化为"可按优先级执行的清单"：从 CRITICAL 的瀑布流消除与 bundle 瘦身，到 LOW 的微优化与高级模式，每条规则都配有可复制、可对照的代码示例。无论用于人工审查还是 Agent 自动化重构，按_sections.md定义的优先级顺序逐层排查，都能以最小的排查成本锁定最大的性能收益。