NNext.js 中文网 GitHub

流式渲染

了解流式渲染在 Next.js 中的工作原理,以及如何利用它在数据可用时逐步渲染 UI。

什么是流式渲染?#

在传统的服务端渲染中,服务器会先生成完整的 HTML 文档,然后才发送任何内容。一个缓慢的数据库查询或 API 调用就可能阻塞整个页面。流式渲染通过使用分块传输编码在响应各部分就绪时将其发送,从而改变了这一点。浏览器会在服务器仍在生成其余内容时就开始渲染 HTML。

这对于将快速的静态内容(页头、导航、布局)与较慢的动态内容(个性化数据、分析、推荐)结合在一起的页面尤其有意义。静态部分可以预渲染并从 CDN 提供服务,立即绘制,而动态部分则在就绪后从服务器流式传入。

React 的服务端渲染器会按与 <Suspense> 边界对齐的块来生成 HTML。Next.js 将其集成到 App Router 中,因此无需额外配置即可使用流式渲染。

示例#

配套的流式渲染演示(源码)让你可以看到本指南中的每个概念的实际效果:

  • 使用 loading.tsx 的页面级流式渲染(骨架屏立即出现,内容约 2 秒后流式传入)
  • 使用独立解析的兄弟 <Suspense> 边界进行细粒度流式渲染
  • 水合对比:单次阻塞式水合与使用 Suspense 边界的拆分水合
  • 在 Route Handler 中流式传输原始 HTML,并提前发现 CSS
  • 一个可配置的 ReadableStream API 端点,用于试验块大小和浏览器缓冲

App Router 如何交付页面#

当浏览器请求一个页面时,在初始页面加载期间有两个流协同工作:

HTML 流#

React 的服务端渲染器会生成渐进式 HTML 块。页面的静态部分(布局、导航、Suspense 回退内容)会首先渲染并立即发送。当某个 <Suspense> 边界的内容就绪时(例如一个异步 Server Component 解析完成),React 会将其完成的 HTML 连同内联 <script> 标签一起流式传输:一个标签用新内容替换回退 DOM 节点,另一个携带组件 payload,以便 React 稍后对其进行水合。浏览器会立即执行替换,无需等待页面的 JavaScript bundle 加载或水合完成。这就是用户看到的效果:页面逐段渐进式绘制。

组件 payload#

组件 payload 是组件树的序列化表示,React 用它来水合页面并处理客户端更新。在初始加载时,它如上所述嵌入在 HTML 流中。在客户端导航时,只会获取组件 payload(带有 rsc: 1 请求头),完全不传输 HTML。React 用它就地更新组件树。

静态外壳#

在任何异步工作解析之前渲染的所有内容称为静态外壳:你的布局、导航,以及由 <Suspense> 边界定义的回退 UI。它会立即发送,让用户有内容可看、可交互,同时动态内容流式传入。借助 Cache Components,静态外壳会在构建时预渲染并从边缘即时提供。

每个 <Suspense> 边界都是一个独立的流式传输点。不同边界内的组件独立解析和流式传入,彼此不会阻塞。

使用 loading.js 的页面级流式渲染#

添加流式渲染最简单的方法是使用 loading.js 文件。将其放在 page.js 旁边,Next.js 会自动用 <Suspense> 边界包裹页面内容,并将你的加载组件作为回退内容。

app/dashboard/loading.tsx
export default function Loading() {
  return (
    <div className="animate-pulse">
      <div className="h-8 w-48 bg-gray-200 rounded mb-4" />
      <div className="h-4 w-full bg-gray-200 rounded mb-2" />
      <div className="h-4 w-full bg-gray-200 rounded mb-2" />
      <div className="h-4 w-2/3 bg-gray-200 rounded" />
    </div>
  )
}
app/dashboard/loading.js
export default function Loading() {
  return (
    <div className="animate-pulse">
      <div className="h-8 w-48 bg-gray-200 rounded mb-4" />
      <div className="h-4 w-full bg-gray-200 rounded mb-2" />
      <div className="h-4 w-full bg-gray-200 rounded mb-2" />
      <div className="h-4 w-2/3 bg-gray-200 rounded" />
    </div>
  )
}

