renderToString

const html = renderToString(reactNode, options?)

• 参考
  • renderToString(reactNode, options?)
• 用法
  • 将 React 树作为 HTML 渲染为字符串
• 备选方案
  • 从 renderToString 迁移到服务器上的流式渲染
  • 从 renderToString 迁移到服务器上的静态预渲染
  • 从客户端代码中移除 renderToString
• 故障排除
  • 当一个组件挂起时，HTML 总是包含一个回退

参考

🌐 Reference

renderToString(reactNode, options?)

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

🌐 On the server, call renderToString to render your app to HTML.

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

const html = renderToString(<App />);

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

🌐 On the client, call hydrateRoot to make the server-generated HTML interactive.

查看更多示例。

参数

🌐 Parameters

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

返回

🌐 Returns

一个 HTML 字符串。

🌐 An HTML string.

注意事项

🌐 Caveats

• renderToString 对 Suspense 的支持有限。如果一个组件挂起，renderToString 会立即将其回退内容作为 HTML 发送。
• renderToString 可以在浏览器中使用，但在客户端代码中使用它 不推荐。

用法

🌐 Usage

将 React 树作为 HTML 渲染为字符串

🌐 Rendering a React tree as HTML to a string

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

🌐 Call renderToString to render your app to an HTML string which you can send with your server response:

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

// The route handler syntax depends on your backend framework
app.use('/', (request, response) => {
  const html = renderToString(<App />);
  response.send(html);
});

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

🌐 This will produce the initial non-interactive HTML output of your React components. On the client, you will need to call hydrateRoot to hydrate that server-generated HTML and make it interactive.

备选方案

🌐 Alternatives

从 renderToString 迁移到服务器上的流式渲染

🌐 Migrating from renderToString to a streaming render on the server

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

如果可能，我们建议使用这些功能齐全的替代方案：

🌐 When possible, we recommend using these fully-featured alternatives:

• 如果你使用 Node.js，请使用 renderToPipeableStream.
• 如果你使用 Deno 或带有 Web Streams 的现代边缘运行时，请使用 renderToReadableStream.

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

🌐 You can continue using renderToString if your server environment does not support streams.

从 renderToString 迁移到服务器上的静态预渲染

🌐 Migrating from renderToString to a static prerender on the server

renderToString 会立即返回一个字符串，因此它不支持等待数据加载以生成静态 HTML。

我们建议使用这些功能齐全的替代方案：

🌐 We recommend using these fully-featured alternatives:

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

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

🌐 You can continue using renderToString if your static site generation environment does not support streams.

从客户端代码中移除 renderToString

🌐 Removing renderToString from the client code

有时，renderToString 会在客户端用来将某些组件转换为 HTML。

🌐 Sometimes, renderToString is used on the client to convert some component to HTML.

// 🚩 Unnecessary: using renderToString on the client
import { renderToString } from 'react-dom/server';

const html = renderToString(<MyIcon />);
console.log(html); // For example, "<svg>...</svg>"

在客户端导入 react-dom/server 会不必要地增加你的打包体积，应尽量避免。如果你需要在浏览器中将某些组件渲染为 HTML，请使用 createRoot 并从 DOM 中读取 HTML：

🌐 Importing react-dom/server on the client unnecessarily increases your bundle size and should be avoided. If you need to render some component to HTML in the browser, use createRoot and read HTML from the DOM:

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); // For example, "<svg>...</svg>"

[flushSync](/reference/react-dom/flushSync) 调用是必要的，以便在读取其 innerHTML 属性之前更新 DOM。

🌐 The flushSync call is necessary so that the DOM is updated before reading its innerHTML property.

故障排除

🌐 Troubleshooting

当一个组件挂起时，HTML 总是包含一个回退

🌐 When a component suspends, the HTML always contains a fallback

renderToString 不完全支持 Suspense。

如果某个组件处于挂起状态（例如，因为它是用 lazy 定义的或正在获取数据），renderToString 不会等待其内容被解析。相反，renderToString 会找到其上方最近的 <Suspense> 边界，并在 HTML 中渲染其 fallback 属性。在客户端代码加载之前，内容不会出现。

🌐 If some component suspends (for example, because it’s defined with lazy or fetches data), renderToString will not wait for its content to resolve. Instead, renderToString will find the closest <Suspense> boundary above it and render its fallback prop in the HTML. The content will not appear until the client code loads.

为了解决这个问题，请使用其中一个推荐的流媒体解决方案。对于服务器端渲染，它们可以在服务器上逐块地流式传输内容，这样用户在客户端代码加载之前就能看到页面逐步填充的内容。对于静态网站生成，它们可以在生成静态 HTML 之前等待所有内容解析完成。

🌐 To solve this, use one of the recommended streaming solutions. For server side rendering, they can stream content in chunks as it resolves on the server so that the user sees the page being progressively filled in before the client code loads. For static site generation, they can wait for all the content to resolve before generating the static HTML.