React v18+SSR环境下redux-persist导致重复渲染问题求助

问题概述 #

将Next.js 12（搭配React 17）升级到Next.js 13（强制React 18）后，SSR应用出现服务端渲染内容与客户端渲染内容同时显示的重复渲染问题，排查后确认是redux-persist的PersistGate组件与React 18的hydration机制不兼容导致。

原实现逻辑为：服务端直接渲染页面内容，客户端用PersistGate包裹组件以恢复持久化状态，该逻辑在React 17下正常，但React 18中失效。同时在纯React SSR环境中也复现了相同问题，说明问题核心在React 18与PersistGate的适配。

原PersistStore组件代码：

import React from 'react';
import { PersistGate } from 'redux-persist/integration/react';

function PersistStore(props) {
  if (typeof window === 'undefined') {
    // 服务端直接返回子组件
    return (
      <React.Fragment>
        {props.children}
      </React.Fragment>
    );
  }

  // 客户端用PersistGate包裹
  return (
    <PersistGate loading={null} persistor={props.persistor}>
      {props.children}
    </PersistGate>
  );
}

export default PersistStore;

原_app.js调用逻辑：

function MyApp({ Component, pageProps }) {
  return (
    <ReactReduxContext.Consumer>
      {({ store }) => (
        <PersistStore persistor={store.__persistor}>
          <Component {...pageProps} />
        </PersistStore>
      )}
    </ReactReduxContext.Consumer>
  );
}

解决方案 #

React 18对hydration的严格性提升，要求客户端初始渲染的DOM结构必须与服务端完全一致。原逻辑中客户端直接渲染PersistGate，导致DOM结构与服务端不匹配，触发重复渲染。以下是适配方案：

方案1：修改PersistStore组件，确保客户端初始渲染与服务端一致 #

通过useState和useEffect控制客户端渲染时机，在hydration完成后再挂载PersistGate：

import React, { useEffect, useState } from 'react';
import { PersistGate } from 'redux-persist/integration/react';

function PersistStore({ persistor, children }) {
  const [isHydrated, setIsHydrated] = useState(false);

  useEffect(() => {
    // 客户端hydration完成后标记状态
    setIsHydrated(true);
  }, []);

  if (typeof window === 'undefined') {
    // 服务端直接返回子组件
    return <>{children}</>;
  }

  // 客户端初始渲染与服务端保持一致，hydration完成后再渲染PersistGate
  if (!isHydrated) {
    return <>{children}</>;
  }

  return (
    <PersistGate loading={null} persistor={persistor}>
      {children}
    </PersistGate>
  );
}

export default PersistStore;

方案2：手动调用persistStore替代PersistGate #

如果不需要PersistGate的loading状态管理，可直接在客户端手动触发持久化，避免组件结构不匹配：

// 在_app.js中修改
import { useEffect } from 'react';
import { persistStore } from 'redux-persist';
import { ReactReduxContext } from 'react-redux';

function MyApp({ Component, pageProps }) {
  return (
    <ReactReduxContext.Consumer>
      {({ store }) => {
        useEffect(() => {
          // 客户端环境下初始化持久化
          const persistor = persistStore(store);
          // 可选：监听持久化完成事件
          persistor.subscribe(() => {
            console.log('Redux state persisted');
          });
        }, [store]);

        return <Component {...pageProps} />;
      }}
    </ReactReduxContext.Consumer>
  );
}

原理说明 #

React 18的hydration机制会严格校验客户端与服务端的DOM结构，原逻辑中客户端直接渲染PersistGate会导致额外的DOM层级，触发React的"不匹配"警告，最终导致服务端渲染内容未被替换，反而叠加显示。

方案1通过延迟PersistGate的渲染时机，确保客户端初始渲染与服务端完全一致，hydration完成后再切换到带持久化的组件结构，既满足SSR要求，又保证redux-persist正常工作。

内容的提问来源于stack exchange，提问作者j.grima