在底层,loading.js 嵌套在 layout.js 内,并将 page.js 包裹在 <Suspense> 边界中:

这意味着:

  • 布局作为静态外壳的一部分立即渲染。
  • 加载骨架屏作为 Suspense 回退内容立即显示。
  • 页面组件加载完成后,其 HTML 会替换骨架屏。

loading.js 适用于在页面数据解析之前没有任何有意义的内容可显示的情况。如果页面需要先等待数据才能渲染任何内容,那么整页骨架屏是一个合理的回退方案。

更多细节请参阅 loading.js API 参考。

使用 <Suspense> 的细粒度流式渲染#

<Suspense> 让你可以精确控制页面哪些部分独立流式传输。你可以使用更细粒度的回退内容,而不必使用整页骨架屏,让静态外壳包含更多真实内容。

使用兄弟边界的并行流式渲染#

当多个组件执行异步工作(获取数据、读取数据库)时,将每个组件包裹在其自己的 <Suspense> 边界中。每个边界都会在其异步工作完成时独立流式传输,无论完成顺序如何,彼此都不会阻塞:

app/dashboard/page.tsx
import { Suspense } from 'react'
import { Revenue } from './revenue'
import { RecentOrders } from './recent-orders'
import { Recommendations } from './recommendations'

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <div className="grid grid-cols-2 gap-4">
        <Suspense fallback={<p>Loading revenue...</p>}>
          <Revenue />
        </Suspense>
        <Suspense fallback={<p>Loading orders...</p>}>
          <RecentOrders />
        </Suspense>
      </div>
      <Suspense fallback={<p>Loading recommendations...</p>}>
        <Recommendations />
      </Suspense>
    </div>
  )
}
app/dashboard/page.js
import { Suspense } from 'react'
import { Revenue } from './revenue'
import { RecentOrders } from './recent-orders'
import { Recommendations } from './recommendations'

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <div className="grid grid-cols-2 gap-4">
        <Suspense fallback={<p>Loading revenue...</p>}>
          <Revenue />
        </Suspense>
        <Suspense fallback={<p>Loading orders...</p>}>
          <RecentOrders />
        </Suspense>
      </div>
      <Suspense fallback={<p>Loading recommendations...</p>}>
        <Recommendations />
      </Suspense>
    </div>
  )
}

在此示例中,如果 Revenue 在 200ms 内解析,RecentOrders 在 1s 内解析,Recommendations 在 3s 内解析,用户会看到每个部分在其数据就绪时立即出现。

用于渐进式细节的嵌套边界#

你可以嵌套 <Suspense> 边界以创建分层的加载体验。例如,商品页面可能立即流式传输页头,接着是商品详情,最后是评论:

app/product/[id]/page.tsx
import { Suspense } from 'react'
import { ProductDetails } from './product-details'
import { Reviews } from './reviews'

export async function generateStaticParams() {
  const products = await getTopProducts()
  return products.map((product) => ({ id: product.id }))
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params

  return (
    <div>
      <h1>Product</h1>
      <Suspense fallback={<p>Loading product details...</p>}>
        <ProductDetails id={id} />
        <Suspense fallback={<p>Loading reviews...</p>}>
          <Reviews productId={id} />
        </Suspense>
      </Suspense>
    </div>
  )
}
app/product/[id]/page.js
import { Suspense } from 'react'
import { ProductDetails } from './product-details'
import { Reviews } from './reviews'

export async function generateStaticParams() {
  const products = await getTopProducts()
  return products.map((product) => ({ id: product.id }))
}

