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

示例代码与实践

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

1. React组件 (SchoolPage.jsx)

麦艺画板(Max.art)

AI工业设计平台，专注于汽车设计，线稿、渲染、3D建模全流程覆盖

下载

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

export default function SchoolPage() {
  return (
    <>
      

        
          
          @@##@@
        
        
        
      
      

        
      
    
  );
}

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();
  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)

  
    
    
    
    
    
  
  
    
    
<%- reactComponent %>
 
     
  

注意事项：

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

• 客户端水合： 确保客户端的JavaScript文件（例如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, );

• 其他水合不匹配： 除了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结构是至关重要的一步。