NGRX Action 不可变性报错解决方法

NGRX 15+ 默认启用严格的运行时不可变性检查，导致直接修改 action（如 `action.item.name = ...`）会抛出“Cannot add property, object is not extensible”错误；本文深入剖析了该机制的原理——所有 action 及其嵌套对象均被 `Object.freeze()` 冻结，进而系统性地给出了根本解决方案：彻底摒弃就地修改，转而通过 `map` 等操作符函数式地创建全新对象（如使用展开运算符或 Immer），并明确区分数据转换（用 `map`）与副作用处理（用 `tap`），同时警示禁用检查仅限临时调试、绝不可用于生产——因为坚守不可变性不仅是绕过报错的技巧，更是保障状态可预测、可回溯、可测试与可调试的架构基石。

NGRX 15+ 默认启用严格不可变性检查，直接修改 action 对象属性（如 `action.item.name`）会触发 “Cannot add property, object is not extensible” 错误；根本解决方式是遵循不可变原则创建新对象，而非就地修改。

在 NGRX 15.x 及更高版本中，@ngrx/store 默认启用了运行时不可变性检查（runtime checks），其中 strictStateImmutability 和 strictActionImmutability 均为 true。这意味着：所有 action 实例（包括其嵌套属性）均被 Object.freeze() 处理，变为不可扩展、不可修改的对象。因此，以下写法必然失败：

tap((action: users.LoadUsersAction) => {
  action.item.name = action.payload; // ❌ TypeError: Cannot add property name, object is not extensible
  action.item.id = action.payload.map(item => item.id); // ❌ 同样报错
});

即使尝试浅拷贝（如 {...action.item} 或 Object.assign），若 action.item 本身也被冻结（NGRX 默认递归冻结嵌套对象），仍无法赋值。

✅ 正确做法：始终返回新对象，不修改原 action

应将逻辑重构为纯函数式操作，在管道中使用 map 或 switchMap 等操作符生成全新 action 负载或副作用数据，而非篡改输入 action：

users$ = createEffect(() => 
  this.actions$.pipe(
    ofType(users.LOAD_USERS),
    map((action: users.LoadUsersAction) => {
      // ✅ 安全：基于原 action 构建全新数据结构，不修改任何冻结对象
      const newItem = {
        ...action.item,
        name: action.payload, // 假设 payload 是 string
        id: Array.isArray(action.payload) 
          ? action.payload.map((item: any) => item.id) 
          : [action.payload?.id] // 根据实际类型调整
      };
      return { newItem }; // 或 dispatch 新 action，如 users.UPDATE_ITEM({ item: newItem })
    }),
    tap(({ newItem }) => {
      console.log('Processed item:', newItem);
      // 执行副作用（如日志、埋点），但不修改 state 或 action
    })
  )
);

⚠️ 注意：tap 仅用于副作用（无返回值），不可用于转换数据流；数据转换必须使用 map、switchMap 等返回新 observable 的操作符。

? （不推荐）临时禁用不可变性检查（仅限调试）

若需快速验证逻辑（例如迁移旧代码阶段），可通过 Store 配置临时关闭检查（生产环境严禁使用）：

// app.config.ts 或 StoreModule.forRoot() 配置中
StoreModule.forRoot(reducers, {
  runtimeChecks: {
    strictStateImmutability: false,
    strictActionImmutability: false,
    // 其他检查项可视情况关闭
  }
}),

但此举会掩盖潜在 bug，削弱 NGRX 的核心优势——可预测的状态演进与时间旅行调试能力。

✅ 最佳实践总结

• 永远不要修改 action 或 state 的任何字段，包括深层属性；
• 使用展开运算符（{...obj}）、Object.assign({}, obj, updates) 或专用库（如 immer 配合 produce）安全生成新对象；
• 在 Effect 中，将数据处理逻辑放在 map/switchMap 内，确保输出为不可变新值；
• 利用 TypeScript 类型系统提前约束 action 结构，避免运行时意外属性赋值；
• 将副作用（如 API 调用、路由跳转）置于 tap，将状态变更逻辑交由 reducer 处理。

遵循不可变性原则不仅是规避错误的手段，更是构建可维护、可测试、可回溯的响应式应用的基石。

终于介绍完啦！小伙伴们，这篇关于《NGRX Action 不可变性报错解决方法》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！