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

这种警告通常不是因为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();
  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 (
    <>
      

        
          
          @@##@@
        
        
        
      
      

        
      
    
  );
}

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

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

  
    
    
  
  
    

      
      <%- reactComponent %>
    
    
  

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

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

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

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

  
  
...
  
...

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

...
...

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

Sora

Sora是OpenAI发布的一种文生视频AI大模型，可以根据文本指令创建现实和富有想象力的场景。

下载

解决方案

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

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

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

  
    
    
  
  
    
<%- reactComponent %>
    
  

通过将直接紧跟在

之后，并在其关闭标签

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

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

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

  
    
    
  
  
    
<%- reactComponent %>
    
  

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

// 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'), );

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

注意事项与总结

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

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