编程 Vite 8 升级后构建通过、运行时却报 greet is not a function:Rolldown 改了 CJS 互操作规则

2026-11-19 21:06:08

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。

排查顺序

  1. 确认报错只在 vite build 后出现、dev 正常———基本可以锁定到 CJS 互操作。
  2. 看报错对象的形状:is not a function 或 [object Object],打印一下拿到的是 module.exports 还是 .default,对照上面三条规则判断该包命中哪一条。
  3. 检查 importer 的扩展名,以及最近的 package.json 有没有 "type": "module";再检查被导入包有没有设 __esModule。
  4. 在调用点按 __esModule 显式取值,先把运行跑通。
  5. 排查配置里是否还有 build.commonjsOptions,逐条确认每个 include/exclude 原本是为了绕哪个包,改成调用点处理或推动上游修复。
  6. 库作者额外检查产物:UMD/IIFE 里的 import.meta.url、以及被保留成 require 的 external;需要时补 esmExternalRequirePlugin 和 define + intro。
  7. 短期内用 legacy.inconsistentCjsInterop: true 争取时间,同时把问题报到上游。
复制全文 生成海报 vite 前端 构建 javascript

推荐文章

程序员茄子在线接单