Vercel React 最佳实践 中文版

React 最佳实践

版本 1.0.0
Vercel 工程团队
2026年1月

注意：
本文档主要供 Agent 和 LLM 在 Vercel 维护、生成或重构 React 及 Next.js 代码库时遵循。人类开发者也会发现其对于保持一致性和自动化优化非常有帮助。

摘要

这是一份针对 React 和 Next.js 应用程序的综合性能优化指南，专为 AI Agent 和 LLM 设计。包含 8 个类别的 40 多条规则，按影响力从关键（消除瀑布流、减少打包体积）到增量（高级模式）排序。每条规则都包含详细的解释、错误与正确实现的真实代码对比，以及具体的影响指标，以指导自动重构和代码生成。

目录

1. 消除瀑布流 — 关键
   • 1.1 推迟 Await 直到需要时
   • 1.2 基于依赖的并行化
   • 1.3 防止 API 路由中的瀑布链
   • 1.4 对独立操作使用 Promise.all()
   • 1.5 策略性 Suspense 边界
2. 打包体积优化 — 关键
   • 2.1 避免 Barrel 文件导入
   • 2.2 条件模块加载
   • 2.3 推迟非关键第三方库
   • 2.4 重型组件动态导入
   • 2.5 基于用户意图预加载
3. 服务端性能 — 高
   • 3.1 跨请求 LRU 缓存
   • 3.2 最小化 RSC 边界序列化
   • 3.3 通过组件组合并行获取数据
   • 3.4 使用 React.cache() 进行按请求去重
   • 3.5 使用 after() 处理非阻塞操作
4. 客户端数据获取 — 中高
   • 4.1 去重全局事件监听器
   • 4.2 使用 SWR 自动去重
5. 重渲染优化 — 中
   • 5.1 推迟状态读取到使用点
   • 5.2 提取为记忆化组件
   • 5.3 缩小 Effect 依赖范围
   • 5.4 订阅派生状态
   • 5.5 使用函数式 setState 更新
   • 5.6 使用惰性状态初始化
   • 5.7 对非紧急更新使用 Transitions
6. 渲染性能 — 中
   • 6.1 动画化 SVG 包装器而非 SVG 元素
   • 6.2 长列表使用 CSS content-visibility
   • 6.3 提升静态 JSX 元素
   • 6.4 优化 SVG 精度
   • 6.5 无闪烁防止水合不匹配
   • 6.6 使用 Activity 组件进行显示/隐藏
   • 6.7 使用显式条件渲染
7. JavaScript 性能 — 中低
   • 7.1 批量 DOM CSS 更改
   • 7.2 为重复查找构建索引 Map
   • 7.3 在循环中缓存属性访问
   • 7.4 缓存重复函数调用
   • 7.5 缓存 Storage API 调用
   • 7.6 合并多个数组迭代
   • 7.7 数组比较前先检查长度
   • 7.8 函数提前返回
   • 7.9 提升 RegExp 创建
   • 7.10 使用循环求最小/最大值而非排序
   • 7.11 使用 Set/Map 进行 O(1) 查找
   • 7.12 使用 toSorted() 代替 sort() 以保证不可变性
8. 高级模式 — 低
   • 8.1 在 Refs 中存储事件处理程序
   • 8.2 使用 useLatest 获取稳定的回调 Refs

1. 消除瀑布流

影响力: 关键

瀑布流（Waterfalls）是头号性能杀手。每一个连续的 await 都会增加完整的网络延迟。消除它们能带来最大的收益。

1.1 推迟 Await 直到需要时

影响力: 高 (避免阻塞不使用的代码路径)

将 await 操作移动到实际使用它们的分支中，以避免阻塞不需要它们的代码路径。

错误：阻塞了两个分支

1async function handleRequest(userId: string, skipProcessing: boolean) {
2  const userData = await fetchUserData(userId)
3  
4  if (skipProcessing) {
5    // 立即返回，但仍然等待了 userData
6    return { skipped: true }
7  }
8  
9  // 只有这个分支使用了 userData
10  return processUserData(userData)
11}
12

正确：仅在需要时阻塞

1async function handleRequest(userId: string, skipProcessing: boolean) {
2  if (skipProcessing) {
3    // 不等待直接返回
4    return { skipped: true }
5  }
6  
7  // 仅在需要时获取
8  const userData = await fetchUserData(userId)
9  return processUserData(userData)
10}
11

另一个例子：提前返回优化

