参考 {/reference/}

renderToString(reactNode, options?) {/rendertostring/}

在服务器上，调用 renderToString 将你的应用渲染为 HTML。

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

const html = renderToString(<App />);

在客户端，调用 hydrateRoot 来激活服务器生成的 HTML，使其具有交互性。

请参考下方更多示例。

参数 {/parameters/}

• reactNode：你想要渲染为 HTML 的 React 节点。例如，像 <App /> 这样的 JSX 元素。
• 可选的 options：一个用于服务器渲染的对象。
  • 可选的 identifierPrefix：一个字符串前缀，React 使用 useId 生成的 ID 会使用此前缀，以避免在同一页面上使用多个根时发生冲突。必须与传给 hydrateRoot 的前缀相同。

返回值 {/returns/}

一个 HTML 字符串。

注意事项 {/caveats/}

• renderToString 对 Suspense 的支持有限。如果某个组件挂起（suspend），renderToString 会立即将其 fallback 作为 HTML 输出。

• renderToString 可以在浏览器中运行，但不推荐在客户端代码中使用。

用法 {/usage/}

将 React 树渲染为 HTML 字符串 {/rendering-a-react-tree-as-html-to-a-string/}

调用 renderToString 将你的应用渲染为 HTML 字符串，并将其与服务器响应一起发送：

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

// 路由处理程序的语法取决于你使用的后端框架
app.use('/', (request, response) => {
  const html = renderToString(<App />);
  response.send(html);
});

这将生成你的 React 组件的初始非交互式 HTML 输出。在客户端，你需要调用 hydrateRoot 来激活服务器生成的 HTML，使其具有交互功能。

替代方案 {/alternatives/}

从 renderToString 迁移到服务器上的流式渲染方法 {/migrating-from-rendertostring-to-a-streaming-method-on-the-server/}

renderToString 会立即返回一个字符串，因此不支持在加载内容时进行流式传输。

如果可能，我们建议使用以下功能更完整的替代方案：

• 如果你使用 Node.js，请使用 renderToPipeableStream。
• 如果你使用 Deno 或支持 Web Streams 的现代运行时，请使用 renderToReadableStream。

如果你的服务器环境不支持流式传输，你仍然可以继续使用 renderToString。

从 renderToString 迁移到服务器上的静态预渲染 {/migrating-from-rendertostring-to-a-static-prerender-on-the-server/}

renderToString 会立即返回一个字符串，并且不支持等待数据加载后再生成静态 HTML。

我们建议使用以下功能更完整的替代方案：

• 如果你使用 Node.js，请使用 prerenderToNodeStream。
• 如果你使用 Deno 或支持 Web Streams 的现代边缘运行时，请使用 prerender。

如果你的静态网站生成环境不支持流式传输，你仍然可以继续使用 renderToString。

从客户端代码中移除 renderToString {/removing-rendertostring-from-the-client-code/}

有时，renderToString 会被用于在客户端将某个组件转换为 HTML：

// 🚩 不必要：在客户端使用 renderToString
import { renderToString } from 'react-dom/server';

const html = renderToString(<MyIcon />);
console.log(html); // 例如，"<svg>...</svg>"

在客户端导入 react-dom/server 会不必要地增加 bundle 体积，因此应避免这样做。如果你需要在浏览器中将某个组件渲染为 HTML，请使用 createRoot 并从 DOM 中读取 HTML：

import { createRoot } from 'react-dom/client';
import { flushSync } from 'react-dom';

const div = document.createElement('div');
const root = createRoot(div);
flushSync(() => {
  root.render(<MyIcon />);
});
console.log(div.innerHTML); // 例如，"<svg>...</svg>"

需要调用 flushSync 以确保在读取 innerHTML 属性之前 DOM 已更新。

故障排除 {/troubleshooting/}

当组件挂起时，HTML 中始终包含 fallback {/when-a-component-suspends-the-html-always-contains-a-fallback/}

renderToString 不完全支持 Suspense。

如果某个组件挂起（例如，因为它使用了 lazy 或正在获取数据），renderToString 不会等待其内容解析完成。相反，renderToString 会找到最近的 <Suspense> 边界，并在 HTML 中渲染其 fallback 属性。内容在客户端代码加载完成之前不会显示。

要解决此问题，请使用推荐的流式渲染方案之一。对于服务器端渲染，它们可以在服务器上以块的形式流式传输内容，以便用户在客户端代码加载完成之前逐步看到页面内容。对于静态站点，它们会等待所有内容解析完成后再生成静态 HTML。