Remix使用React.lazy出现Suspense Hydration错误的解决咨询

核心原因 #

React原生的React.lazy仅支持客户端懒加载，和Remix的服务端渲染（SSR）流程不兼容，会导致服务端渲染的内容与客户端水合时的内容不匹配，触发水合前更新的错误。

具体解决方法 #

1. 使用Remix官方的lazy函数（推荐） #

Remix从@remix-run/react提供了适配SSR的lazy函数，能正确同步服务端渲染和客户端水合的状态，彻底避免这类错误。

代码示例：

// root.tsx
import { lazy, Suspense } from "@remix-run/react";

// 用Remix的lazy替代React.lazy
const LandingPage = lazy(() => import("./routes/LandingPage"));
const LatestEventsPage = lazy(() => import("./routes/LatestEventsPage"));

export default function Root() {
  return (
    <html>
      <body>
        <Suspense fallback={<div>加载中...</div>}>
          <LandingPage />
          <LatestEventsPage />
        </Suspense>
      </body>
    </html>
  );
}

2. 拆分路由利用自动代码分割 #

Remix本身会对每个路由自动做代码分割，把LandingPage和LatestEventsPage拆成独立子路由，既避免冗余代码，又不需要手动处理懒加载的水合问题。

代码示例：

// root.tsx - 根路由只负责渲染子路由出口
import { Outlet } from "@remix-run/react";

export default function Root() {
  return (
    <html>
      <body>
        <Outlet />
      </body>
    </html>
  );
}

// routes/_index.tsx - 对应原LandingPage组件
export default function LandingPage() {
  return <div>首页内容</div>;
}

// routes/latest-events.tsx - 对应原LatestEventsPage组件
export default function LatestEventsPage() {
  return <div>最新活动</div>;
}

3. 客户端延迟加载（备选方案） #

如果坚持用React.lazy，可以通过useEffect在客户端挂载后再加载组件，避免服务端与客户端的渲染不匹配：

代码示例：

// root.tsx
import { useState, useEffect, Suspense } from "react";

// 先声明组件类型
let LandingPage: React.ComponentType;
let LatestEventsPage: React.ComponentType;

export default function Root() {
  const [componentsLoaded, setComponentsLoaded] = useState(false);

  useEffect(() => {
    // 客户端挂载后才加载组件
    async function loadComponents() {
      const [landingModule, eventsModule] = await Promise.all([
        import("./routes/LandingPage"),
        import("./routes/LatestEventsPage"),
      ]);
      LandingPage = landingModule.default;
      LatestEventsPage = eventsModule.default;
      setComponentsLoaded(true);
    }
    loadComponents();
  }, []);

  // 加载完成前显示兜底内容
  if (!componentsLoaded) {
    return <div>加载中...</div>;
  }

  return (
    <html>
      <body>
        <Suspense fallback={<div>加载中...</div>}>
          <LandingPage />
          <LatestEventsPage />
        </Suspense>
      </body>
    </html>
  );
}

内容的提问来源于stack exchange，提问作者Vlady Veselinov