解析 `Streaming SSR`：如何利用 HTTP 流式传输让 React 组件“分批次”到达浏览器？ - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

尊敬的各位同仁，

欢迎来到今天的讲座。今天我们将深入探讨 React 18 引入的一项革命性特性：Streaming SSR (流式服务器端渲染)。我们将剖析其核心原理——如何利用 HTTP 流式传输，让 React 组件不再是“一蹴而就”，而是“分批次”抵达浏览器，从而显著提升用户体验和应用性能。

在前端开发日益复杂的今天，我们不仅追求功能完整，更要关注用户感知的速度和交互的流畅性。传统 SSR 解决了首次加载的白屏问题，但它本身也存在一些瓶颈。Streaming SSR 正是为了突破这些瓶颈而生。

I. 传统 SSR 的局限性与挑战

在深入 Streaming SSR 之前，我们有必要回顾一下传统的服务器端渲染（SSR）是如何工作的，以及它所面临的挑战。

1. 传统 SSR 的工作原理回顾

传统 SSR 的基本流程如下：

用户请求： 浏览器向服务器发送一个页面请求。
服务器渲染： 服务器接收请求后，在 Node.js 环境中执行 React 应用的渲染逻辑，将所有组件渲染成完整的 HTML 字符串。这个过程通常包括数据获取（例如从数据库或外部 API）。
发送完整 HTML： 服务器将这个完整的 HTML 字符串作为 HTTP 响应发送给浏览器。
浏览器解析与呈现： 浏览器接收到 HTML 后，立即解析并显示页面内容（First Contentful Paint, FCP）。
客户端 Hydration (水合): 浏览器下载并执行客户端 JavaScript。React 接管已经渲染的 HTML，将其与客户端的虚拟 DOM 结构关联起来，并附加事件监听器，使页面变为可交互（Time To Interactive, TTI）。

2. 传统 SSR 的主要瓶颈

尽管传统 SSR 解决了客户端渲染（CSR）的白屏问题并改善了 SEO，但它带来了新的性能挑战：

TTFB (Time To First Byte) 延迟： 服务器必须等待所有数据获取完成、所有组件渲染成 HTML 后，才能发送第一个字节。如果页面中包含多个慢速数据源，或者组件树非常庞大，用户就会经历较长的白屏时间。
- 例如，一个页面需要从 A、B、C 三个不同的微服务获取数据，如果 B 服务响应最慢，那么整个 HTML 的生成就必须等待 B 完成。
全量 Hydration 阻塞： 即使 HTML 已经显示，用户也无法立即与页面交互。因为浏览器需要下载所有 JavaScript，然后 React 才能进行 Hydration。如果 JavaScript 包很大，或者组件树很复杂，Hydration 过程可能会耗时很长，阻塞主线程，导致页面看起来是可用的，但实际却无法点击，用户体验不佳。
- 一旦 Hydration 开始，它会尝试水合整个组件树。如果某个组件的 Hydration 逻辑复杂或耗时，它会阻塞其他组件的 Hydration，直到它自己完成。

示意图：传统 SSR 的时间线

阶段	描述	用户感知
服务器
数据获取 (慢)	阻塞，等待所有异步数据返回
组件渲染 (慢)	阻塞，等待所有组件渲染成 HTML
TTFB	服务器发送第一个字节	白屏
浏览器
接收 HTML
解析 HTML / FCP	显示页面内容（但不可交互）	可见
下载 JS	阻塞，下载所有客户端 JavaScript	可见
执行 JS	阻塞主线程，React 进行全量 Hydration	可见
TTI	页面完全可交互	可交互

这些限制促使 React 团队思考新的渲染范式，目标是：在服务器端就能实现渐进式渲染，并允许客户端进行渐进式 Hydration。 这正是 Streaming SSR 的核心价值。

II. 异步渲染与 Suspense 的崛起

React 18 是一个里程碑式的版本，它引入了并发模式（Concurrent Mode）和一系列新的 API，为 Streaming SSR 奠定了基础。其中，Suspense 组件是实现异步渲染和流式传输的关键。

1. React 并发模式

并发模式允许 React 在不阻塞主线程的情况下执行多个渲染任务。这意味着 React 可以中断一个正在进行的渲染，处理更高优先级的更新（例如用户输入），然后再恢复被中断的任务。这大大提升了应用的响应性和用户体验。

2. Suspense 组件

Suspense 是一个边界组件，它允许你“暂停”渲染组件树的一部分，直到某个异步操作（如数据获取、代码分割加载）完成。在此期间，Suspense 会渲染一个“回退 UI”（fallback UI）。

基本用法：

import React, { Suspense } from 'react';

// 假设这是一个异步加载的组件，或一个内部包含异步数据获取的组件
const AsyncComponent = React.lazy(() => import('./AsyncComponent'));
// 或者，更常见的是，AsyncComponent 内部使用 Suspense-enabled data fetching 库

function App() {
  return (
    <div>
      <h1>欢迎来到我的应用</h1>
      <Suspense fallback={<p>加载中...</p>}>
        <AsyncComponent />
      </Suspense>
      <p>这是应用的底部内容。</p>
    </div>
  );
}

