本文详解如何在使用 rtk query 的同时保留 redux-persist 功能，解决因中间件升级引发的非可序列化值警告（如 `persist/persist` 中的 `register` 函数），关键在于正确配置 `serializablecheck.ignoredactions`。
在将 RTK Query 集成到现有 Redux Toolkit 项目时，常见的误区是直接替换 middleware 字段为函数式写法（如 getDefaultMiddleware => ...），却忽略了默认中间件中新增的 可序列化性检查（serializable check） —— 这一严格校验机制会拦截 redux-persist 内部使用的函数型 payload（如 register、rehydrate），从而抛出类似以下错误：
A non-serializable value was detected in an action, in the path: register. Value: function register(key).
这是因为 redux-persist 为实现持久化状态恢复，需在 action 中传递函数引用（如 REGISTER action 携带 register(key)），而该行为天然违反 Redux Toolkit 默认启用的 serializableCheck 规则。
✅ 正确做法不是禁用整个检查，而是精准忽略 redux-persist 的特定内部 action 类型。RTK 官方明确支持此方案，并提供了标准常量导入方式。
首先，确保安装并导入 redux-persist 的 action 类型常量：
npm install redux-persist # 或 yarn add redux-persist
然后，在 configureStore 配置中更新 middleware 选项，显式忽略 persist 相关 action，并保留 apiSlice.middleware：
import { configureStore, combineReducers } from '@reduxjs/toolkit';
import { persistReducer, persistStore } from 'redux-persist';
import storage from 'redux-persist/lib/storage';
import { getPersistConfig } from 'redux-deep-persist';
import { FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER } from 'redux-persist/es/constants'; // ✅ 关键：导入 persist action 类型
import { apiSlice } from './api';
import { settingsReducer, userReducer } from './reducers'; // 假设路径
export const rootReducer = combineReducers({
settings: settingsReducer,
user: userReducer,
[apiSlice.reducerPath]: apiSlice.reducer, // ✅ 注册 API slice reducer
});
const config = getPersistConfig({
key: 'root',
storage,
whitelist: ['user.name', 'settings.color'],
rootReducer,
});
const persistedReducer = persistReducer(config, rootReducer);
export const store = configureStore({
reducer: persistedReducer,
devTools: process.env.NODE_ENV !== 'production',
middleware: (getDefaultMiddleware) =>
getDefaultMiddleware({
serializableCheck: {
ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER], // ✅ 精准豁免
},
}).concat(apiSlice.middleware), // ✅ 自动包含 thunk、immutableCheck 等默认中间件
});
export const persistor = persistStore(store);
export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;? 注意事项：
- getDefaultMiddleware() 已内置 thunk，无需手动添加 thunk 到数组中 —— 直接 .concat(apiSlice.middleware) 即可同时支持 thunk 和 RTK Query。
- ignoredActions 中的常量必须来自 redux-persist/es/constants（而非 redux-persist 根路径），避免类型不匹配或未定义问题。
- 若使用 TypeScript，建议配合 @reduxjs/toolkit v1.9+ 和 redux-persist v6.0+，以获得最佳类型推导与兼容性。
- 不推荐设置 serializableCheck: false 全局关闭检查，这会掩盖真实的数据序列化隐患，降低应用健壮性。
通过上述配置，你既能享受 RTK Query 提供的自动缓存、请求生命周期管理与类型安全，又能无缝延续 redux-persist 的本地持久化能力，且完全符合 Redux Toolkit 的现代实践规范。