1// 错误：总是获取权限
2async function updateResource(resourceId: string, userId: string) {
3  const permissions = await fetchPermissions(userId)
4  const resource = await getResource(resourceId)
5  
6  if (!resource) {
7    return { error: 'Not found' }
8  }
9  
10  if (!permissions.canEdit) {
11    return { error: 'Forbidden' }
12  }
13  
14  return await updateResourceData(resource, permissions)
15}
16
17// 正确：仅在需要时获取
18async function updateResource(resourceId: string, userId: string) {
19  const resource = await getResource(resourceId)
20  
21  if (!resource) {
22    return { error: 'Not found' }
23  }
24  
25  const permissions = await fetchPermissions(userId)
26  
27  if (!permissions.canEdit) {
28    return { error: 'Forbidden' }
29  }
30  
31  return await updateResourceData(resource, permissions)
32}
33

当被跳过的分支经常被执行，或者被推迟的操作非常昂贵时，这种优化通过尤为有价值。

1.2 基于依赖的并行化

影响力: 关键 (2-10倍 提升)

对于具有部分依赖关系的操作，使用 better-all 来即最大化并行性。它会在尽可能早的时刻启动每个任务。

错误：profile 不必要地等待 config

1const [user, config] = await Promise.all([
2  fetchUser(),
3  fetchConfig()
4])
5const profile = await fetchProfile(user.id)
6

正确：config 和 profile 并行运行

1import { all } from 'better-all'
2
3const { user, config, profile } = await all({
4  async user() { return fetchUser() },
5  async config() { return fetchConfig() },
6  async profile() {
7    return fetchProfile((await this.$.user).id)
8  }
9})
10

参考: github.com/shuding/bet…

1.3 防止 API 路由中的瀑布链

影响力: 关键 (2-10倍 提升)

在 API 路由和 Server Actions 中，即使此时还不 await 它们，也要立即启动独立的操作。

错误：config 等待 auth，data 等待两者

1export async function GET(request: Request) {
2  const session = await auth()
3  const config = await fetchConfig()
4  const data = await fetchData(session.user.id)
5  return Response.json({ data, config })
6}
7

正确：auth 和 config 立即启动

1export async function GET(request: Request) {
2  const sessionPromise = auth()
3  const configPromise = fetchConfig()
4  const session = await sessionPromise
5  const [config, data] = await Promise.all([
6    configPromise,
7    fetchData(session.user.id)
8  ])
9  return Response.json({ data, config })
10}
11

对于具有更复杂依赖链的操作，使用 better-all 自动最大化并行性（参见"基于依赖的并行化"）。

1.4 对独立操作使用 Promise.all()

影响力: 关键 (2-10倍 提升)

当异步操作没有相互依赖关系时，使用 Promise.all() 并发执行它们。

错误：顺序执行，3 次往返

1const user = await fetchUser()
2const posts = await fetchPosts()
3const comments = await fetchComments()
4

正确：并行执行，1 次往返

1const [user, posts, comments] = await Promise.all([
2  fetchUser(),
3  fetchPosts(),
4  fetchComments()
5])
6

1.5 策略性 Suspense 边界

影响力: 高 (更快的首次绘制)

不要在异步组件中等待数据后再返回 JSX，而是使用 Suspense 边界在数据加载时更快地显示包装器 UI。

错误：包装器被数据获取阻塞

1async function Page() {
2  const data = await fetchData() // 阻塞整个页面
3  
4  return (
5    <div>
6      <div>Sidebar</div>
7      <div>Header</div>
8      <div>
9        <DataDisplay data={data} />
10      </div>
11      <div>Footer</div>
12    </div>
13  )
14}
15

即便只有中间部分需要数据，整个布局也会等待数据。

正确：包装器立即显示，数据流式传输

1function Page() {
2  return (
3    <div>
4      <div>Sidebar</div>
5      <div>Header</div>
6      <div>
7        <Suspense fallback={<Skeleton />}>
8          <DataDisplay />
9        </Suspense>
10      </div>
11      <div>Footer</div>
12    </div>
13  )
14}
15
16async function DataDisplay() {
17  const data = await fetchData() // 仅阻塞此组件
18  return <div>{data.content}</div>
19}
20

Sidebar、Header 和 Footer 立即渲染。只有 DataDisplay 等待数据。

替代方案：在组件间共享 promise