在客户端渲染中，当 AsyncComponent 还没有加载完成或其内部数据尚未获取时，Suspense 会显示 <p>加载中...</p>。一旦 AsyncComponent 准备就绪，它就会替换掉回退 UI。

Suspense 的重要性：

声明式异步处理： 你不再需要手动管理加载状态、错误状态和数据就绪状态，Suspense 为你抽象了这些。
编排加载顺序： 可以在组件树的任意位置声明加载边界，控制哪些部分需要等待，哪些可以立即显示。
为 Streaming SSR 铺路： Suspense 的这种“等待-显示回退-显示真实内容”的机制，完美契合了服务器端渐进式发送 HTML 的需求。服务器可以先发送包含回退 UI 的 HTML，然后当异步内容就绪时，再发送真实内容的 HTML 片段。

III. Streaming SSR 核心原理：HTTP 流式传输

Streaming SSR 的核心魔法在于它利用了 HTTP 协议的流式传输能力。传统的 HTTP 响应是一次性发送一个完整的响应体，而流式传输则允许服务器在连接保持活跃的情况下，分批次地将数据发送给客户端。

1. HTTP 分块传输编码 (Chunked Transfer Encoding)

这是实现 HTTP 流式传输的关键机制。当服务器无法预知响应体的总长度，或者希望在生成响应体的同时就开始发送数据时，它会使用 Transfer-Encoding: chunked 头部。

工作原理：

服务器将响应体分割成一系列的“块”（chunks）。
每个块前面会有一个十六进制的数字，表示该块的长度。
块数据紧随其后。
最后一个块是一个长度为 0 的块，表示响应体结束。

示例 HTTP 响应 (伪代码):

HTTP/1.1 200 OK
Content-Type: text/html
Transfer-Encoding: chunked

5       <-- 块长度 (5个字节)
Hello   <-- 块数据
D       <-- 块长度 (13个字节)
 World!
<p>     <-- 块数据
C       <-- 块长度 (12个字节)
This is </p>
6       <-- 块长度 (6个字节)
a test. <-- 块数据
0       <-- 最后一个块，表示结束

<-- 响应结束

浏览器接收到这种响应后，会逐个解析这些块。每当接收到一个新的块，它就可以立即处理这些数据，而无需等待整个响应完成。

2. 服务器如何持续写入响应流

在 Node.js 环境中，HTTP 响应对象 (res) 是一个可写流（Writable Stream）。我们可以利用 res.write() 方法向客户端发送数据，而无需立即调用 res.end()。

res.write(chunk): 将数据块写入响应流。服务器会立即发送这些数据到客户端。
res.end(chunk): 发送最后一个数据块并关闭响应流。

Node.js 示例：

const http = require('http');

http.createServer((req, res) => {
  res.writeHead(200, {
    'Content-Type': 'text/html',
    'Transfer-Encoding': 'chunked' // 明确告诉浏览器这是分块传输
  });

  res.write('<h1>');
  res.write('Hello');

  // 模拟一个异步操作，导致延迟
  setTimeout(() => {
    res.write(' World');
    res.write('</h1>');

    // 模拟另一个异步操作
    setTimeout(() => {
      res.write('<p>This is a streamed response.</p>');
      res.end(); // 结束响应
    }, 1000);
  }, 2000);

}).listen(3000, () => {
  console.log('Server running on port 3000');
});

当浏览器访问这个服务器时，它会：

立即收到 <h1>Hello 并显示。
等待 2 秒后，收到 World</h1>，页面更新为 <h1>Hello World</h1>。
再等待 1 秒后，收到 <p>This is a streamed response.</p>，页面再次更新。

这种能力是 Streaming SSR 的基石，它允许 React 在服务器端将渲染结果分阶段地发送给浏览器。

3. 客户端浏览器如何接收和解析流数据

现代浏览器对分块传输编码有原生支持。当浏览器检测到 Transfer-Encoding: chunked 头部时，它不会等待整个响应接收完毕才开始解析 HTML。相反，它会：

渐进式解析： 一旦接收到第一个 HTML 块，浏览器就开始解析并构建 DOM 树。
渐进式渲染： 随着新的 HTML 块不断到来，浏览器会增量地更新页面内容，触发重绘。
脚本执行： 如果在流中遇到 <script> 标签，浏览器会暂停 HTML 解析，下载并执行脚本，然后再继续解析 HTML。这是 Streaming SSR 中实现渐进式 Hydration 的关键。

通过这种方式，用户可以更快地看到页面的部分内容，即使某些部分仍在服务器端渲染或数据仍在获取中。这极大地改善了用户对首次加载速度的感知。

IV. React 18 Streaming SSR 工作机制深度解析

React 18 为 Streaming SSR 提供了新的服务器端渲染 API：renderToPipeableStream。这个 API 专门设计用于利用 HTTP 流的优势，实现渐进式 HTML 渲染和 Hydration。

1. renderToPipeableStream API

与传统的 renderToString（一次性返回完整 HTML 字符串）不同，renderToPipeableStream 返回一个可读流（Readable Stream），我们可以将其直接 pipe 到 Node.js 的 HTTP 响应流中。

