解决React SSR水合警告：EJS模板中意外空白引发的DOM不匹配

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

解决React SSR水合警告：EJS模板中意外空白引发的DOM不匹配

2025-10-10

浏览次数：次

返回列表

解决React SSR水合警告：EJS模板中意外空白引发的DOM不匹配

本文旨在解决React服务端渲染（SSR）中常见的“Expected server HTML to contain a matching in ”水合警告。该问题通常源于Express和EJS等自定义SSR设置中，React组件被注入HTML模板时，因EJS模板中的换行或空格导致服务器生成的HTML与客户端期望的DOM结构不完全匹配。核心解决方案是确保React组件在EJS模板中被直接、无空白地注入到其根DOM元素内部。

理解React SSR水合（Hydration）机制

在react服务端渲染（ssr）应用中，服务器会预先生成html字符串并发送给客户端。客户端的react应用接收到这份html后，并不会从头开始构建dom，而是尝试“水合”已有的dom结构。水合过程是react将客户端j*ascript逻辑（如事件监听器、状态管理）附加到服务器预渲染的html上的过程。为了实现高效的水合，react要求服务器生成的html结构与客户端首次渲染时预期的dom结构完全一致。任何细微的差异，包括额外的文本节点（如换行符、空格），都可能导致水合失败，从而触发类似“expected server html to contain a matching

in ”的警告，并可能回退到客户端渲染（csr），失去ssr的优势。

常见问题：EJS模板中的隐形空白

当使用Express和EJS等模板引擎进行React SSR时，一个常见且容易被忽视的问题是EJS模板中注入React组件的方式。考虑以下EJS模板片段：

<div class="root">
  <!-- Rendered React component will be injected here -->
  <%- reactComponent %>
</div>

在这个例子中，reactComponent变量包含了由renderToString生成的React组件的HTML字符串。表面上看，它被正确地放置在

内部。然而，EJS模板中的换行符和注释（即使是HTML注释）在渲染时会被转换为实际的空白字符。这意味着，服务器最终发送给客户端的HTML可能看起来像这样：

<div class="root">

   <!-- Rendered React component will be injected here -->

   <header>...</header>
   <section>...</section>

</div>

React的水合算法在检查

的子节点时，会首先遇到一个文本节点（由换行和空格组成），而不是它所期望的

元素。这种不匹配就会立即触发水合警告，并导致React放弃水合，转而进行客户端渲染。

解决方案：确保组件的直接注入

解决这个问题的关键在于消除EJS模板中reactComponent注入点周围的所有非预期空白。这意味着将reactComponent直接放置在根DOM元素的开始标签和结束标签之间，且不引入任何换行符或空格。

修改后的EJS模板示例：

<div class="root"><%- reactComponent %></div>

通过这种方式，服务器生成的HTML将是：

<div class="root"><header>...</header><section>...</section></div>

现在，

的第一个子节点就是React组件的根元素（例如

），与客户端React期望的结构完全匹配，从而实现成功的水合。

示例代码与实践

以下是一个完整的Express、EJS和React SSR设置示例，展示了如何正确处理组件注入：

1. React组件 (SchoolPage.jsx)

青泥AI

青泥学术AI写作辅助平台

360 查看详情青泥AI

import React from 'react';
import MiniSearchBar from './MiniSearchBar'; // 假设有这个组件
import ContentContainer from './ContentContainer'; // 假设有这个组件

export default function SchoolPage() {
  return (
    <>
      <header>
        <picture title="Campus Eats">
          <source
            media="(min-width: 400px)"
            srcSet="/images/campus-eats-logo-black.svg"
          />
          @@##@@
        </picture>
        <n* className="places-at">
          <h2>Places</h2>
          <h2>at</h2>
          <div className="search-container">
            <MiniSearchBar></MiniSearchBar>
          </div>
        </n*>
        <n* className="login-signup">
          <button className="login">Log in</button>
          <button className="signup">Sign up</button>
        </n*>
      </header>
      <section>
        <ContentContainer></ContentContainer>
      </section>
    </>
  );
}

2. Express服务器 (server.js)

import express from 'express';
import path from 'path';
import ejs from 'ejs';
import React from 'react';
import { renderToString } from 'react-dom/server';
import SchoolPage from './dist/SchoolPage.js'; // 假设打包后的组件

const app = express();
const PORT = process.env.PORT || 3000;

app.use(express.static(path.join(__dirname, 'public'))); // 静态文件服务

app.get("/campus/:id/locations", async (req, res) => {
  const reactComponentHtml = renderToString(<SchoolPage />);
  const filePath = path.join(__dirname, "dist", "school-page.ejs"); // EJS模板路径

  ejs.renderFile(filePath, { reactComponent: reactComponentHtml }, (err, html) => {
    if (err) {
      console.error("Error rendering template:", err);
      return res.status(500).send("Internal Server Error");
    }
    res.send(html);
  });
});

app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

3. EJS模板 (school-page.ejs)

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- 省略其他meta、link和script标签 -->
    <title>Campus Eats</title>
  </head>
  <body>
    <!-- 关键改动：确保 <%- reactComponent %> 无空白地直接嵌入 -->
    <div id="root"><%- reactComponent %></div> 
    <script src="/school-page.js" defer></script> <!-- 客户端水合脚本 -->
  </body>
</html>

注意事项：

id="root" vs class="root": 尽管将class="root"改为id="root"对解决此特定的水合警告并非决定性因素，但将React应用的根元素使用id="root"是普遍的最佳实践，因为它提供了唯一的标识符，方便客户端J*aScript精确地挂载React应用。

客户端水合： 确保客户端的J*aScript文件（例如school-page.js）在加载后会使用ReactDOM.hydrateRoot（或旧版ReactDOM.hydrate）来挂载React应用到id="root"元素上，例如：

import React from 'react';
import { hydrateRoot } from 'react-dom/client';
import SchoolPage from './SchoolPage'; // 客户端打包后的组件

const container = document.getElementById('root');
hydrateRoot(container, <SchoolPage />);

其他水合不匹配： 除了EJS模板中的空白，其他因素也可能导致水合不匹配，例如：
- 客户端在水合前对DOM进行了修改。
- 服务器和客户端在渲染逻辑上存在差异（例如，基于浏览器API的代码在服务器上无法执行，导致DOM结构不同）。
- 使用dangerouslySetInnerHTML时内容不匹配。
- React组件内部条件渲染逻辑在服务器和客户端执行结果不同。

总结

React SSR中的水合警告“Expected server HTML to contain a matching in ”是一个常见的陷阱，尤其是在自定义SSR环境（如Express + EJS）中。其核心原因往往是EJS模板中注入React组件时引入的额外空白字符，导致服务器生成的HTML与客户端React期望的DOM结构不一致。通过确保reactComponent在EJS模板中被直接、无空白地注入到其根DOM元素内部，可以有效解决此问题，保证React应用的顺利水合，从而充分发挥SSR的性能优势。在调试此类问题时，仔细检查服务器发送的最终HTML结构是至关重要的一步。