export default async function ProductPage({ params }) {
  const { id } = await params

  return (
    <div>
      <h1>Product</h1>
      <Suspense fallback={<p>Loading product details...</p>}>
        <ProductDetails id={id} />
        <Suspense fallback={<p>Loading reviews...</p>}>
          <Reviews productId={id} />
        </Suspense>
      </Suspense>
    </div>
  )
}

外层边界在 ProductDetails 解析之前显示 "Loading product details..."。解析完成后,内层边界变为可见,在 Reviews 解析之前显示 "Loading reviews..."。这就形成了渐进式的呈现。

下推动态访问#

最大化即时流式渲染内容的关键,是将动态数据访问推迟到真正需要它的组件中。这适用于 params、searchParams、cookies()、headers() 和数据获取。如果你在布局或页面的顶层 await 其中任何一项,其下方的所有内容都会变为动态的,无法作为静态外壳的一部分预渲染。

相反,应将 promise 向下传递,让使用它的组件在 <Suspense> 边界内解析它:

app/dashboard/layout.tsx
import { Suspense } from 'react'
import { Nav } from './nav'
import { UserMenu } from './user-menu'
import { cookies } from 'next/headers'

export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const cookieStore = cookies() // 开始工作,但不要 await

  return (
    <div>
      <Nav>
        <Suspense fallback={<p>Loading user...</p>}>
          <UserMenu cookiePromise={cookieStore} />
        </Suspense>
      </Nav>
      {children}
    </div>
  )
}
app/dashboard/layout.js
import { Suspense } from 'react'
import { Nav } from './nav'
import { UserMenu } from './user-menu'
import { cookies } from 'next/headers'

export default function DashboardLayout({ children }) {
  const cookieStore = cookies() // 开始工作,但不要 await

  return (
    <div>
      <Nav>
        <Suspense fallback={<p>Loading user...</p>}>
          <UserMenu cookiePromise={cookieStore} />
        </Suspense>
      </Nav>
      {children}
    </div>
  )
}

在此示例中,<Nav> 和 {children} 作为静态外壳的一部分渲染,因为布局中没有任何内容被 await。只有 <UserMenu> 在解析 cookie promise 时挂起。如果布局在顶层调用了 await cookies(),整个布局及其所有子组件都会被阻止预渲染。

同样的原则也适用于 params 和 searchParams。不要在页面层解构它们,而是将 promise 传递给需要该值的组件:

app/shop/[category]/page.tsx
import { Suspense } from 'react'
import { Hero } from './hero'
import { ProductGrid } from './product-grid'

export async function generateStaticParams() {
  const categories = await getCategories()
  return categories.map((c) => ({ category: c.slug }))
}

export default function ShopPage({
  params,
}: {
  params: Promise<{ category: string }>
}) {
  return (
    <div>
      <Hero />
      <Suspense fallback={<p>Loading products...</p>}>
        <ProductGrid paramsPromise={params} />
      </Suspense>
    </div>
  )
}
app/shop/[category]/page.js
import { Suspense } from 'react'
import { Hero } from './hero'
import { ProductGrid } from './product-grid'

export async function generateStaticParams() {
  const categories = await getCategories()
  return categories.map((c) => ({ category: c.slug }))
}

export default function ShopPage({ params }) {
  return (
    <div>
      <Hero />
      <Suspense fallback={<p>Loading products...</p>}>
        <ProductGrid paramsPromise={params} />
      </Suspense>
    </div>
  )
}

<Hero /> 作为静态外壳的一部分绘制。<ProductGrid> 在需要 category 时解析 params,仅在其边界内挂起。

你还可以使用 .then() 内联解包 promise,让子组件接收普通值而非 promise:

app/shop/[category]/page.tsx
<Suspense fallback={<p>Loading products...</p>}>
  {params.then(({ category }) => (
    <ProductGrid category={category} />
  ))}
</Suspense>
app/shop/[category]/page.js
<Suspense fallback={<p>Loading products...</p>}>
  {params.then(({ category }) => (
    <ProductGrid category={category} />
  ))}