import { renderToPipeableStream } from 'react-dom/server';

const { pipe, abort } = renderToPipeableStream(
  <ReactApp />, // 你的根 React 组件
  {
    // 配置选项
    onShellReady() {
      // 当初始的 HTML 外壳（不包含 Suspense 后备内容）准备好时调用
      // 可以在这里发送 HTTP 头部和外壳 HTML
    },
    onShellError(error) {
      // 外壳渲染出错时调用
      // 可以在这里发送错误页面的 HTML
    },
    onAllReady() {
      // 当所有内容（包括所有 Suspense 边界内的内容）都渲染完毕时调用
      // 如果你不需要流式传输，或者只需要等待所有内容就绪，可以在这里发送 HTML
    },
    onError(error) {
      // 在流式传输过程中，任何 Suspense 边界内的内容渲染出错时调用
      console.error(error);
    },
    // 其他选项，如 `bootstrapScripts`、`bootstrapModules` 等
  }
);

关键回调函数：

onShellReady: 这是 Streaming SSR 的核心。当 React 能够渲染出页面的“外壳”（shell）——即不依赖任何异步数据的、最外层的 HTML 结构，包括所有 Suspense 边界的 fallback 内容时，这个回调就会触发。此时，你可以将 pipe 方法返回的流 pipe 到 res 对象中，开始向客户端发送 HTML。
onAllReady: 当整个 React 树（包括所有 Suspense 边界内的异步内容）都渲染完成时触发。如果你不希望流式传输，而是希望等待所有内容就绪再发送，可以在这里 pipe。但对于 Streaming SSR 来说，通常我们更关注 onShellReady。
onError: 在流式传输过程中，任何一个 Suspense 边界内部的异步组件渲染失败时，都会触发这个回调。这允许你在服务器端捕获并记录错误，而不会中断整个流。

2. HTML Shell (外壳) 的发送

onShellReady 触发时，React 已经渲染出了页面的骨架。这个骨架通常包含：

<head> 部分（meta 标签、title、CSS 链接等）。
页面布局的非异步部分。
所有 Suspense 边界的 fallback 内容。

服务器会立即将这些 HTML 发送给浏览器。用户因此能更快地看到一个带有加载指示器（fallback UI）的页面结构，而不是白屏。

示例代码片段 (服务器端):

import express from 'express';
import React from 'react';
import { renderToPipeableStream } from 'react-dom/server';
import App from './src/App'; // 你的 React 根组件

const app = express();
app.use(express.static('public')); // 静态文件服务

