React 18 流式渲染：renderToPipeableStream 的工作原理

在 React 18 之前，服务端渲染使用 renderToString，这是同步的：React 会先将整个组件树渲染为字符串，然后再向浏览器发送任何 HTML。如果某个组件需要加载数据，服务器就必须等待所有数据准备完成后，首个字节才能传到用户那里。

React 18 引入了 renderToPipeableStream，它会将组件树渲染为 HTML 数据块流。React 不必等待所有内容准备就绪，而是在组件树的各个部分完成后就发送相应的 HTML，使浏览器能够立即开始渲染可见内容。

renderToPipeableStream 会返回一个包含两个方法的对象：pipe(writable) 和 abort()。pipe 接受 Node.js Writable 流（通常是 HTTP 响应），并开始向其中传输 HTML。abort() 会取消该数据流，用于请求被取消或超出超时时间的情况。

数据流从 HTML 外壳开始——也就是所有未被待处理的 Suspense 边界阻塞的内容。这包括文档头部、导航、页脚、布局框架以及任何可同步获得的内容。外壳会立即开始传输，早于任何依赖数据的组件完成解析。

Suspense 边界内等待数据的组件最初会以其后备界面进行传输（例如加载指示器）。React 稍后会发送一个脚本标签，用解析后的内容替换后备界面——整个过程无需在客户端重新渲染外壳。

将 bootstrapScripts: ['/static/js/client.js'] 传递给 renderToPipeableStream，告诉 React 在数据流末尾注入一个脚本标签。浏览器会加载此包并调用 hydrateRoot，将 React 的事件处理器附加到服务端渲染的 DOM 上。

当 HTML 外壳（待处理的 Suspense 边界之外的所有内容）准备发送时，onShellReady 会触发。这是调用 pipe(res) 的正确时机——但请务必在调用 pipe 之前设置 HTTP 状态码和响应标头，因为开始流式传输后 HTTP 状态就会被锁定。

由于调用 pipe() 后会立即开始流式传输，因此任何 res.setHeader 或 res.statusCode 赋值都必须在调用 pipe 之前完成。常见做法是在 onShellReady 回调中将状态码设置为 200，并将 Content-Type 设置为 text/html，然后立即调用 pipe(res)。

onShellError 会在外壳完成渲染前发生不可恢复的错误时触发——例如，顶层组件在任何 Suspense 边界之外抛出错误。在这种情况下，您无法流式传输部分响应；相反，应重定向到错误页面，或发送静态错误 HTML 文档。

整个 React 树（包括所有 Suspense 边界）都已解析完成时，onAllReady 会触发。对于搜索引擎爬虫和社交媒体链接预览器，您需要发送完整 HTML，而不是进行流式传输。请检查请求是否来自机器人，并在 onAllReady 中调用 pipe(res)，而不是在 onShellReady 中调用。

Suspense 边界中的错误会触发 onError——React 仍可在该边界回退到错误界面的同时继续流式传输页面其余内容。请使用 onError 将错误记录到您的可观测性流水线中，而不要为用户中止流式传输。

应该在什么时候使用 onAllReady，而不是 onShellReady 来开始调用 pipe？

renderToPipeableStream 是 Node.js 服务器用于流式 SSR 的基础 API。它通过 onShellReady 立即流式传输 HTML 外壳，在数据解析完成后填充 Suspense 边界，并通过 bootstrapScripts 对客户端进行水合。请对机器人和爬虫使用 onAllReady，在发生致命失败时使用 onShellError，并始终在调用 pipe() 前设置 HTTP 标头。