Front-End Checklist 实践指南：用 Streaming HTML 把 TTFB 从 800ms 压到 10ms

本文基于 Front-End Checklist 仓库中的streaming-html性能规则（规则文档 与 SKILL.md）展开，系统讲解如何利用 HTTP 分块传输与 ReactrenderToPipeableStream/ WebReadableStream，在服务端渲染时先发外壳、后流式补全内容，从而显著降低 Time to First Byte（TTFB）与 First Contentful Paint（FCP）。读完本文，你将掌握三种落地姿势：自定义 Node.js/Express 环境的renderToPipeableStream、Next.js App Router 的 Suspense 流式渲染，以及非 React 环境的 Web Streams 实现，并学会用 WebPageTest 与 DevTools 验证流式是否真正生效。

流式渲染为什么能赢：分块传输与"先发外壳"

HTML streaming 依赖 HTTP 的分块传输编码（Transfer-Encoding: chunked）。它允许服务器在不知道响应总长度的情况下，把响应分成多个 chunk 陆续发送。浏览器每收到一块就开始解析，并在最后一块到达之前就去发现和拉取 CSS、字体、脚本、图片等子资源。

传统（缓冲式）SSR 的时间线是串行的：

0ms Server starts executing 800ms All database queries complete 800ms HTML generation begins 820ms HTML generation completes 820ms TTFB — first byte arrives in browser 850ms CSS parsed 900ms FCP

采用流式渲染后，慢查询与页面外壳的交付被解耦：

0ms Server starts executing 10ms TTFB — shell HTML flushed immediately (head, above-fold skeleton) 10ms Browser fetches CSS, discovers LCP image 300ms Slow data query completes; component HTML streamed 380ms FCP — above-fold content painted

在这个例子里，浏览器开始工作的时间提前了 790ms。核心原理正如规则文档 references/rule.md 所强调的：传统 SSR 必须等所有数据请求完成后才发送第一个字节，浏览器在慢查询结束前无法解析 HTML、发现子资源或渲染任何内容；流式则把首屏以上内容的交付从慢数据库查询和第三方 API 调用中解放出来，直接改善感知性能与 Largest Contentful Paint（LCP）。

判定规则：何时该检查、怎么修、怎么评审

SKILL.md 为这项规则定义了明确的检查口径，可作为 Code Review 与 AI Agent 审查的清单：

• Check（检查）：审查服务端渲染实现，判断 HTML 是按块流式发送，还是等全部生成后才缓冲发给客户端；
• Fix（修复）：重构 SSR 实现，改用renderToPipeableStream+ 围绕慢数据请求的 Suspense 边界，或在 Node.js handler 中使用ReadableStream，让首屏以上 HTML 立即冲刷给客户端；
• Explain（解释）：说明流式 HTML 如何通过解耦快速内容与慢速服务端数据依赖来改善 TTFB 和 FCP；
• Code Review（评审重点）：检查服务端入口与页面组件中是否存在renderToString调用、数据请求组件是否缺少 Suspense 边界、响应返回前是否对慢查询进行了不必要的await。

React 方案：renderToPipeableStream 与 onShellReady

renderToPipeableStream是 React 的流式 SSR API。它接收一个 React 树，把渲染结果按块写入 Node.js 的可写流。最关键的选项是onShellReady——当应用外壳（Suspense 边界之外的所有内容）可以发送时被调用：

// server/render.ts (custom Express / Node.js setup) import { renderToPipeableStream } from 'react-dom/server'; import { IncomingMessage, ServerResponse } from 'http'; import App from './App'; export function handleRequest(req: IncomingMessage, res: ServerResponse) { let didError = false; const { pipe, abort } = renderToPipeableStream( <App url={req.url} />, { // bootstrapScripts is optional — use for client hydration bootstrapScripts: ['/static/js/main.js'], onShellReady() { // The shell is the minimal HTML that does not depend on Suspense // boundaries — flush it immediately for a low TTFB res.statusCode = didError ? 500 : 200; res.setHeader('Content-Type', 'text/html; charset=utf-8'); // chunked transfer is automatic when the length is unknown pipe(res); }, onShellError(error) { // Shell rendering failed — fall back to a basic error page res.statusCode = 500; res.setHeader('Content-Type', 'text/html'); res.end('<h1>Something went wrong</h1>'); }, onError(error) { didError = true; console.error(error); }, } ); // Abort streaming after 10 seconds to avoid hanging connections setTimeout(abort, 10_000); }

要点解析：