app.get('/', (req, res) => {
  let didError = false;

  const { pipe, abort } = renderToPipeableStream(<App />, {
    bootstrapScripts: ['/main.js'], // 客户端 JS 入口
    onShellReady() {
      // 在外壳 HTML 准备好时发送 HTTP 头部和开始流式传输
      res.statusCode = didError ? 500 : 200;
      res.setHeader('Content-type', 'text/html');
      pipe(res); // 将 React 渲染流导向 HTTP 响应流
    },
    onShellError(error) {
      // 处理外壳渲染错误
      console.error('Shell Error:', error);
      res.statusCode = 500;
      res.send('<!doctype html><p>Loading Error</p>'); // 发送一个简单的错误页面
    },
    onError(error) {
      // 处理流中组件渲染错误
      didError = true;
      console.error('Stream Error:', error);
    }
  });

  // 如果客户端在流完成前断开连接，或者需要提前中断流
  // req.on('close', () => abort());
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

3. Suspense Placeholders (回退 UI) 的发送

当 React 遇到一个 Suspense 边界，并且其内部的异步内容尚未就绪时，它不会等待。相反，它会先渲染 Suspense 的 fallback 属性提供的 UI，并将其包含在外壳 HTML 中发送出去。

在浏览器端，用户会先看到这个回退 UI。

HTML 结构示例 (简化):

<!DOCTYPE html>
<html>
  <head>
    <title>Streaming SSR App</title>
  </head>
  <body>
    <div id="root">
      <h1>Welcome!</h1>
      <!-- 这是 Suspense 的 fallback 内容 -->
      <div id="loading-spinner">加载中...</div>
      <!-- React 会在这里放置一些特殊的注释来标记 Suspense 边界 -->
      <!-- $S -->
      <!-- 后续的异步内容会在这里被注入 -->
    </div>
    <script src="/main.js"></script>
  </body>
</html>

4. script 标签的魔法与渐进式 Hydration

这是 Streaming SSR 最巧妙的部分。当服务器端某个 Suspense 边界内的异步数据最终获取完成，或者异步组件代码加载完毕后，React 会做以下事情：

它会渲染出这个异步组件的真实 HTML 内容。
它会将这段真实的 HTML 内容，以及一些特殊的 <script> 标签，作为新的数据块注入到响应流中。

这些特殊的 <script> 标签包含了：

HTML 片段注入指令： React 会生成一个 <script> 标签，其中包含 JavaScript 代码，这段代码会查找之前发送的 Suspense 占位符，然后将新到达的 HTML 片段插入到正确的位置，替换掉占位符。
客户端 Hydration 指令： 更重要的是，这些 <script> 标签还会告诉客户端的 React，现在可以对刚刚插入的 HTML 片段进行“水合”了。这意味着客户端 React 不需要等待整个页面加载完毕，就可以对这些部分进行局部、渐进式的 Hydration。

HTML 流中的内容 (简化示例):

<!-- ... 初始外壳 HTML ... -->
<div id="root">
  <h1>Welcome!</h1>
  <div id="loading-spinner">加载中...</div>
  <!-- React 内部的标记，用于客户端识别替换点 -->
  <!-- $S1 -->
</div>
<script src="/main.js"></script>
<!-- ... 服务器继续处理，某个 Suspense 边界内的异步数据就绪 ... -->
<!-- 新的 HTML 块被推送到流中 -->
<script>
  // 这是一个由 React 自动生成的脚本，它负责：
  // 1. 查找 DOM 中对应的 Suspense 占位符（例如通过 ID 或特殊标记）。
  // 2. 将异步组件的真实 HTML 字符串注入到占位符的位置。
  // 3. 告诉客户端 React，可以对这一部分进行 Hydration 了。
  // 例如：
  // const AsyncContent = '<p>这是异步加载的内容！</p>';
  // document.getElementById('loading-spinner').outerHTML = AsyncContent;
  // __webpack_require__.r(AsyncContentModule); // 模拟模块注册
  // ReactDOM.hydrate(React.createElement(AsyncContentComponent), document.getElementById('newly-inserted-root'));
  // 实际的 React 脚本会更复杂，例如使用 `ReactDOM.hydrateRoot` 的部分水合能力
</script>
<!-- 实际注入的 HTML 会在 script 之后，或者直接通过 script 操纵 DOM 插入 -->
<div hidden id="react-suspense-content-1">
  <p>这是异步加载的内容！</p>
</div>
<script>
  // 更精准的 React 内部机制：
  // 1. 通过 `ReactDOM.renderToPipeableStream` 内部生成的特定标记（如 `<!--$S1-->`）
  //    客户端 React 知道这是一个 Suspense 边界。
  // 2. 当异步内容准备好时，服务器发送一个 `<script>` 标签，其中包含：
  //    - `ReactDOM.render(AsyncComponent, document.getElementById('loading-spinner'));` （伪代码）
  //    - 或者更底层地，将 `AsyncComponent` 的 HTML 注入到 `loading-spinner` 的位置。
  //    - 随后，客户端的 React 会识别到这个新注入的 HTML，并对其进行 Hydration。
  //    - React 内部通过 `__rde` (react-dom-server-runtime) 等内部函数来完成这些。
  // 实际的注入是这样的：
  // <template id="B:0"></template>
  // <script>
  //   $RC("B:0", '<p>这是异步加载的内容！</p>');
  // </script>
  // $RC 是一个全局函数，用于在客户端将 HTML 片段渲染到指定的 Suspense 占位符中。
  // 其中的 HTML 字符串会被解析并替换掉占位符。
</script>

渐进式 Hydration 的优势：

非阻塞： 客户端 React 可以对页面的不同部分进行独立的 Hydration。一个慢速组件的 Hydration 不会阻塞整个页面的交互性。
优先级： React 可以优先 Hydrate 关键的、用户可见的部分，或者用户正在交互的部分。
更快的 TTI： 用户可以更快地与页面的关键部分进行交互，即使其他部分仍在加载或 Hydrating。

bootstrapScripts 和 bootstrapModules：

renderToPipeableStream 的 options 中可以指定 bootstrapScripts 和 bootstrapModules。它们用于指定客户端 React 应用的入口 JavaScript 文件。这些脚本会在外壳 HTML 中被引用，并负责启动客户端 React 应用，使其能够接收和处理流中后续到达的 HTML 片段。

bootstrapScripts: 适用于传统的 <script src="..."> 标签。
bootstrapModules: 适用于 ES Modules <script type="module" src="..."> 标签。

总结 renderToPipeableStream 的流式处理流程：

服务器开始渲染 React 根组件。
遇到 Suspense 边界，且其内部异步内容未就绪时，渲染 fallback。
当非异步部分和所有 fallback 内容就绪时（onShellReady），服务器发送页面的初始 HTML 外壳，包含 fallback UI 和客户端 JS 引用。
浏览器接收并渲染外壳，用户看到骨架和加载状态。
在服务器端，异步数据继续获取或组件代码继续加载。
一旦某个 Suspense 边界内的异步内容就绪，React 会渲染其真实 HTML。
服务器将这段真实 HTML 以及一个特殊的 <script> 标签（包含将其注入 DOM 的指令和 Hydration 指令）作为新的数据块发送给浏览器。
浏览器接收到新的数据块，执行 <script> 标签中的 JS。
JS 将真实 HTML 插入到正确位置，替换掉 fallback。
客户端 React 对新插入的 HTML 片段进行渐进式 Hydration，使其变为可交互。
这个过程一直重复，直到所有 Suspense 边界都被解析并 Hydrated。

V. 代码实践：构建一个 Streaming SSR 应用

让我们通过一个具体的例子来理解 Streaming SSR 的实现。我们将构建一个简单的应用，其中包含一个模拟延迟的数据获取组件。

项目结构:

my-streaming-ssr-app/
├── public/
│   └── main.js             // 客户端打包后的 JS
├── src/
│   ├── App.js              // React 根组件
│   ├── SlowComponent.js    // 模拟慢速数据获取的组件
│   ├── index.js            // 客户端入口
│   └── server.js           // 服务器端入口 (Node.js/Express)
├── package.json
├── webpack.config.js

1. webpack.config.js (客户端打包)

我们需要将客户端 React 代码打包成浏览器可执行的 JS。

const path = require('path');

module.exports = {
  mode: 'development', // 或 'production'
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'public'),
    filename: 'main.js',
    publicPath: '/'
  },
  module: {
    rules: [
      {
        test: /.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-react', '@babel/preset-env']
          }
        }
      }
    ]
  },
  devtool: 'source-map'
};

