NextJS 14中redux-persist同步存储创建失败问题求助

错误原因 #

NextJS 14的App Router默认以服务器组件模式运行，而redux-persist依赖的localStorage是浏览器专属API，服务器端环境无法访问该API，导致初始化存储失败，进而回退到空操作存储（noop storage）。

解决方案 #

方案1：安全适配服务器/客户端的存储逻辑 #

修改你的store文件，替换原有的storage导入逻辑，确保仅在浏览器环境使用localStorage，服务器端使用空存储占位：

import {
  configureStore,
  combineReducers,
  getDefaultMiddleware,
} from '@reduxjs/toolkit';
import {
  persistStore,
  persistReducer,
  FLUSH,
  REHYDRATE,
  PAUSE,
  PERSIST,
  PURGE,
  REGISTER,
} from 'redux-persist';
// 替换原storage导入，改用createWebStorage手动创建
import createWebStorage from "redux-persist/lib/storage/createWebStorage";
import postingsReducer from '@/redux/slices/postingsSlice';
import newPostingFormReducer from '@/redux/slices/newPostingSlice';
import userReducer from '@/redux/slices/userSlice';

// 创建服务器端用的空存储，避免报错
const createNoopStorage = () => {
  return {
    getItem() {
      return Promise.resolve(null);
    },
    setItem(_key, value) {
      return Promise.resolve(value);
    },
    removeItem() {
      return Promise.resolve();
    },
  };
};

// 仅在浏览器环境使用localStorage，服务器端用空存储
const storage = typeof window !== "undefined" ? createWebStorage("local") : createNoopStorage();

const persistConfig = {
  key: 'root',
  storage,
  // Optionally, blacklist any reducers here
};

const rootReducer = combineReducers({
  postings: postingsReducer,
  newPosting: newPostingFormReducer,
  user: userReducer,
});

const persistedReducer = persistReducer(persistConfig, rootReducer);

export const store = configureStore({
  reducer: persistedReducer,
  middleware: getDefaultMiddleware =>
    getDefaultMiddleware({
      serializableCheck: {
        ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER],
      },
    }),
});

export const persistor = persistStore(store);

方案2：确保Store仅在客户端初始化 #

如果方案1仍未解决问题，可通过动态导入方式，让Store的初始化逻辑仅在客户端执行：
修改providers.tsx文件：

'use client';
import React, { useEffect, useState } from 'react';
import { Provider } from 'react-redux';
import { PersistGate } from 'redux-persist/integration/react';
import { NextUIProvider } from '@nextui-org/react';
import { ThemeProvider as NextThemesProvider } from 'next-themes';

export default function Providers({ children }: { children: React.ReactNode }) {
  const [store, setStore] = useState(null);
  const [persistor, setPersistor] = useState(null);

  useEffect(() => {
    // 动态导入Store，仅在客户端执行初始化
    import('@/redux/store').then((module) => {
      setStore(module.store);
      setPersistor(module.persistor);
    });
  }, []);

  if (!store || !persistor) {
    return <div>Loading...</div>;
  }

  return (
    <Provider store={store}>
      <PersistGate
        loading={<div>Providers Loading...</div>}
        persistor={persistor}
      >
        <NextUIProvider>
          <NextThemesProvider
            attribute="class"
            defaultTheme="bounty"
            themes={['bitcoin', 'amce', 'bounty']}
          >
            {children}
          </NextThemesProvider>
        </NextUIProvider>
      </PersistGate>
    </Provider>
  );
}

额外检查 #

• 确保所有直接导入store的组件都添加了'use client'指令，避免服务器组件触发Store初始化；
• 重启开发服务器，刷新页面验证错误是否消失，同时测试页面刷新后Redux状态是否正常持久化。

内容的提问来源于stack exchange，提问作者Leon Gaban