Next.js中Redux Persist页面刷新后用户数据丢失问题求助

问题背景 #

使用 Redux Toolkit 管理用户数据（访问令牌、用户信息），引入 Redux Persist 配置后，页面刷新时用户数据丢失，未达到持久化预期。

技术栈与依赖版本 #

• 框架：Next.js + React + TypeScript
• 依赖版本：
  • @reduxjs/toolkit: ^1.9.5
  • react-redux: ^8.1.1
  • redux-persist: ^6.0.0
  • redux-thunk: ^2.4.2

相关代码片段 #

store.js #

// 示例配置（按用户实际代码调整）
import { configureStore } from '@reduxjs/toolkit';
import { persistStore, persistReducer } from 'redux-persist';
import storage from 'redux-persist/lib/storage';
import userReducer from './userSlice';

const persistConfig = {
  key: 'root',
  storage,
};

const persistedReducer = persistReducer(persistConfig, userReducer);

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

export const persistor = persistStore(store);

_app.js #

// 示例配置（按用户实际代码调整）
import { Provider } from 'react-redux';
import { PersistGate } from 'redux-persist/integration/react';
import { store, persistor } from '../store';

function MyApp({ Component, pageProps }) {
  return (
    <Provider store={store}>
      <PersistGate loading={null} persistor={persistor}>
        <Component {...pageProps} />
      </PersistGate>
    </Provider>
  );
}

export default MyApp;

userSlice.js #

// 示例配置（按用户实际代码调整）
import { createSlice } from '@reduxjs/toolkit';

const initialState = {
  token: null,
  userInfo: null,
};

const userSlice = createSlice({
  name: 'user',
  initialState,
  reducers: {
    setUser: (state, action) => {
      state.token = action.payload.token;
      state.userInfo = action.payload.userInfo;
    },
    clearUser: (state) => {
      state.token = null;
      state.userInfo = null;
    },
  },
});

export const { setUser, clearUser } = userSlice.actions;
export default userSlice.reducer;

用户数据设置方式 #

// 示例调用（按用户实际代码调整）
dispatch(setUser({ token: 'xxx', userInfo: { id: 1, name: 'test' } }));

排查与解决步骤 #

1. 检查 Redux Persist 与根 reducer 的绑定逻辑 #

• 若存在多个 reducer，需先通过 combineReducers 合并为根 reducer，再用 persistReducer 包裹，而非仅包裹单个 userReducer：

import { combineReducers } from '@reduxjs/toolkit';

const rootReducer = combineReducers({
  user: userReducer,
  // 其他需管理的 reducer
});

const persistedReducer = persistReducer(persistConfig, rootReducer);

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

2. 适配 Next.js SSR 环境的存储 #

Redux Persist 默认使用 localStorage，但 Next.js 服务端渲染时 window 对象不存在，会导致初始化失败：

// 自定义适配服务端的存储方案
import createWebStorage from 'redux-persist/lib/storage/createWebStorage';

const createNoopStorage = () => ({
  getItem() { return Promise.resolve(null); },
  setItem(_key, value) { return Promise.resolve(value); },
  removeItem() { return Promise.resolve(); },
});

const storage = typeof window !== 'undefined' ? createWebStorage('local') : createNoopStorage();

3. 确认 PersistGate 的包裹范围 #

• 必须保证 PersistGate 直接嵌套在 Provider 内部，且完整包裹所有页面组件，否则初始渲染时无法读取持久化数据。
• 避免在 PersistGate 的 loading 组件中执行状态重置或页面跳转，防止干扰数据恢复流程。

4. 排查状态重置逻辑 #

• 检查 userSlice 中是否存在意外重置 initialState 的逻辑，Redux Persist 会在初始化时将持久化数据合并到初始状态，若有异步初始化或外部代码强制重置状态，会导致数据丢失。
• 确认 setUser 动作的 payload 结构正确，没有遗漏字段或错误覆盖状态。

5. 验证浏览器存储状态 #

• 打开浏览器开发者工具的「Application」面板，查看 localStorage 中是否存在 persist:root 键值对：
  • 若不存在：检查是否有代码在页面加载时调用 clearUser，或 persistConfig 的 key 配置错误。
  • 若存在但未加载：确认 persistor 实例正确传入 PersistGate，且没有禁用持久化的逻辑。

6. 排除依赖冲突 #

• 清除 node_modules 和 package-lock.json，重新安装依赖，排查版本兼容问题。当前依赖版本组合本身兼容，但局部依赖冲突可能导致功能异常。

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