2. src/index.js (客户端入口)

客户端通过 hydrateRoot 来接管服务器渲染的 HTML。

import React from 'react';
import { hydrateRoot } from 'react-dom/client';
import App from './App';

hydrateRoot(document.getElementById('root'), <App />);

3. src/SlowComponent.js (模拟慢速数据获取的组件)

这个组件将模拟一个耗时的数据获取，并使用 Suspense 友好的方式来处理。

为了简化，我们不使用实际的数据获取库，而是模拟一个“读”操作。

import React from 'react';

// 模拟数据缓存和读取，以支持 Suspense
let cache = new Map();

function fetchData(id) {
  if (!cache.has(id)) {
    let status = 'pending';
    let result;
    let suspender = new Promise(resolve => {
      setTimeout(() => {
        status = 'success';
        result = `Data for item ${id} fetched at ${new Date().toLocaleTimeString()}`;
        resolve();
      }, 3000); // 模拟 3 秒延迟
    });
    cache.set(id, { suspender, result });
  }
  const entry = cache.get(id);
  if (entry.status === 'pending') {
    throw entry.suspender; // 抛出 Promise，让 Suspense 捕获
  }
  return entry.result;
}

function SlowComponent({ id }) {
  const data = fetchData(id); // 当数据未就绪时，这里会抛出 Promise
  return (
    <div style={{ border: '1px solid #ccc', padding: '10px', margin: '10px' }}>
      <h3>Slow Component {id}</h3>
      <p>{data}</p>
    </div>
  );
}

export default SlowComponent;

注意： 生产环境中，你会使用像 react-query、swr 或 React 自身的数据获取方案（如未来的 use hook）来配合 Suspense。上述 fetchData 是一个非常简化的示例，旨在演示 Suspense 捕获 Promise 的机制。在服务器端，fetchData 需要能够同步或通过 async/await 在服务器等待数据，不能直接 throw Promise。对于服务器端，我们通常会直接在组件中 await 真实的异步操作，或者使用支持 Suspense 的数据获取库。为了在 SSR 环境下演示，我会调整 App.js 中的数据获取方式，使其更符合服务器端渲染的实际情况。

更符合 SSR 的 fetchData 模拟：
在服务器端，我们需要在渲染之前或渲染过程中 await 数据。
让我们直接在 App.js 中模拟异步组件，而不是在 SlowComponent 内部抛出。

// src/SlowComponent.js (保持简单，只显示接收到的数据)
import React from 'react';

function SlowComponent({ data }) {
  return (
    <div style={{ border: '1px solid #ccc', padding: '10px', margin: '10px' }}>
      <h3>Slow Component</h3>
      <p>{data}</p>
    </div>
  );
}

export default SlowComponent;

4. src/App.js (React 根组件)

这里我们将使用 Suspense 来包裹 SlowComponent。

import React, { Suspense } from 'react';
import SlowComponent from './SlowComponent';

// 模拟一个异步函数，用于在服务器端获取数据
async function getSlowData(delay) {
  return new Promise(resolve => {
    setTimeout(() => {
      resolve(`This data arrived after ${delay / 1000} seconds! (Server Time: ${new Date().toLocaleTimeString()})`);
    }, delay);
  });
}

// 这是一个服务器和客户端共享的数据容器
// 在服务器端，我们会在渲染前填充它
// 在客户端，它会作为初始状态被 Hydrate
const dataPromiseCache = {};

function fetchDataForComponent(key, delay) {
  if (!dataPromiseCache[key]) {
    dataPromiseCache[key] = getSlowData(delay);
  }
  // 在服务器端，这里会 await Promise
  // 在客户端，如果 Promise 已经解决，则直接返回结果；否则，throw Promise 让 Suspense 捕获
  if (typeof window === 'undefined') { // 服务器端
    return dataPromiseCache[key];
  } else { // 客户端
    // 这是客户端 Suspense 友好的数据读取模式
    // 实际库如 SWR/React Query 会帮你处理
    if (dataPromiseCache[key].status === 'fulfilled') {
      return dataPromiseCache[key].value;
    } else if (dataPromiseCache[key].status === 'rejected') {
      throw dataPromiseCache[key].reason;
    } else {
      throw dataPromiseCache[key]; // throw Promise for Suspense
    }
  }
}

