来自边缘的流式 SSR

当服务器以流式方式传输 HTML 时，浏览器会分块接收并渲染内容，而不是等待完整文档。这意味着用户可以看到并交互页面中已经可见的部分——页眉、导航、主视觉区域——同时依赖较慢数据的部分仍在加载。

向 renderToReadableStream 传入 bootstrapScripts 会告诉 React 客户端 JS 代码包所在的位置。React 会在流末尾注入脚本标签，让浏览器加载代码包并调用 hydrateRoot，使页面随着各个部分完成流式传输而变得可交互。

React 的流式传输依赖 Suspense 边界，将组件树拆分成可以独立传输的部分。Suspense 边界内等待数据的组件（通过抛出 Promise）会先以占位内容传输，随后完成解析并在稍后传输真实内容。

onShellReady 回调在非挂起的 HTML 外壳（Suspense 边界之外的所有内容）准备好进行流式传输时触发。这是设置 HTTP 状态码和响应标头，然后调用 pipe(res) 或开始从 ReadableStream 读取的正确时机。

HTTP 状态码和标头必须在响应正文开始之前发送。由于流式传输在 onShellReady 时开始，任何错误处理逻辑（设置状态 500、重定向）都必须在外壳开始传输之前执行——一旦开始流式传输，状态码就会锁定。

onShellError 在外壳准备好之前发生致命错误时触发——例如，顶层组件（位于任何 Suspense 边界之外）发生错误。此时外壳不会进行流式传输，您应返回静态错误页面或重定向到错误路由。

onError 对 Suspense 边界内可恢复的错误触发。React 仍可传输页面的其余部分；出错的边界会渲染其错误回退界面。使用 onError 进行日志记录：将错误捕获到可观测性平台，而不要中止流。

如果 Suspense 边界的数据耗时过长，请先流式传输外壳，并让该边界在客户端完成水合。请实现一个超时机制：5 秒后，如果该边界尚未解析完成，就终止该流；客户端将通过 useEffect 自行获取数据。

Workers 运行时会将 ReadableStream 直接作为响应体传递。Cloudflare 的基础设施会在 React 生成每个数据块时，将其转发到用户的浏览器，而不会缓存整个文档。这意味着，请求到达后数毫秒内，HTML 的首个字节就会离开边缘节点。

renderToReadableStream 会返回一个用于中止的控制器函数。如果请求被取消（例如用户离开当前页面），调用这个函数会阻止 React 继续渲染和处理数据。这样可以避免对孤立请求进行无效计算，并将 Worker 的 CPU 使用量控制在合理范围内。

采用边缘流式传输后，完整的延迟链路如下：5 毫秒（请求发送到最近的边缘节点）+ 2 毫秒（Worker 冷启动）+ 8 毫秒（外壳渲染）= 首字节耗时 15 毫秒。用户的浏览器会先从外壳中渲染 LCP 元素，同时页面的其余部分继续在后台传输。

在流式传输 SSR 的过程中，onShellReady 回调究竟会在什么时候触发？

边缘流式 SSR 会分块传输 HTML，通过立即发送外壳来改善 FCP 和 LCP。Suspense 边界将组件树划分为可以独立传输的部分。onShellReady 是开始传输的信号——调用它之前请先设置状态码。onShellError 处理致命故障，onError 处理可恢复故障，而中止操作可以避免在请求取消后继续浪费工作。