Vite 8 升级后构建通过、运行时却报 greet is not a function:Rolldown 改了 CJS 互操作规则
Vite 8 用 Rolldown + Oxc 替换了 esbuild + Rollup,其中一条改动是「统一 CommonJS 互操作」。这条规则改动的危险之处,是它不会让构建报错,只会让产物在运行时出错。
参考链接:
- 迁移指南:https://vite.dev/guide/migration
- Vite 8 发布公告:https://vite.dev/blog/announcing-vite8
- 升级踩坑记录:https://ortamarco.me/en/blog/what-breaks-upgrading-to-vite-8/
- 真实案例:https://github.com/AfterShip/phone/issues/455
新规则:default import 拿什么
从 CJS 模块 default import 时,只要满足下面任意一条,拿到的是整个 module.exports;否则拿到 module.exports.default:
- importer 是
.mjs/.mts; - importer 最近的
package.json里"type": "module"; - 被导入的 CJS 模块的
module.exports.__esModule不是true。
Vite 7 时代 dev 和 build 用的是两套规则:dev 还额外依赖 importer 是否被包含进依赖预构建(加上 .mjs/.mts、type 字段和 __esModule),build 侧则是 __esModule 不为 true、且 module.exports 上没有 default 属性(build.commonjsOptions.defaultIsModuleExports 默认 'auto')。两套规则并存,正好让 bug 一路走到生产环境才暴露———只在 build 后出现的怪问题,多半源于这个差异。
症状
Vite 的 troubleshooting 里叫「Default import unexpectedly returns an object」:你期望拿到 module.exports.default,实际拿到整个 module.exports 对象。表现是 x.default is not a function、组件渲染成 [object Object],而构建日志一片正常。
真实案例是 Storybook 的 Next.js 集成,经依赖预构建触发,React 报:
Element type is invalid: expected a string (for built-in components)
or a class/function (for composite components) but got: object.
最小复现:cjs-pkg 里 module.exports = { __esModule: true, default: function greet() {} },调用方:
import greet from 'cjs-pkg';
greet();
Vite 7 dev 下能跑;Vite 8 下 importer 是普通 .js 且没有 "type": "module",直接 TypeError: greet is not a function。
临时回退
export default defineConfig({
legacy: { inconsistentCjsInterop: true },
})
该选项已标记 deprecated,文档的建议是把它当作过渡:把受影响的包反馈给上游修复(附上 Rolldown 的 CJS interop 文档链接),而不是长期打补丁。
单点修复
按 Rolldown 文档,不要猜,直接看 __esModule:
import raw from 'some-cjs-package'
const actual =
typeof raw === 'object' && raw !== null && raw.__esModule ? raw.default : raw
不要简写成 raw.default ?? raw。一个普通 CJS 模块如果导出的对象自带 default 字段、又没设 __esModule,它的整个 module.exports 恰恰就是 Rolldown 交给你的东西;?? 会在这种情况下取错。
三个连带变化
build.commonjsOptions 现在完全失效,不报警、不报错,直接忽略。如果你的配置里用 include/exclude/requireReturnsDefault 绕开过某个 CJS 包,这段补丁会静默失效,症状出现在下游模块上,很容易归因到错误的代码。
对 external 模块的 require 不再被转成 import,会原样保留(影响 SSR / Node target 的构建)。需要旧行为时用 Vite 重新导出的 Rolldown esmExternalRequirePlugin。
import.meta.url 在 UMD/IIFE 产物里不再被 polyfill,默认替换成 undefined。于是 new URL('./worker.js', import.meta.url) 变成 new URL('./worker.js', undefined),发布出去的库在消费者那边运行时报错,而你的构建是成功的。补救方式是用 define 配合 build.rolldownOptions.output.intro。
另外,.cjs 文件现在严格按 CJS 语义处理:以扩展名声明为 CommonJS 的文件不能用 ESM-only 语法,包括动态 import()。Vite 7 + esbuild 对此是放行的。
其余改动:JS API 用户拿到的 build() 抛出的是 BundleError 而非插件的原始错误,类型为 Error & { errors?: RolldownError[] };output.manualChunks 的对象形式移除,函数形式废弃,改用 Rolldown 的 codeSplitting;插件作者注意模块类型自动检测,在 load/transform 里把内容转成 JS 时要加 moduleType: 'js';默认浏览器目标抬高到 Chrome/Edge 111、Firefox 114、Safari 16.4。
排查顺序
- 确认报错只在
vite build后出现、dev 正常———基本可以锁定到 CJS 互操作。 - 看报错对象的形状:
is not a function或[object Object],打印一下拿到的是module.exports还是.default,对照上面三条规则判断该包命中哪一条。 - 检查 importer 的扩展名,以及最近的
package.json有没有"type": "module";再检查被导入包有没有设__esModule。 - 在调用点按
__esModule显式取值,先把运行跑通。 - 排查配置里是否还有
build.commonjsOptions,逐条确认每个include/exclude原本是为了绕哪个包,改成调用点处理或推动上游修复。 - 库作者额外检查产物:UMD/IIFE 里的
import.meta.url、以及被保留成require的 external;需要时补esmExternalRequirePlugin和define+intro。 - 短期内用
legacy.inconsistentCjsInterop: true争取时间,同时把问题报到上游。