解决React SSR中Hydration警告：EJS模板注入的细微之处

新闻中心 NEWS CENTER

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

解决React SSR中Hydration警告：EJS模板注入的细微之处

2025-10-10

浏览次数：次

返回列表

解决React SSR中Hydration警告：EJS模板注入的细微之处

本文探讨了React服务器端渲染(SSR)中常见的“Expected server HTML to contain a matching...”hydration警告。该警告通常源于EJS模板中React组件注入时，父容器与组件之间存在多余的空白字符或换行符，导致客户端与服务器端生成的HTML结构不匹配。通过将React组件内联注入到父div中，可以有效解决此问题，确保React能够成功进行hydration，避免回退到客户端渲染。

理解React Hydration警告

在react服务器端渲染（ssr）应用中，当服务器生成html并发送到客户端后，客户端的react会尝试“接管”这份html，将其转化为可交互的组件树，这个过程称为hydration（水合）。如果客户端react在hydration过程中发现服务器端渲染的html结构与它期望的结构不匹配，就会抛出类似“expected server html to contain a matching

in ”的警告。这种不匹配会导致react放弃hydration，转而进行客户端渲染（csr），从而失去ssr带来的性能和seo优势。

这种警告通常不是因为HTML本身语法错误，而是因为客户端和服务器端渲染的HTML在细节上存在差异，例如多余的空白字符、注释或属性顺序等。React对这种匹配要求非常严格。

常见的SSR设置与问题场景

在不使用Next.js等框架，而是采用Express、EJS和React构建SSR应用时，开发者通常会遇到上述问题。以下是一个典型的设置：

1. 服务器端渲染逻辑 (server.jsx)

Express服务器接收请求后，使用renderToString将React组件渲染成HTML字符串，然后将该字符串注入到EJS模板中。

// server.jsx (简化示例)
const express = require('express');
const path = require('path');
const React = require('react');
const ReactDOMServer = require('react-dom/server');
const ejs = require('ejs');
const SchoolPage = require('./dist/SchoolPage').default; // 确保路径正确

const app = express();
app.use(express.static(path.join(__dirname, 'dist'))); // 假设静态文件在dist

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

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

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

2. React根组件 (SchoolPage.jsx)

一个包含HTML语义元素的React组件。

// SchoolPage.jsx
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>
    </>
  );
}

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

这是将React组件HTML注入到完整HTML骨架的地方。

<!-- school-page.ejs (存在问题的写法) -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- ... 省略head内容 ... -->
    <title>Document</title>
  </head>
  <body>
    <div class="root">
      <!-- Rendered React component will be injected here -->
      <%- reactComponent %>
    </div>
    <script src="/school-page.js" defer></script>
  </body>
</html>

在上述EJS模板中，开发者可能会习惯性地将注释和放在新行，这正是导致Hydration警告的常见原因。

问题根源：EJS模板中的隐形陷阱

Hydration警告的根本原因在于EJS模板中注入React组件时，父容器div.root与实际注入的reactComponent之间存在了多余的空白字符或换行符。当服务器端渲染时，renderToString会生成不包含这些额外空白的HTML字符串。然而，当EJS模板将这个字符串插入到

标签内部时，由于模板文件中的换行和缩进，最终生成的HTML会变成类似：

<div class="root">
  <!-- Rendered React component will be injected here -->
  <header>...</header>
  <section>...</section>
</div>

而客户端的React在Hydration时，期望的是一个紧凑的结构，例如：

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

这种服务器端和客户端期望的HTML结构差异（即使只是空白字符的差异），都会被React的Hydration机制检测为不匹配，从而触发警告并回退到客户端渲染。

青泥AI

青泥学术AI写作辅助平台

360 查看详情青泥AI

解决方案

解决此问题的关键在于确保EJS模板中React组件的注入是完全内联的，不引入任何额外的空白字符或换行符。

1. 关键修复：内联注入React组件

将EJS模板中的注入点修改为以下形式：

<!-- school-page.ejs (修复后的写法) -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- ... 省略head内容 ... -->
    <title>Document</title>
  </head>
  <body>
    <div class="root"><%- reactComponent %></div>
    <script src="/school-page.js" defer></script>
  </body>
</html>

通过将直接紧跟在

之后，并在其关闭标签之前，可以消除中间的所有空白字符和换行符。这样，服务器端生成的HTML与客户端React期望的结构就能精确匹配，从而成功进行Hydration。

2. 最佳实践：使用ID选择器

虽然不是导致Hydration警告的直接原因，但将根容器的class="root"改为id="root"是React官方推荐的做法。客户端React通常通过ReactDOM.hydrateRoot(document.getElementById('root'), )或ReactDOM.render(, document.getElementById('root'))来挂载或水合应用，使用id选择器能够更清晰、更高效地定位根元素。

<!-- school-page.ejs (更佳实践) -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <!-- ... 省略head内容 ... -->
    <title>Document</title>
  </head>
  <body>
    <div id="root"><%- reactComponent %></div>
    <script src="/school-page.js" defer></script>
  </body>
</html>

同时，客户端的入口文件也需要相应调整：

// client-side.js (或 school-page.js)
import React from 'react';
import { hydrateRoot } from 'react-dom/client'; // React 18+
import SchoolPage from './SchoolPage';

// React 18+
hydrateRoot(document.getElementById('root'), <SchoolPage />);

// 或者 React 17及以下
// import ReactDOM from 'react-dom';
// ReactDOM.hydrate(<SchoolPage />, document.getElementById('root'));

注意事项与总结

Hydration的严格性：React的Hydration机制对HTML结构要求非常严格。即使是微小的差异（如空白字符、注释、属性顺序），都可能导致不匹配警告。
调试策略：当遇到此类警告时，首先检查服务器端生成的最终HTML（通过浏览器开发者工具查看或直接打印EJS渲染后的HTML），然后与客户端React期望的HTML进行比对，重点关注根元素内部的结构。
避免不必要的客户端DOM操作：在Hydration完成之前，避免在客户端脚本中对服务器渲染的DOM进行任何修改，这也会导致不匹配。

通过上述方法，特别是确保EJS模板中React组件的内联注入，可以有效解决React SSR中的Hydration警告，确保应用能够充分利用服务器端渲染的优势，提供更好的用户体验和SEO表现。