如何在Redux Toolkit中兼容Immutable.js并保留状态检查？

问题背景 #

迁移遗留Redux代码到Redux Toolkit（RTK）时，原有代码依赖Immutable.js保证状态不可变性，新代码不再使用Immutable.js，但希望遗留代码无需修改就能正常运行。使用RTK的configureStore后，应用抛出不可变性检查错误：

Invariant failed: A state mutation was detected between dispatches, in the path 'app._values._tail.array.0._values._root.array.0.array.16._defaultValues.gcm.__hash'. This may cause incorrect behavior.

虽然可以通过完全禁用检查解决：

immutableCheck: false,
serializableCheck: false,

但这种方式会关闭所有状态检查，风险较高。需要仅让Immutable.js对象绕过这些检查，保留对普通JS对象的校验。

适配最新Immutable.js API的解决方案 #

旧代码因Immutable.js API更新（Iterable改为Collection，无isIterable方法）失效，需基于当前Immutable.js的isImmutable()方法重新配置RTK中间件：

1. 导入依赖 #

确保已安装@reduxjs/toolkit和immutable，然后导入所需模块：

import { configureStore, createSerializableStateInvariantMiddleware, createImmutableStateInvariantMiddleware } from '@reduxjs/toolkit';
import Immutable from 'immutable';

2. 自定义不可变性检查中间件 #

配置createImmutableStateInvariantMiddleware，让它识别Immutable对象并跳过突变检查：

const immutableMiddleware = createImmutableStateInvariantMiddleware({
  isImmutable: (value) => {
    // 标记所有Immutable实例为不可变对象，跳过检查
    return Immutable.isImmutable(value);
  }
});

3. 自定义序列化检查中间件 #

配置序列化中间件，允许Immutable对象通过检查，并适配其条目遍历逻辑：

const serializableMiddleware = createSerializableStateInvariantMiddleware({
  isSerializable: (value) => {
    // 允许Immutable对象、非对象类型或null通过序列化检查
    return Immutable.isImmutable(value) || typeof value !== 'object' || value === null;
  },
  getEntries: (value) => {
    // 对Immutable对象使用自身的entries方法，普通对象用Object.entries
    return Immutable.isImmutable(value) ? value.entries() : Object.entries(value);
  }
});

4. 配置Store并替换中间件 #

使用getDefaultMiddleware()合并自定义中间件，保留RTK默认的其他功能（如thunk异步支持）：

const store = configureStore({
  reducer: rootReducer, // 替换为你的根reducer
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware()
      .replace(immutableMiddleware)
      .replace(serializableMiddleware)
});

核心逻辑说明 #

• 用Immutable.isImmutable()精准判断Immutable实例，替代旧版的Iterable.isIterable()
• 不可变性中间件仅跳过Immutable对象的突变检查，普通JS对象的校验依然生效
• 序列化中间件适配Immutable对象的遍历方式，避免因无法序列化而报错
• 通过replace()方法替换默认中间件，不丢失RTK自带的其他中间件能力

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