1function Page() {
2  // 立即开始获取，但不要 await
3  const dataPromise = fetchData()
4  
5  return (
6    <div>
7      <div>Sidebar</div>
8      <div>Header</div>
9      <Suspense fallback={<Skeleton />}>
10        <DataDisplay dataPromise={dataPromise} />
11        <DataSummary dataPromise={dataPromise} />
12      </Suspense>
13      <div>Footer</div>
14    </div>
15  )
16}
17
18function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
19  const data = use(dataPromise) // 解包 promise
20  return <div>{data.content}</div>
21}
22
23function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
24  const data = use(dataPromise) // 复用同一个 promise
25  return <div>{data.summary}</div>
26}
27

两个组件共享同一个 promise，因此只会进行一次获取。布局立即渲染，而两个组件一起等待。

何时不使用此模式：

• 布局决策所需的关键数据（影响定位）
• 首屏（Above the fold）的 SEO 关键内容
• Suspense 开销不值得的小型快速查询
• 当你想要避免布局偏移（加载中 → 内容跳动）时

权衡： 更快的首次绘制 vs 潜在的布局偏移。根据你的 UX 优先级进行选择。

2. 打包体积优化

影响力: 关键

减少初始打包体积可以改善可交互时间 (TTI) 和最大内容绘制 (LCP)。

2.1 避免 Barrel 文件导入

影响力: 关键 (200-800ms 导入成本, 缓慢的构建)

直接从源文件导入而不是从 Barrel 文件导入，以避免加载数千个未使用的模块。Barrel 文件是重新导出多个模块的入口点（例如，执行 export * from './module' 的 index.js）。

流行的图标和组件库在其入口文件中可能有 多达 10,000 个重导出。对于许多 React 包，仅导入它们就需要 200-800ms，这会影响开发速度和生产环境的冷启动。

为什么 tree-shaking 没有帮助： 当库被标记为外部（不打包）时，打包器无法对其进行优化。如果你将其打包以启用 tree-shaking，分析整个模块图会导致构建变得非常缓慢。

错误：导入整个库

1import { Check, X, Menu } from 'lucide-react'
2// 加载 1,583 个模块，开发环境额外耗时 ~2.8s
3// 运行时成本：每次冷启动 200-800ms
4
5import { Button, TextField } from '@mui/material'
6// 加载 2,225 个模块，开发环境额外耗时 ~4.2s
7

正确：仅导入你需要的内容

1import Check from 'lucide-react/dist/esm/icons/check'
2import X from 'lucide-react/dist/esm/icons/x'
3import Menu from 'lucide-react/dist/esm/icons/menu'
4// 仅加载 3 个模块 (~2KB vs ~1MB)
5
6import Button from '@mui/material/Button'
7import TextField from '@mui/material/TextField'
8// 仅加载你使用的内容
9

替代方案：Next.js 13.5+

1// next.config.js - 使用 optimizePackageImports
2module.exports = {
3  experimental: {
4    optimizePackageImports: ['lucide-react', '@mui/material']
5  }
6}
7
8// 这样你可以保留符合人体工程学的 Barrel 导入：
9import { Check, X, Menu } from 'lucide-react'
10// 在构建时自动转换为直接导入
11

直接导入可提供 15-70% 更快的开发启动速度，28% 更快的构建速度，40% 更快的冷启动速度，以及显著更快的 HMR。

受影响的常见库：lucide-react, @mui/material, @mui/icons-material, @tabler/icons-react, react-icons, @headlessui/react, @radix-ui/react-*, lodash, ramda, date-fns, rxjs, react-use。

参考: vercel.com/blog/how-we…

2.2 条件模块加载

影响力: 高 (仅在需要时加载大数据)

仅在功能激活时加载大数据或模块。

例子：懒加载动画帧

1function AnimationPlayer({ enabled }: { enabled: boolean }) {
2  const [frames, setFrames] = useState<Frame[] | null>(null)
3
4  useEffect(() => {
5    if (enabled && !frames && typeof window !== 'undefined') {
6      import('./animation-frames.js')
7        .then(mod => setFrames(mod.frames))
8        .catch(() => setEnabled(false))
9    }
10  }, [enabled, frames])
11
12  if (!frames) return <Skeleton />
13  return <Canvas frames={frames} />
14}
15

typeof window !== 'undefined' 检查可防止在 SSR 时打包此模块，从而优化服务端包体积和构建速度。

2.3 推迟非关键第三方库

影响力: 中 (水合后加载)

分析、日志记录和错误跟踪不会阻塞用户交互。应当在水合（Hydration）之后加载它们。

错误：阻塞初始包