</Suspense>

这使得 ProductGrid 保持简单(它接收 string 而非 Promise),同时仍将 params 访问推迟到 Suspense 边界内部。

何时使用 loading.js 与 <Suspense>#

loading.js<Suspense>
作用范围整个页面任意组件
设置直接放入一个文件显式包裹组件
导航作为即时回退内容预取默认不预取
最适合没有数据就无法渲染任何内容的页面大多数页面,用于细粒度控制

优先使用靠近动态访问位置的显式 <Suspense> 边界。当预渲染器遇到动态工作时,它会向上遍历组件树寻找最近的 Suspense 边界。如果找不到,构建会失败并出现阻塞路由错误。位于组件树较高位置的 loading.js 是有效的边界,因此框架会找到它并停止,但这样一来整页都会回退到骨架屏,而不是进行细粒度流式传输。

流式传输中的错误处理#

如果某个组件在流式渲染开始后抛出错误,最近的 error.js 边界会捕获它,并渲染错误 UI 来替代出错的组件。页面的其余部分保持不变,只有出错的部分被替换。

由于 HTTP 状态码(200 OK)已随第一个块发送,无法再将其改为 4xx 或 5xx。错误完全在流式 HTML 中处理。有关此限制的更多信息,请参阅 HTTP 约定。

向客户端流式传输数据#

你可以在 Server Component 中启动一次 fetch,并将未解析的 promise 作为 prop 传递给 Client Component。该 promise 可以按需传递任意多层。只有调用 React 的 use API 读取该值的组件需要在其周围加上 <Suspense> 边界:

app/dashboard/page.tsx
import { Suspense } from 'react'
import { StatsChart } from './stats-chart'

type Stats = { revenue: number; orders: number }

async function getStats(): Promise<Stats> {
  const res = await fetch('https://api.example.com/stats')
  return res.json()
}

export default function Dashboard() {
  // 在服务端渲染期间启动 fetch,不要 await 它
  const statsPromise = getStats()

  return (
    <Suspense fallback={<p>Loading chart...</p>}>
      <StatsChart dataPromise={statsPromise} />
    </Suspense>
  )
}
app/dashboard/page.js
import { Suspense } from 'react'
import { StatsChart } from './stats-chart'

async function getStats() {
  const res = await fetch('https://api.example.com/stats')
  return res.json()
}

export default function Dashboard() {
  // 在服务端渲染期间启动 fetch,不要 await 它
  const statsPromise = getStats()

  return (
    <Suspense fallback={<p>Loading chart...</p>}>
      <StatsChart dataPromise={statsPromise} />
    </Suspense>
  )
}
app/dashboard/stats-chart.tsx
'use client'

import { use } from 'react'

type Stats = { revenue: number; orders: number }

export function StatsChart({ dataPromise }: { dataPromise: Promise<Stats> }) {
  const stats = use(dataPromise)

  return <div></div>
}
app/dashboard/stats-chart.js
'use client'

import { use } from 'react'

export function StatsChart({ dataPromise }) {
  const stats = use(dataPromise)

  return <div></div>
}

回退内容会随静态外壳立即发送。当 promise 解析时,React 会将完成的 HTML 流式传入页面。

在组件树中共享 promise#

当多个组件需要相同的数据时,只需启动一次 fetch,并通过 context provider 传递该 promise,使子树中的任何组件都能用 use() 解析它:

app/layout.tsx
import { getUser } from '@/lib/data'
// 将 promise 存储在 React context 中供子树使用
import { UserProvider } from './user-provider'

export default function Layout({ children }: { children: React.ReactNode }) {
  const userPromise = getUser()

  return <UserProvider userPromise={userPromise}>{children}</UserProvider>
}

完整模式请参阅在 Context Provider 中使用 React 的 use。

在 Route Handlers 中实现流式渲染#

