设置redux-persist的manualPersist为true时组件无法渲染的问题

背景 #

根据redux-persist v6.0.0文档，persistStore(store, [config, callback])支持manualPersist配置项：

如果希望避免调用persistStore后立即开始持久化，可设置manualPersist选项，示例：{ manualPersist: true }。之后可通过persistor.persist()在任意时刻启动持久化，通常在调用persistStore时存储未就绪时使用此配置。

我按照文档编写了以下代码：

store.ts #

import { combineReducers, configureStore } from '@reduxjs/toolkit';
import { PersistorOptions, persistReducer, persistStore } from 'redux-persist';
import storage from 'redux-persist/lib/storage';
import { testSlice } from './testSlice';

const rootReducer = combineReducers({
  test: testSlice.reducer,
});

const presistedReducer = persistReducer(
  {
    key: 'root',
    storage,
  },
  rootReducer
);

export const store = configureStore({
  reducer: presistedReducer,
});

export const persistor = persistStore(store, {
  manualPersist: true,
} as PersistorOptions);

main.tsx #

import ReactDOM from 'react-dom/client';
import { Provider } from 'react-redux';
import App from './App';
import './index.css';
import { PersistGate } from 'redux-persist/integration/react';
import { persistor, store } from './store';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <Provider store={store}>
    <PersistGate loading={null} persistor={persistor}>
      <App />
    </PersistGate>
  </Provider>
);

App.tsx #

import { persistor } from './store';
import './App.css';

function App() {
  return (
    <div>
      <button
        type="button"
        onClick={() => {
          persistor.persist();
        }}
      >
        persist
      </button>
    </div>
  );
}

export default App;

问题 #

设置manualPersist: true后，<App/>组件完全无法渲染，浏览器控制台也没有错误日志。我的需求是通过点击按钮手动触发状态持久化，请问这是什么原因？

原因分析 #

manualPersist: true的作用是同时禁用redux-persist的自动状态恢复（rehydrate）和自动持久化。而PersistGate组件的核心逻辑是：等待persistor完成状态恢复流程后，才会渲染包裹的子组件。由于自动rehydrate被禁用，PersistGate会一直处于等待状态，永远不会渲染<App/>。

解决方案 #

要解决这个问题，需要手动触发状态恢复，让PersistGate完成等待流程，同时保留手动触发持久化的逻辑。有两种常用方式：

方式1：在初始化时手动调用rehydrate #

在main.tsx中导入persistor后，直接调用persistor.rehydrate()：

import ReactDOM from 'react-dom/client';
import { Provider } from 'react-redux';
import App from './App';
import './index.css';
import { PersistGate } from 'redux-persist/integration/react';
import { persistor, store } from './store';

// 手动触发状态恢复
persistor.rehydrate();

ReactDOM.createRoot(document.getElementById('root')!).render(
  <Provider store={store}>
    <PersistGate loading={null} persistor={persistor}>
      <App />
    </PersistGate>
  </Provider>
);

方式2：通过PersistGate的onBeforeLift回调触发rehydrate #

利用PersistGate提供的onBeforeLift回调，在组件挂载前手动触发rehydrate：

ReactDOM.createRoot(document.getElementById('root')!).render(
  <Provider store={store}>
    <PersistGate 
      loading={null} 
      persistor={persistor}
      onBeforeLift={() => persistor.rehydrate()}
    >
      <App />
    </PersistGate>
  </Provider>
);

完成上述修改后，PersistGate会在状态恢复完成后渲染<App/>，点击按钮调用persistor.persist()即可手动触发状态持久化。

内容的提问来源于stack exchange，提问作者Lin Du