流式渲染
了解流式渲染在 Next.js 中的工作原理,以及如何利用它在数据可用时逐步渲染 UI。
什么是流式渲染?#
在传统的服务端渲染中,服务器会先生成完整的 HTML 文档,然后才发送任何内容。一个缓慢的数据库查询或 API 调用就可能阻塞整个页面。流式渲染通过使用分块传输编码在响应各部分就绪时将其发送,从而改变了这一点。浏览器会在服务器仍在生成其余内容时就开始渲染 HTML。
这对于将快速的静态内容(页头、导航、布局)与较慢的动态内容(个性化数据、分析、推荐)结合在一起的页面尤其有意义。静态部分可以预渲染并从 CDN 提供服务,立即绘制,而动态部分则在就绪后从服务器流式传入。
React 的服务端渲染器会按与 <Suspense> 边界对齐的块来生成 HTML。Next.js 将其集成到 App Router 中,因此无需额外配置即可使用流式渲染。
示例#
配套的流式渲染演示(源码)让你可以看到本指南中的每个概念的实际效果:
- 使用
loading.tsx的页面级流式渲染(骨架屏立即出现,内容约 2 秒后流式传入) - 使用独立解析的兄弟
<Suspense>边界进行细粒度流式渲染 - 水合对比:单次阻塞式水合与使用 Suspense 边界的拆分水合
- 在 Route Handler 中流式传输原始 HTML,并提前发现 CSS
- 一个可配置的
ReadableStreamAPI 端点,用于试验块大小和浏览器缓冲
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> 边界包裹页面内容,并将你的加载组件作为回退内容。
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>
)
}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> 边界中。每个边界都会在其异步工作完成时独立流式传输,无论完成顺序如何,彼此都不会阻塞:
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>
)
}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> 边界以创建分层的加载体验。例如,商品页面可能立即流式传输页头,接着是商品详情,最后是评论:
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>
)
}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> 边界内解析它:
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>
)
}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 传递给需要该值的组件:
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>
)
}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:
<Suspense fallback={<p>Loading products...</p>}>
{params.then(({ category }) => (
<ProductGrid category={category} />
))}
</Suspense><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> 边界:
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>
)
}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>
)
}'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>
}'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() 解析它:
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、大文件生成,或任何你希望数据逐步到达的响应都很有用:
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',
},
})
}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 查看逐个到达的块:
curl http://localhost:3000/api/stream你还可以流式传输文件,而无需将其全部加载到内存中。使用 FileHandle.readableWebStream() 直接从文件获取 Web ReadableStream:
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"',
},
})
}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的preloadprop。请参阅图片加载指南以在预加载、立即加载和 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() 放在边界之前:
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>
)
}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 来禁用缓冲:
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 有自己的缓冲行为:
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 页面),你将看到类似如下的输出:
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 时间戳:
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