上述模式依赖 React 和 Suspense 来流式传输 UI。在 React 渲染之外,Route Handlers 可以使用 Web Streams API 流式传输原始响应。这对 Server-Sent Events、大文件生成,或任何你希望数据逐步到达的响应都很有用:

app/api/stream/route.ts
export async function GET() {
  const encoder = new TextEncoder()

  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 10; i++) {
        controller.enqueue(encoder.encode(`Chunk ${i + 1}\n`))
        await new Promise((resolve) => setTimeout(resolve, 200))
      }
      controller.close()
    },
  })

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/plain; charset=utf-8',
      'X-Content-Type-Options': 'nosniff',
    },
  })
}
app/api/stream/route.js
export async function GET() {
  const encoder = new TextEncoder()

  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 10; i++) {
        controller.enqueue(encoder.encode(`Chunk ${i + 1}\n`))
        await new Promise((resolve) => setTimeout(resolve, 200))
      }
      controller.close()
    },
  })

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/plain; charset=utf-8',
      'X-Content-Type-Options': 'nosniff',
    },
  })
}

在浏览器中直接访问此路由,或使用 curl 查看逐个到达的块:

bash
curl http://localhost:3000/api/stream

你还可以流式传输文件,而无需将其全部加载到内存中。使用 FileHandle.readableWebStream() 直接从文件获取 Web ReadableStream:

app/api/download/route.ts
import { open } from 'node:fs/promises'

export async function GET() {
  const file = await open('/path/to/large-file.csv')

  return new Response(file.readableWebStream(), {
    headers: {
      'Content-Type': 'text/csv',
      'Content-Disposition': 'attachment; filename="data.csv"',
    },
  })
}
app/api/download/route.js
import { open } from 'node:fs/promises'

export async function GET() {
  const file = await open('/path/to/large-file.csv')

  return new Response(file.readableWebStream(), {
    headers: {
      'Content-Type': 'text/csv',
      'Content-Disposition': 'attachment; filename="data.csv"',
    },
  })
}

有关构建流式端点的更多细节,请参阅 Route Handler API 参考。

流式渲染与 Web Vitals#

Web Vitals 是 Google 用来衡量用户体验的指标。流式渲染会直接影响其中几项。

TTFB 与 FCP#

不使用流式渲染时,服务器会等待所有数据后才发送任何 HTML,因此 TTFB 等于最慢的查询。使用流式渲染时,服务器会在静态外壳就绪后立即发送。TTFB 降为渲染布局和回退内容所需的时间。浏览器会立即绘制静态外壳,因此 FCP 与数据获取时间解耦。

LCP(最大内容绘制)#

如果你的 LCP 元素(主图、主标题、商品照片)位于 Suspense 边界内,它就无法在该边界的内容被替换之前绘制。这样,该元素就取决于服务器渲染它的工作,而非初始服务器响应时间。显示它也会在客户端产生开销,因为 React 会随边界的 HTML 流式传输一小段内联脚本,内容只有在该脚本运行后才会出现。

数据获取并不是边界延迟 LCP 元素的唯一原因。React 还会延迟较大的边界,因为发送其 HTML 需要时间。请参阅什么会激活 Suspense 边界。

小知识: 根据经验,只要存在 Suspense 边界,React 就可能使用它。在网络缓慢或 CPU 繁忙的情况下,并发渲染甚至可能在你意料之外回退到它。添加边界意味着接受这一点,因此不要添加不需要的边界。

要保持 LCP 较快:

  • 将 LCP 元素保持在 Suspense 边界之外或上方,使其作为静态外壳的一部分渲染。
  • 对已知需要在浏览器发现其 <img> 元素之前就开始加载的 LCP 图片,使用 next/image 的 preload prop。请参阅图片加载指南以在预加载、立即加载和 fetch 优先级之间做出选择。预加载控制图片的获取时机,而非绘制时机。位于边界内的图片仍需等待替换。
  • 对于非图片 LCP 元素(文本、标题),请将其渲染在 Suspense 边界之外。

