immer 导入报错,九成出在模块解析和打包配置:要么是 ESM 与 CJS 混用导致 default 取不到,要么是 Tree Shaking 把 produce 摇掉了,要么是 React 18 下从 'immer' 取 useImmer 的路径写错。先按这三类逐一核对,大多能立刻定位。本文先给结论,再逐个讲清排查顺序与修复代码,帮你把三类报错一次定位,而不是无头苍蝇式重试。无论你用的是 Vite、Webpack 还是 Node 的 CommonJS 工程,报错的根因都逃不出这三个方向,按「先读报错信息 → 再判模块系统 → 最后查打包配置与子路径」的顺序排查,基本都能在几分钟内收敛,不用再到处搜碎片答案。真正难的不是写出 produce,而是让它在你的构建链里始终被正确解析。

先看结论
先把结论摆清楚。immer 本质是帮你在 React Hooks 这类响应式写法里优雅地生成不可变数据:你写一份「看起来可变」的草稿,它返回一份新的不可变数据,原状态不动。导入报错的根因基本逃不出三类:模块系统不匹配、打包器误删、子路径写错。下面用 React 里的不可变数据 承接这类用法,理解它在不同模块规范下的导出形态差异。排查顺序也固定——先看打包器报的是 cannot find module 还是 default is not a function,前者是路径或依赖问题,后者几乎一定是 ESM/CJS 混用。记住一个原则:报错信息里出现 default,先怀疑解构方式;出现 produce is not a function,先怀疑被摇树摇掉了。把入口收口到一处,能避免绝大多数重复踩坑。
不可变数据思想本身不复杂:你永远不直接改原对象,而是基于旧状态计算出新状态。immer 用 produce 把这件事变得像改可变对象一样自然,但要理解它在不同模块规范下的导出形态差异,否则就会在导入这一步栽跟头。下面三类报错,覆盖了线上九成以上的案例,理解清楚后你甚至能在同事贴出报错前就预判问题所在。
一、ESM 与 CJS 混用导致 default 取不到
最常见的是在 CJS 项目里用 ESM 解构。immer 同时提供 ESM 和 CJS 产物,但 default 导出在两者里形态不同。在 CommonJS 环境直接 const { produce } = require('immer') 可能拿到 undefined,因为 produce 挂在 default 上,而不是作为具名导出暴露。
现代前端项目多基于 Vue.js 入门教程 这类 ESM 工程,写法应是:
import { produce } from 'immer';
const next = produce(base, draft => { draft.count += 1; });
如果在 Node 的 CJS 文件里,要改成:
const immer = require('immer');
const produce = immer.produce; // 而不是 const { produce } = require('immer')
这种差异的来源是打包器对 ESM/CJS 互操作(interop)的处理。当你用 import { produce } 但底层被当成 CJS 加载时,解构拿到的是整个模块对象上的具名属性,而 produce 实际在 default 上,于是得到 undefined。判断自己属于哪种:打开报错栈,若指向 bundle 的 interop 适配层,基本就是模块系统问题,调整 import 写法或加 esModuleInterop 即可。关于 immer 的更多实战用法,可以看这篇 Immer 使用笔记,里面把不可变数据更新画得很清楚,连嵌套 draft 的冻结与草稿合并都讲到了。
一个容易忽略的细节是:同一个项目里如果混用了 Vite 的 ESM 产物和某个 CJS 依赖的 interop 垫片,produce 的解析结果可能在开发期正常、构建期翻车。所以锁定模块规范比事后打补丁更稳,也更容易在 CI 里用一条 lint 规则兜住。
二、Tree Shaking 把 produce 摇掉
第二类发生在生产构建。某些打包配置在 minify 阶段把「未被静态分析确认使用」的 named export 摇掉,运行时 produce 变成 undefined,报 produce is not a function。这在按需引入、动态 import 的场景里尤其多,本地开发正常、一上线就炸。
兜底写法是用全量 import 保住引用:
import * as immer from 'immer';
const next = immer.produce(base, d => { d.x = 1; });
或者用 sideEffects 标记避免误删。需要系统了解常见坑的,可以对照 新手常犯的错误清单 逐条排查自己的构建配置。验证方法很简单:在报错位置前打印 typeof produce,如果是 undefined 而非 function,就坐实了被摇掉。临时方案是关掉该依赖的 minify,确认恢复后再针对性加 sideEffects 白名单,而不是一刀切关掉整个压缩,否则会牺牲线上性能。
Tree Shaking 的误判往往源于打包器无法证明 produce 一定会被调用。当你用 import { produce } 且只在条件分支里使用时,激进的压缩器可能判定它为死代码。全量 import * as immer 能让引用变得可观测,是最稳的兜底;更彻底的治本是给 immer 所在的包加 "sideEffects": false 或在打包器配置里声明该依赖不被摇树,从根上消除误删。

三、React 18 下 useImmer 引入路径写错
第三类专属于 React 用户。immer 从 9.x 起把 React 绑定拆到了 'immer' 的对应导出,早期文档却写从 'immer' 取 useImmer,新版要确认导出是否存在:
import { useImmer } from 'immer';
// 若报错,先检查版本;某些版本需从 'immer/react' 引入
如果装的是旧版却按新文档写,就会 cannot find export useImmer。排查固定三步:先看 package.json 里的 immer 版本,再查该版本的导出表,最后对齐 import 路径。状态管理相关的不可变更新逻辑建议收口到一个文件,所有组件从那里取 produce 和 useImmer,避免散落各处的路径写法不一致,后续升级版本时只改一处。这样即使官方再次调整导出位置,影响也被限制在一个模块内,不至于牵一发动全身。

实操检查清单
- 前置:先确认你的构建工具与模块规范(Webpack / Vite / Node CJS),并准备好可复现的最小工程。
- 操作:按本文三类顺序运行对应改法,观察实际报错是否消失。
- 检查:看打包器报的是 cannot find module 还是 default is not a function,预期对得上根因。
- 失败处理:若仍报错,按「模块系统 → 打包摇树 → 子路径」逐条修复并重新验证。
- 适用边界:该方案适用于 React / 前端工程化场景;Node 纯 CJS 工程需改用 require 写法。
总结
回到开头:immer 导入报错按「模块系统 → 打包摇树 → 子路径」三步走,先读报错类型再对症。ESM/CJS 混用就改解构写法,produce 被摇掉就改用全量 import 或加 sideEffects,useImmer 取不到就核对版本与导出路径。把不可变数据的更新入口集中管理,既能规避路径冲突,也让状态管理更可控。真正难的不是写出 produce,而是让它在你的构建链里始终被正确解析——理清模块规范,报错自然消失。
常见问题
Q:为什么本地开发正常、打包后就报 produce is not a function?
这是典型的 Tree Shaking 问题。开发模式不压缩所以引用在,生产压缩时被摇掉。按上文改用 import * as immer 或给依赖加 sideEffects 白名单即可。
Q:require('immer') 解构出 undefined 怎么破?
说明项目是 CommonJS 上下文,produce 在 default 上。用 const immer = require('immer'); const produce = immer.produce; 显式取,或把文件改成 ESM 用命名导入。
Q:useImmer 提示不存在怎么办?
先确认 immer 版本与文档匹配,早期版本从 'immer' 导出,新版可能改到 'immer/react'。对齐 package.json 版本和官方导出表即可。

TRAE-AI编程