// 辅助函数，用于包装 Promise，使其具有 Suspense 所需的 status/value/reason 属性
function wrapPromise(promise) {
  let status = 'pending';
  let result;
  let suspender = promise.then(
    r => {
      status = 'fulfilled';
      result = r;
    },
    e => {
      status = 'rejected';
      result = e;
    }
  );
  return {
    read() {
      if (status === 'pending') {
        throw suspender;
      } else if (status === 'rejected') {
        throw result;
      } else if (status === 'fulfilled') {
        return result;
      }
    }
  };
}

// 在客户端，我们可能需要一个独立的 Suspendable SlowComponent
// 因为服务器端已经将数据流式传输过来了，客户端只需要 Hydrate
// 但为了演示客户端 Hydration，我们仍然使用 Suspense
function SuspendableSlowComponent({ delay }) {
  const resource = React.useMemo(() => wrapPromise(getSlowData(delay)), [delay]);
  return <SlowComponent data={resource.read()} />;
}

function App() {
  return (
    <html>
      <head>
        <title>Streaming SSR Demo</title>
        <style>{`
          body { font-family: sans-serif; margin: 20px; }
          .container { border: 2px solid #007bff; padding: 20px; border-radius: 8px; }
          .loading { color: gray; }
          .error { color: red; }
        `}</style>
      </head>
      <body>
        <div id="root" className="container">
          <h1>React Streaming SSR Example</h1>
          <p>This is some eagerly rendered content.</p>

          <Suspense fallback={<p className="loading">Loading Slow Component 1...</p>}>
            {/* 在服务器端，这里会 await getSlowData(2000) */}
            <SuspendableSlowComponent delay={2000} />
          </Suspense>

          <Suspense fallback={<p className="loading">Loading Slow Component 2...</p>}>
            {/* 这个组件会更慢 */}
            <SuspendableSlowComponent delay={5000} />
          </Suspense>

          <p>This content is below the Suspense boundaries and will be sent with the initial shell.</p>
        </div>
      </body>
    </html>
  );
}

export default App;

重要说明：
上述 fetchDataForComponent 和 wrapPromise 模式是为了在客户端和服务器端演示 Suspense 的行为。

在服务器端，renderToPipeableStream 会等待 SuspendableSlowComponent 内部的 getSlowData Promise 解决，然后将最终的 HTML 发送到流中。
在客户端，当执行 resource.read() 时，如果 Promise 尚未解决，它会 throw Promise，触发客户端 Suspense 的 fallback。一旦数据到达（通过服务器注入的脚本），Promise 解决，组件重新渲染。

5. src/server.js (服务器端入口)

这是 Streaming SSR 的核心。

import express from 'express';
import React from 'react';
import { renderToPipeableStream } from 'react-dom/server';
import App from './App'; // 导入你的 React 根组件
import path from 'path';
import fs from 'fs';

const app = express();
const PORT = 3000;

// 静态文件服务：将 public 目录下的文件暴露出去
app.use(express.static(path.resolve(__dirname, '../public')));