CLS(累积布局偏移)#

当 Suspense 回退内容被解析后的内容替换时,浏览器会重新排布页面。如果回退内容与解析后内容尺寸不同,周围布局就会发生偏移。要最小化 CLS:

  • 设计骨架屏回退内容时,使其尺寸与所代表的内容一致。与最终卡片网格具有相同高度和宽度的骨架屏可以防止偏移。
  • 在 Suspense 边界周围使用固定或最小高度的容器,以便在内容到达前预留空间。

INP(交互到下一次绘制)#

流式渲染支持选择性水合:React 会在组件流式传入时独立水合,并优先水合用户正在交互的组件。每个 <Suspense> 边界都是一个水合单元。没有它们,React 会以一次阻塞式水合处理整个页面。有了它们,水合被拆分为更小的任务,这些任务会让出浏览器,使主线程保持响应。配套演示让你可以比较单次阻塞式水合与使用 Suspense 边界的拆分水合。

提前发现资源#

静态外壳在第一个 HTML 块中就包含 <link> 和 <script> 标签。浏览器会立即发现并开始获取 CSS、JavaScript 和字体,而服务器仍在生成内容。资源是在服务器思考期间获取的,而非之后。

在上面的仪表盘示例中,<h1> 在外壳中渲染(有利于 LCP),每个数据部分在其自己的 Suspense 边界后独立流式传输(有利于 INP,因为水合被拆分),骨架屏回退内容预留了空间(有利于 CLS)。

HTTP 约定#

一旦开始流式传输,HTTP 响应头(包括状态码)就已发送给客户端。流式传输开始后,你无法更改状态码或响应头。 本节的所有内容都源于这一基本约束。

状态码#

当 <Suspense> 回退内容渲染或组件挂起时,服务器必须确定使用 200 OK 以开始发送 HTML 流。如果 notFound() 在流中触发,Next.js 无法回头将状态改为 404。相反,它会在流式 HTML 中注入 <meta name="robots" content="noindex">,使搜索引擎不索引该页面。同样,流中的 redirect() 会变成客户端重定向,而非 HTTP 重定向响应头。

流式传输何时开始?#

当 Suspense 回退内容渲染时(例如 loading.tsx),或当某个组件在 <Suspense> 边界下挂起时,响应体就开始流式传输。要返回 404,请将 notFound() 放在边界之前:

app/post/[slug]/page.tsx
import { Suspense } from 'react'
import { notFound } from 'next/navigation'
import { PostContent } from './post-content'

export async function generateStaticParams() {
  const posts = await getPublishedPosts()
  return posts.map((post) => ({ slug: post.slug }))
}

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const exists = await checkSlugExists(slug) // 快速存在性检查
  if (!exists) notFound() // 在流式传输开始前返回 404

  return (
    <Suspense fallback={<p>Loading post...</p>}>
      <PostContent slug={slug} />
    </Suspense>
  )
}
app/post/[slug]/page.js
import { Suspense } from 'react'
import { notFound } from 'next/navigation'
import { PostContent } from './post-content'

export async function generateStaticParams() {
  const posts = await getPublishedPosts()
  return posts.map((post) => ({ slug: post.slug }))
}

export default async function PostPage({ params }) {
  const { slug } = await params
  const exists = await checkSlugExists(slug) // 快速存在性检查
  if (!exists) notFound() // 在流式传输开始前返回 404

  return (
    <Suspense fallback={<p>Loading post...</p>}>
      <PostContent slug={slug} />
    </Suspense>
  )
}

小知识: 借助 Cache Components,Next.js 会在请求时检查运行的同时发送预渲染外壳以及预加载 CSS、字体和图片的响应头。即使外壳没有可见 UI 或路由设置了 instant = false,这也会启动一个 200 响应。之后的 notFound() 仍会渲染 not-found UI 并添加 noindex。