1import { Analytics } from '@vercel/analytics/react'
2
3export default function RootLayout({ children }) {
4  return (
5    <html>
6      <body>
7        {children}
8        <Analytics />
9      </body>
10    </html>
11  )
12}
13

正确：水合后加载

1import dynamic from 'next/dynamic'
2
3const Analytics = dynamic(
4  () => import('@vercel/analytics/react').then(m => m.Analytics),
5  { ssr: false }
6)
7
8export default function RootLayout({ children }) {
9  return (
10    <html>
11      <body>
12        {children}
13        <Analytics />
14      </body>
15    </html>
16  )
17}
18

2.4 重型组件动态导入

影响力: 关键 (直接影响 TTI 和 LCP)

使用 next/dynamic 懒加载初始渲染不需要的大型组件。

错误：Monaco 随主 chunk 打包 ~300KB

1import { MonacoEditor } from './monaco-editor'
2
3function CodePanel({ code }: { code: string }) {
4  return <MonacoEditor value={code} />
5}
6

正确：Monaco 按需加载

1import dynamic from 'next/dynamic'
2
3const MonacoEditor = dynamic(
4  () => import('./monaco-editor').then(m => m.MonacoEditor),
5  { ssr: false }
6)
7
8function CodePanel({ code }: { code: string }) {
9  return <MonacoEditor value={code} />
10}
11

2.5 基于用户意图预加载

影响力: 中 (减少感知延迟)

在需要之前预加载繁重的包，以减少感知延迟。

例子：悬停/聚焦时预加载

1function EditorButton({ onClick }: { onClick: () => void }) {
2  const preload = () => {
3    if (typeof window !== 'undefined') {
4      void import('./monaco-editor')
5    }
6  }
7
8  return (
9    <button
10      onMouseEnter={preload}
11      onFocus={preload}
12      onClick={onClick}
13    >
14      打开编辑器
15    </button>
16  )
17}
18

例子：当功能标志启用时预加载

1function FlagsProvider({ children, flags }: Props) {
2  useEffect(() => {
3    if (flags.editorEnabled && typeof window !== 'undefined') {
4      void import('./monaco-editor').then(mod => mod.init())
5    }
6  }, [flags.editorEnabled])
7
8  return <FlagsContext.Provider value={flags}>
9    {children}
10  </FlagsContext.Provider>
11}
12

typeof window !== 'undefined' 检查可防止在 SSR 时打包预加载模块，从而优化服务端包体积和构建速度。

3. 服务端性能

影响力: 高

优化服务端渲染和数据获取可消除服务端瀑布流并减少响应时间。

3.1 跨请求 LRU 缓存

影响力: 高 (跨请求缓存)

React.cache() 仅在一个请求内有效。对于跨连续请求共享的数据（用户点击按钮 A 然后点击按钮 B），请使用 LRU 缓存。

实现：

1import { LRUCache } from 'lru-cache'
2
3const cache = new LRUCache<string, any>({
4  max: 1000,
5  ttl: 5 * 60 * 1000  // 5 分钟
6})
7
8export async function getUser(id: string) {
9  const cached = cache.get(id)
10  if (cached) return cached
11
12  const user = await db.user.findUnique({ where: { id } })
13  cache.set(id, user)
14  return user
15}
16
17// 请求 1: DB 查询, 结果被缓存
18// 请求 2: 缓存命中, 无 DB 查询
19

当顺序的用户操作在几秒钟内命中多个需要相同数据的端点时，请使用此方法。

配合 Vercel 的 Fluid Compute： LRU 缓存特别有效，因为多个并发请求可以共享同一个函数实例和缓存。这意味着缓存可以跨请求持久化，而无需 Redis 等外部存储。

在传统 Serverless 中： 每次调用都是隔离运行的，因此请考虑使用 Redis 进行跨进而缓存。

参考: github.com/isaacs/node…

3.2 最小化 RSC 边界序列化

影响力: 高 (减少传输数据大小)

React Server/Client 边界会将所有对象属性序列化为字符串，并将它们嵌入到 HTML 响应和后续的 RSC 请求中。此序列化数据直接影响页面重量和加载时间，因此 大小非常重要。仅传递客户端实际使用的字段。

错误：序列化所有 50 个字段

1async function Page() {
2  const user = await fetchUser()  // 50 个字段
3  return <Profile user={user} />
4}
5
6'use client'
7function Profile({ user }: { user: User }) {
8  return <div>{user.name}</div>  // 使用 1 个字段
9}
10

正确：仅序列化 1 个字段