• onShellReady：外壳就绪即pipe(res)，此时不依赖 Suspense 边界的最小 HTML 会立刻冲刷出去，TTFB 只受外壳渲染时间影响；
• onShellError：外壳渲染失败时的兜底路径，直接返回 500 与基础错误页；
• onError：流式过程中任一处渲染出错都会触发，通过didError标记让状态码最终反映为 500；
• bootstrapScripts：可选，用于客户端水合（hydration）时注入入口脚本；
• abort：配合setTimeout设置 10 秒超时，避免慢请求挂起连接；
• 当响应长度未知时，Node.js 会自动使用Transfer-Encoding: chunked，无需手动设置。

Next.js App Router：默认流式 + 细粒度 Suspense

Next.js App Router 默认就会流式输出。任何包裹数据请求的asyncServer Component 本身就是一个天然的 Suspense 边界，而显式使用<Suspense>可以精确控制哪些内容先被冲刷：

// app/dashboard/page.tsx import { Suspense } from 'react'; import { DashboardSkeleton, RecentOrdersSkeleton } from '@/components/skeletons'; export default function DashboardPage() { return ( <main> {/* The page title and navigation are part of the shell — they render immediately without waiting for any data. */} <h1>Dashboard</h1> <nav>{/* ... */}</nav> {/* KPICards fetches summary stats. If it is slow, show a skeleton rather than blocking the page shell. */} <Suspense fallback={<DashboardSkeleton />}> <KPICards /> </Suspense> {/* RecentOrders fetches a paginated list — isolated in its own boundary so it does not block KPICards. */} <Suspense fallback={<RecentOrdersSkeleton />}> <RecentOrders /> </Suspense> </main> ); } // KPICards is a Server Component that fetches its own data async function KPICards() { const stats = await fetchKPIStats(); // potentially slow return <ul>{stats.map((s) => <KPICard key={s.id} stat={s} />)}</ul>; } async function RecentOrders() { const orders = await fetchRecentOrders(); // independent query return <OrderList orders={orders} />; }

Next.js 会立即冲刷<h1>Dashboard</h1>和导航栏的 HTML，随后在KPICards、RecentOrders各自的数据解析完成后，利用 React 的 slot 机制把它们按任意顺序流式补入。

⚠️边界太粗会杀死流式：如果把整页包进单个 Suspense 边界，那么在所有数据就绪前不会冲刷任何内容——效果与缓冲式 SSR 完全一致。必须围绕每个独立取数的区块建立细粒度边界，确保首屏以上内容永远不会被首屏以下的数据阻塞。

仓库实例：Front-End Checklist 站点的 Suspense 用法

这一实践在本仓库的 Next.js 前端中已落地，可作为对照参考：

• home-page-content.tsx 将赞助商区块包进<Suspense fallback={<SponsorsSectionFallback />}>，同时外层再用ErrorBoundary兜底，页面其余区块（Hero、分类、清单预览等）不与赞助商数据请求互相阻塞；
• sponsors-section-async.tsx 是一个 async Server Component，内部await fetchAllSponsors()拉取赞助商数据，注释明确要求它必须被 Suspense 包裹，以免该请求阻塞页面导航；同文件的SponsorsSectionFallback（L21-L48）提供了流式等待期间的骨架屏（aria-labelledby、spinner）；
• rules/page.tsx/rules/page.tsx#L80) 在规则浏览区使用<Suspense fallback={<RulesBrowserSkeleton />}>，配合'use cache'与cachePublicContent()做内容缓存，静态页外壳先行、交互区数据后补。

非 React 环境：Node.js ReadableStream

在不使用 React 的服务器环境（纯 Node.js / Deno / Cloudflare Workers）中，可以用 Web Streams API 直接流式发送 HTML chunk：

// Plain Node.js / Deno / Cloudflare Workers example export function createStreamingResponse( getSlowData: () => Promise<string> ): Response { const encoder = new TextEncoder(); const stream = new ReadableStream({ async start(controller) { // Flush the page shell immediately controller.enqueue( encoder.encode(`<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>My App</title> <link rel="stylesheet" href="/styles.css"> </head> <body> <header><nav><!-- navigation --></nav></header> <main id="content"> <div class="loading-skeleton" aria-busy="true" aria-label="Loading content..."> </div> `) ); // Fetch slow data while the browser is already parsing the shell const data = await getSlowData(); // Stream the content section once data is ready controller.enqueue( encoder.encode(` <script> // Replace skeleton with real content document.getElementById('content').innerHTML = ${JSON.stringify(data)}; </script> </main> </body> </html>`) ); controller.close(); }, }); return new Response(stream, { headers: { 'Content-Type': 'text/html; charset=utf-8', // Disable any response buffering by proxies 'X-Accel-Buffering': 'no', }, }); }