要返回请求时的 404,请在页面渲染之前使用 Proxy。Proxy 还可以在渲染开始前重定向、重写或返回响应。next.config.js 中配置的重定向同样在页面渲染前运行。

机器人与爬虫#

仅限于 HTML 的机器人和爬虫需要元数据在初始 HTML 的 <head> 中可用。Next.js 通过它们的 user agent 来识别它们,并在流式传输页面内容之前等待 generateMetadata 解析。完整浏览器和支持 DOM 的爬虫则可以直接接收与页面内容一起的流式元数据。

你可以使用 htmlLimitedBots 配置选项自定义哪些机器人接收阻塞式元数据。更多细节请参阅 loading.js SEO 部分。

Cache Components#

借助 Cache Components,访客和支持 DOM 的爬虫会立即收到预渲染外壳,动态内容则在解析时流式传入。仅限于 HTML 的机器人会跳过预渲染外壳并动态渲染页面,以便将元数据放入 <head>。元数据解析完成后,其余页面内容仍可流式传输。

当你的预渲染外壳依赖于仅在预渲染时存在的输入(例如构建时数据或在请求时环境中无法访问的值)时,请记住这一点。访客和支持 DOM 的爬虫会收到外壳而无需重新运行该代码,但仅限于 HTML 的机器人会动态重新渲染它,因此一个人能正常加载的页面可能无法为爬虫渲染。请确保外壳依赖的任何数据在请求时也可用。

可能影响流式渲染的因素#

服务器与客户端之间任何会缓冲响应的层都会削弱流式渲染的好处。HTML 可能在服务器上已逐步完整生成,但如果代理、CDN 甚至客户端自身在渲染前收集了所有块,用户看到的就是一个延迟的单一响应,而非渐进式渲染。

反向代理#

Nginx 和类似的反向代理默认会缓冲响应。通过将 X-Accel-Buffering 响应头设置为 no 来禁用缓冲:

next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*{/}?',
        headers: [
          {
            key: 'X-Accel-Buffering',
            value: 'no',
          },
        ],
      },
    ]
  },
}

CDN#

内容分发网络可能会在将整个响应转发给客户端之前对其进行缓冲。请查阅你的 CDN 提供商文档了解流式传输支持。有些 CDN 需要特定配置或套餐层级才能透传分块响应。

Serverless 平台#

并非所有 serverless 环境都支持流式渲染。例如,AWS Lambda 需要显式启用响应流式模式(默认未启用)。Vercel 原生支持流式渲染。

压缩#

Gzip 和 Brotli 压缩在刷新之前可能会在内部缓冲块,因为压缩算法需要足够的数据才能高效压缩。这可能会增加第一个可见块的延迟。如果你发现流式传输延迟,请检查压缩层是否足够积极地刷新。

客户端#

缓冲也会发生在客户端。Safari/WebKit 会缓冲流式响应,直到收到 1024 字节,因此非常小的响应会一次性绘制,而非渐进式绘制。真实应用很容易超过这个阈值(布局、样式、脚本),所以它只影响极简演示或极小的 Route Handler 响应。

像 curl 这样的命令行工具默认也会缓冲。-N 标志会禁用输出缓冲,但 curl 仍依赖换行符来将行刷新到终端。如果流发送的块不带换行符,即使使用 -N 也可能看起来停滞。

验证流式渲染是否生效#

本节介绍如何确认 HTTP 响应确实以块的形式穿过你的基础设施到达。关于设计有意义的加载状态和有效放置 Suspense 边界的指导,请参阅使用 <Suspense> 的细粒度流式渲染和 Cache Components 指南。

检查 Network 面板。 在 Chrome DevTools 中,选中 document 请求并查看 "Timing" 明细。较长的 "Content Download" 阶段加上较早的 "Time to First Byte",可以确认响应是流式传输的,而非一次性到达。