// 定义一个根路由
app.get('/', async (req, res) => {
  let didError = false;

  // 调用 renderToPipeableStream
  const { pipe, abort } = renderToPipeableStream(<App />, {
    bootstrapScripts: ['/main.js'], // 客户端 JS 入口
    onShellReady() {
      // 当外壳 HTML 准备好时，发送 HTTP 头部并开始流式传输
      // 注意：这里我们直接将整个 HTML 结构（包括 <html>, <head>, <body>, <div id="root">）
      // 都放在了 App 组件中，所以不需要手动写 <!DOCTYPE html> 等。
      res.statusCode = didError ? 500 : 200;
      res.setHeader('Content-type', 'text/html');
      pipe(res); // 将 React 渲染流导向 HTTP 响应流
    },
    onShellError(error) {
      // 外壳渲染出错时调用
      console.error('Shell Error:', error);
      res.statusCode = 500;
      // 在这里发送一个简单的错误页面 HTML
      res.send(`<!DOCTYPE html><html><head><title>Error</title></head><body><h1>Loading Error</h1><pre>${error.message}</pre></body></html>`);
    },
    onError(error) {
      // 在流式传输过程中，任何 Suspense 边界内的内容渲染出错时调用
      didError = true;
      console.error('Stream Error (inside Suspense boundary):', error);
      // 注意：这里我们不能直接发送错误页面，因为流已经开始了。
      // React 会尝试在流中注入一个错误回退。
    }
  });

  // 如果客户端断开连接，可以中止流
  // req.on('close', () => abort());
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

运行步骤：

安装依赖：

npm init -y
npm install react react-dom express @babel/core @babel/preset-env @babel/preset-react babel-loader webpack webpack-cli

打包客户端 JS：
```
npx webpack --config webpack.config.js
```
这会在 public/ 目录下生成 main.js。
启动服务器：
```
node src/server.js
```
访问浏览器： 打开 http://localhost:3000

观察效果：

即时显示： 你会立即看到页面的标题、固定内容和两个“Loading Slow Component…”的占位符。
渐进加载： 大约 2 秒后，第一个慢组件的内容会突然出现，替换掉它的加载占位符。
继续加载： 再过 3 秒（总共 5 秒），第二个慢组件的内容也会出现。
无白屏： 整个过程中，页面始终有内容显示，没有长时间的白屏等待。
检查网络： 打开浏览器的开发者工具，查看网络请求。你会发现 HTTP 响应是一个持续的流，数据块会分批次到达。

VI. 性能优势与用户体验提升

Streaming SSR 带来的性能提升是多方面的，直接转化为更优秀的用户体验。

1. 更快的 TTFB (Time To First Byte)

告别全量等待： 服务器不再需要等待所有数据获取和所有组件渲染完成才能发送第一个字节。它可以在外壳 HTML 准备好时就立即发送响应。
用户感知速度提升： 即使服务器后台还在处理复杂逻辑或慢速数据请求，用户也能更快地看到页面的骨架和加载指示器，避免了长时间的白屏。

2. 更快的 FCP (First Contentful Paint)

即时可见： 由于 TTFB 缩短，浏览器能够更快地接收到并渲染出页面的第一个有意义的内容（通常是页面的布局和加载占位符）。
减少焦虑： 用户不会感到应用卡死或无响应，因为他们能持续看到内容加载的进展。

3. 更快的 TTI (Time To Interactive) for critical parts (渐进式 Hydration)

局部可交互： 客户端 React 可以对随着流到达的 HTML 片段进行独立的 Hydration。这意味着页面中不依赖异步内容的、或异步内容已就绪的部分，可以提前变得可交互。
优先关键区域： 如果页面的某个区域对用户交互至关重要，而其数据加载较快，它就可以比页面其他部分更早地变为可交互。
提升用户满意度： 用户可以立即点击和操作页面的关键元素，而无需等待整个页面完全 Hydrated。

4. 更好的用户感知性能

持续反馈： 页面内容是渐进式加载的，用户能看到内容一点点地填充进来，这比一次性出现所有内容更能给人“快速”的心理感受。
减少不确定性： 加载指示器明确告诉用户内容正在路上，而不是一片空白，降低了用户等待时的挫败感。

5. 减少服务器负载（特定场景）

分批处理： 服务器可以分批处理和发送数据，而不是一次性进行大量计算并缓存整个 HTML 字符串。
更高效的资源利用： 对于某些 I/O 密集型操作，流式传输可以允许服务器在等待外部服务响应的同时，将已就绪的部分发送出去，从而更有效地利用 CPU 和网络资源。

VII. 挑战与注意事项

尽管 Streaming SSR 带来了显著的优势，但在实际应用中也需要考虑一些挑战和注意事项。

1. 缓存策略

复杂性： 传统的 SSR 响应是一个静态的 HTML 字符串，可以方便地被 CDN 或代理服务器缓存。但 Streaming SSR 的响应是动态的、分块的流，缓存整个流的复杂性更高。
部分缓存： 可以考虑缓存外壳 HTML，但内部的异步内容通常是动态的，难以通用缓存。
CDN 支持： 某些 CDN 可能对 Transfer-Encoding: chunked 的缓存支持不完善，需要特定的配置。

2. 错误处理

onError 的重要性： renderToPipeableStream 的 onError 回调至关重要。它允许你在流式传输过程中捕获组件渲染错误，而不是让整个流中断。
优雅降级： 当某个 Suspense 边界内的组件渲染失败时，React 会尝试发送一个错误回退（通常会是客户端 Suspense 的 fallback 或自定义错误边界）。确保你的错误边界能够优雅地处理这些情况。
网络错误： 如果在流式传输过程中发生网络中断，客户端将无法接收到后续的 HTML 块。这需要客户端 JavaScript 来处理，例如显示一个连接丢失的提示。

3. 复杂性与调试

理解难度： Streaming SSR 的工作机制比传统 SSR 更复杂，涉及服务器流、客户端渐进式解析、JavaScript 注入和渐进式 Hydration。
调试挑战： 调试服务器端和客户端协同工作时的流问题可能比较棘手。你需要理解 HTTP 协议、Node.js 流以及 React 内部的 Hydration 机制。
工具支持： 依赖于框架（如 Next.js、Remix）提供的抽象层可以大大简化开发，但理解底层原理仍然重要。

4. 兼容性

浏览器支持： 现代浏览器对 HTTP/1.1 和 HTTP/2 的分块传输编码都有良好的支持。
老旧浏览器： 极少数老旧浏览器可能对流式传输或某些客户端 JavaScript 注入机制支持不佳，但这不是普遍问题。

5. SEO 影响

通常不是问题： 搜索引擎爬虫（如 Googlebot）通常能够处理 JavaScript 渲染的内容。对于 Streaming SSR，最终所有的内容都会到达浏览器并被渲染，因此 SEO 通常不会受到负面影响。
爬取时间： 如果关键内容依赖于长时间的异步加载，可能会略微增加爬虫抓取完整内容所需的时间，但通常在可接受范围内。

6. 数据同构与状态管理

服务器与客户端数据同步： 在服务器端获取的数据如何传递给客户端进行 Hydration，这是任何 SSR 应用都需要解决的问题。
共享状态： 对于全局状态管理（如 Redux, Zustand），需要确保服务器端渲染时的状态能够被正确地序列化并在客户端进行反序列化，以保持一致性。
Suspense 友好的数据获取： 使用专门为 Suspense 设计的数据获取库（如 React Query 配合 suspense: true）可以简化服务器和客户端的数据同步。

VIII. Streaming SSR 与 Server Components (RSC) 的关系

在 React 18 及未来版本中，Streaming SSR 经常与 React Server Components (RSC) 同时被提及。虽然它们都与服务器端渲染和性能优化相关，但它们解决的问题和工作方式有所不同，并且可以协同工作。

1. Streaming SSR：关注“如何传输”

核心目标： 优化服务器端渲染 HTML 到客户端的 传输过程。
解决问题： 减少 TTFB，实现渐进式内容显示和渐进式 Hydration。
传输内容： 完整的 HTML 结构（包括 <head>, <body>），以及客户端 JavaScript。当异步内容就绪时，它会发送带有 JavaScript 注入指令的 HTML 片段。
执行位置： 组件的渲染逻辑在服务器端执行，Hydration 发生在客户端。

2. Server Components (RSC)：关注“在何处渲染”和“减少客户端 JS”

核心目标： 将更多的渲染逻辑和数据获取移到服务器端，并将客户端 JavaScript 包的大小降到最低。
解决问题： 减少客户端 JavaScript 包大小，降低客户端 Hydration 负担，提高客户端性能。
传输内容： RSC 不发送 HTML。它发送一种特殊的、轻量级的 JSON 序列化格式（React Server Component Payload, RSCP），其中包含组件的属性、React 元素树的描述以及对客户端组件的引用。
执行位置： Server Components 完全在服务器端渲染，不发送到客户端进行 Hydration。Client Components 可以在服务器端预渲染成 HTML，然后在客户端进行 Hydration。
标记： 通过 'use client' 指令来区分 Server Component (默认) 和 Client Component。

3. 两者如何协同工作

Streaming SSR 和 RSC 并非互斥，而是可以相互补充，共同构建一个高性能的 React 应用。

RSC 提供内容，Streaming SSR 传输内容： 当你使用 RSC 时，Server Components 在服务器端渲染出它们的输出（RSCP）。这个 RSCP 可以被 Streaming SSR 机制进一步优化传输。
渐进式 RSC 内容传输： RSCP 本身也可以是流式的。服务器可以先发送页面结构所需的 RSCP 部分，然后当某个 Server Component 中的异步数据就绪时，再发送该组件对应的 RSCP 片段。
RSC 渲染 HTML，Streaming SSR 发送 HTML： 对于那些包含 Client Components 的 RSC 树，最终需要在服务器端渲染成 HTML（例如，通过 renderToPipeableStream）。Streaming SSR 就能以渐进的方式将这些 HTML 发送给浏览器。

简而言之：

Streaming SSR 是关于 如何将服务器端渲染的结果（HTML + JS）逐步发送给客户端。
RSC 是关于 哪些组件可以在服务器端完全渲染并避免客户端 JS。

你可以拥有一个由 Server Components 组成的 React 树，其中一些 Server Components 引用了 Client Components。当这个混合树在服务器端被 renderToPipeableStream 渲染时，Server Components 的部分会被处理，而 Client Components 及其 Hydration 相关的 HTML 和 JS 则会通过 Streaming SSR 的机制，以渐进的方式发送到浏览器。

IX. 展望未来

Streaming SSR 是 React 迈向更强大、更高效架构的重要一步。未来，我们可以期待：

框架深度集成： Next.js、Remix 等主流 React 框架将进一步抽象和优化 Streaming SSR 的实现细节，提供更简洁的 API 和更强大的开发体验。用户将能够更轻松地构建流式 SSR 应用，无需深入了解底层机制。
更智能的 Hydration 策略： React 可能会引入更精细的 Hydration 控制，例如，基于用户可见性或交互优先级来自动决定哪些组件需要优先 Hydrate。
无缝的数据层： 随着 React Server Components 的成熟，与 Streaming SSR 的结合将变得更加无缝，开发者可以更自然地编写跨服务器和客户端的代码，并享受两者带来的性能优势。
更广泛的生态系统支持： 更多第三方库和工具将适配 Streaming SSR 和并发模式，简化开发者的工作流程。

结论

Streaming SSR 是 React 18 为提升用户体验和应用性能而带来的一项强大技术。通过利用 HTTP 流式传输和 React Suspense 的能力，它彻底改变了服务器端渲染的模式。我们不再需要等待整个页面渲染完成才能发送响应，而是可以渐进地将 HTML 和交互性推送到浏览器。这带来了更快的首次内容绘制、更短的可交互时间，以及更流畅的用户感知。理解并掌握 Streaming SSR 的原理和实践，无疑是现代 React 开发者工具箱中的一项关键技能。它不仅优化了现有应用的性能瓶颈，也为构建未来高性能、高响应性的 Web 应用奠定了坚实的基础。