关键点：骨架 HTML 先enqueue冲刷，浏览器解析骨架的同时服务端并行等待慢数据；数据就绪后再enqueue内容区块并通过内联脚本替换骨架。注意骨架使用aria-busy="true"与aria-label，即使是无 React 的流式方案也保持无障碍语义。

首块冲刷资源提示：把 preload 放进第一个 chunk

流式最有价值的模式之一，是在页面内容尚未完全确定时，就把<link rel="preload">提示放进第一块 HTML：

// First chunk always includes critical resource hints const shellChunk = `<!DOCTYPE html> <html> <head> <!-- Preload the LCP image — browser starts fetching immediately --> <link rel="preload" as="image" href="/hero.webp" fetchpriority="high"> <!-- Preload critical fonts --> <link rel="preload" as="font" type="font/woff2" href="/fonts/inter.woff2" crossorigin> <link rel="stylesheet" href="/critical.css"> </head> <body> <div id="app"> `;

LCP 图片用fetchpriority="high"的 preload 让浏览器立即开始下载，字体用type="font/woff2"+crossorigin预取——这些请求从 TTFB 时刻就与 HTML 解析并行，这正是本仓库render-blocking规则与streaming-html规则互相呼应的结合点（见 streaming-html.mdx 的 relatedRules）。

⚠️CDN 与代理缓冲会抵消流式：Nginx、Cloudflare 等代理常会先把响应缓冲完再转发给下游，这会让流式彻底失效。Nginx 下设置X-Accel-Buffering: no，并确保你的 CDN 对 HTML 响应启用流式直通（streaming pass-through）。

测量与验证：让流式"可证明"

流式只有在浏览器真正提前收到并开始解析第一个 chunk 时才有效，因此必须验证而不只是相信配置。

WebPageTest 瀑布图验证

1. 第一条绿色条（Time to First Byte）应低于 200ms；
2. CSS 与 LCP 图片请求应在 HTML 条仍处于活动状态时就开始；
3. DevTools Performance 中的 "Layout" 事件应发生在响应完成之前。

自动化检查

• 打开 DevTools Network 面板点击页面请求，Response 标签应显示 HTML 以多个 chunk 到达（响应会在数百毫秒内持续接收后续 chunk，而非瞬间"完成"）；
• 运行 Lighthouse，确认 TTFB 低于 600ms（绿色）、FCP 低于 1.8s——SKILL.md 的 Quick Reference 也明确提示：Lighthouse 中 TTFB 超过 600ms 通常是未使用流式的信号；
• 在 DevTools 中以模拟 3G 网络测试：即使数据需要 3～5 秒，骨架 UI 也应快速出现。

手动检查

• 在 Next.js 中，于被 Suspense 包裹的 async Server Component 内添加console.log('rendering KPICards')，观察服务器日志：页面加载事件应早于该日志出现，从而证明外壳先于慢组件冲刷。

关联规则与阅读延伸

该规则在 Front-End Checklist 规则库 中归属performance大类、rendering子类，难度为 advanced，预计耗时 45 分钟。与其配套的关联规则包括：

• ttfb：当瓶颈是服务端数据拉取时间时，流式是降低 TTFB 的首要服务端手段；
• largest-contentful-paint：更快地流式输出首屏 HTML，通过更早发现并加载 LCP 图片或文本元素直接降低 LCP；
• render-blocking：流式可在初始 chunk 中冲刷 preload 提示，让浏览器在完整响应到达前就获取关键资源；
• list-virtualization：两者同属performance/rendering区域，常一起评审。

同时，仓库为 Agent/LLM 落地评审提供了结构化的 SKILL.md（含 check / fix / explain / code review 四段提示词）与完整实操版 references/rule.md，在代码评审中可直接按此清单逐项核对。

小结：让慢数据不再阻塞首屏

流式渲染的本质，是把"生成完整 HTML"这一个串行任务拆成"外壳 + 多个独立内容区块"的并行流水线：浏览器从 TTFB 开始解析、发现并拉取子资源，慢查询完成后内容再按块补入。落地时记住三条主线：自定义 React SSR 用renderToPipeableStream的onShellReady即时pipe；Next.js App Router 用细粒度<Suspense>隔离每个独立取数区块；非 React 环境用ReadableStream配合X-Accel-Buffering: no绕过代理缓冲。最后务必用瀑布图与 Lighthouse 阈值（TTFB < 600ms、FCP < 1.8s）证明流式真实生效。