观察原始块。 要确切了解服务器发送了什么以及何时发送,可以使用一个将响应作为流读取的小脚本。这比 curl 更可靠,因为 curl 有自己的缓冲行为:

stream-observer.mjs
const res = await fetch(
  'https://streaming-demo.labs.vercel.dev/suspense-demo',
  {
    headers: { 'Accept-Encoding': 'identity' },
  }
)

const reader = res.body.getReader()
const decoder = new TextDecoder()
let i = 0
const start = Date.now()

while (true) {
  const { done, value } = await reader.read()
  if (done) break
  console.log(`\nchunk ${i++} (+${Date.now() - start}ms)\n`)
  console.log(decoder.decode(value))
}

使用 node stream-observer.mjs 运行。对于具有两个兄弟 Suspense 边界的页面(例如配套演示的 Suspense 页面),你将看到类似如下的输出:

Terminal
chunk 0 (+0ms)    # 静态外壳:<head>、CSS、导航、回退骨架屏、
                  # <template id="B:0"> 和 <template id="B:1"> 占位符、
                  # 引导脚本
chunk 1 (+170ms)  # 用于水合的组件 payload (self.__next_f.push)
chunk 2 (+1000ms) # 天气组件:payload + <div hidden id="S:0">(替换 B:0)
chunk 3 (+3000ms) # 分析仪表盘:payload + <div hidden id="S:1">(替换 B:1)

<template id="B:0"> 标记是 Suspense 回退内容的占位符。当某个边界解析完成时,React 会流式传输一个包含完成 HTML 的 <div hidden id="S:0">,以及一个将其替换到页面中的脚本。时间戳显示每个边界独立解析。

小知识: Accept-Encoding: identity 请求头会禁用压缩,使块不会被压缩层缓冲。

对比机器人请求。 在同一脚本中添加机器人 user agent:headers: { 'User-Agent': 'Twitterbot/1.0', 'Accept-Encoding': 'identity' }。现在 await fetch() 本身会阻塞直到完整渲染完成(此页面约 3 秒),因为服务器会保留响应直到获得完整文档。随后响应体会一次性到达,没有交错的 +1000ms / +3000ms 时间戳:

Terminal
chunk 0 (+0ms) # 完整文档一次性突发到达,此前 fetch() 已等待

这就是机器人与爬虫的行为:服务器等待完整渲染并发送一个完整的 HTML 文档,而不是流式传输。

平台支持#

部署选项是否支持
Node.js server是
Docker container是
Static export否
Adapters取决于平台

详细配置说明请参阅自托管指南。

总结#

触发因素是你的代码:异步工作、非确定性输出或运行时数据。当框架遇到这些情况时,它会向上遍历组件树寻找 <Suspense> 边界作为回退内容。这些边界之上的所有内容构成静态外壳,并立即发送。当每个边界解析完成时,React 会将结果流式传入页面。

关键决策是缓存什么以及将 Suspense 边界放在哪里。使用 "use cache" 缓存一切可以缓存的内容,以扩大静态外壳。将动态访问下推到需要它的组件,并用 <Suspense> 包裹它们。其余内容都会成为外壳的一部分。

有关将这些模式应用于现有路由的分步工作流程,请参阅优化静态外壳。

延伸阅读#

  • RSC Explorer - 交互式工具,用于探索组件 payload 格式,了解 React 如何从流式块中重建组件树
  • web.dev 上的 Streams API - Web Streams API 简介,它是 Route Handlers 中流式渲染的基础
  • 分块传输编码(MDN) - 实现流式响应的 HTTP/1.1 机制
  • browser.engineering - 深入探讨浏览器如何处理网络响应、渲染和渐进式显示
  • 防止水合前闪烁 - 如何在浏览器绘制之前用客户端特定的值(区域设置、主题、持久化状态)更新服务端渲染的 HTML
Next.js 中文网