1async function Page() {
2  const user = await fetchUser()
3  return <Profile name={user.name} />
4}
5
6'use client'
7function Profile({ name }: { name: string }) {
8  return <div>{name}</div>
9}
10

3.3 通过组件组合并行获取数据

影响力: 关键 (消除服务端瀑布流)

React Server Components 在树中顺序执行。使用组合重构以并行化数据获取。

错误：Sidebar 等待 Page 的 fetch 完成

1export default async function Page() {
2  const header = await fetchHeader()
3  return (
4    <div>
5      <div>{header}</div>
6      <Sidebar />
7    </div>
8  )
9}
10
11async function Sidebar() {
12  const items = await fetchSidebarItems()
13  return <nav>{items.map(renderItem)}</nav>
14}
15

正确：两者同时获取

1async function Header() {
2  const data = await fetchHeader()
3  return <div>{data}</div>
4}
5
6async function Sidebar() {
7  const items = await fetchSidebarItems()
8  return <nav>{items.map(renderItem)}</nav>
9}
10
11export default function Page() {
12  return (
13    <div>
14      <Header />
15      <Sidebar />
16    </div>
17  )
18}
19

使用 children prop 的替代方案：

1async function Layout({ children }: { children: ReactNode }) {
2  const header = await fetchHeader()
3  return (
4    <div>
5      <div>{header}</div>
6      {children}
7    </div>
8  )
9}
10
11async function Sidebar() {
12  const items = await fetchSidebarItems()
13  return <nav>{items.map(renderItem)}</nav>
14}
15
16export default function Page() {
17  return (
18    <Layout>
19      <Sidebar />
20    </Layout>
21  )
22}
23

3.4 使用 React.cache() 进行按请求去重

影响力: 中 (请求内去重)

使用 React.cache() 进行服务端请求去重。身份验证和数据库查询受益最大。

用法：

1import { cache } from 'react'
2
3export const getCurrentUser = cache(async () => {
4  const session = await auth()
5  if (!session?.user?.id) return null
6  return await db.user.findUnique({
7    where: { id: session.user.id }
8  })
9})
10

在单个请求中，对 getCurrentUser() 的多次调用只会执行一次查询。

3.5 使用 after() 处理非阻塞操作

影响力: 中 (更快的响应时间)

使用 Next.js 的 after() 来调度应在发送响应后执行的工作。这可以防止日志记录、分析和其他副作用阻塞响应。

错误：阻塞响应

1import { logUserAction } from '@/app/utils'
2
3export async function POST(request: Request) {
4  // 执行变更
5  await updateDatabase(request)
6  
7  // 日志记录阻塞了响应
8  const userAgent = request.headers.get('user-agent') || 'unknown'
9  await logUserAction({ userAgent })
10  
11  return new Response(JSON.stringify({ status: 'success' }), {
12    status: 200,
13    headers: { 'Content-Type': 'application/json' }
14  })
15}
16

正确：非阻塞

1import { after } from 'next/server'
2import { headers, cookies } from 'next/headers'
3import { logUserAction } from '@/app/utils'
4
5export async function POST(request: Request) {
6  // 执行变更
7  await updateDatabase(request)
8  
9  // 响应发送后记录日志
10  after(async () => {
11    const userAgent = (await headers()).get('user-agent') || 'unknown'
12    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
13    
14    logUserAction({ sessionCookie, userAgent })
15  })
16  
17  return new Response(JSON.stringify({ status: 'success' }), {
18    status: 200,
19    headers: { 'Content-Type': 'application/json' }
20  })
21}
22

响应立即发送，而日志记录在后台发生。

常见用例：

• 分析跟踪
• 审计日志
• 发送通知
• 缓存失效
• 清理任务

重要说明：

• 即使响应失败或重定向，after() 也会运行
• 适用于 Server Actions、Route Handlers 和 Server Components

参考: nextjs.org/docs/app/ap…

4. 客户端数据获取

影响力: 中高

自动去重和高效的数据获取模式减少了多余的网络请求。

4.1 去重全局事件监听器

影响力: 低 (N 个组件共用单个监听器)

使用 useSWRSubscription() 在组件实例之间共享全局事件监听器。

错误：N 个实例 = N 个监听器

1function useKeyboardShortcut(key: string, callback: () => void) {
2  useEffect(() => {
3    const handler = (e: KeyboardEvent) => {
4      if (e.metaKey && e.key === key) {
5        callback()
6      }
7    }
8    window.addEventListener('keydown', handler)
9    return () => window.removeEventListener('keydown', handler)
10  }, [key, callback])
11}
12