代码 Vite 8 里 manualChunks 报 TypeError:换成 codeSplitting.groups 的最小改动

2026-11-21 21:07:10

Vite 8 里 manualChunks 报 TypeError:换成 codeSplitting.groups 的最小改动

环境

  • macOS,Node.js v25.9.0
  • Vite 7.3.8(对照)与 Vite 8.3.8(2026-11-11)

Vite 8.0 于 2026-03-12 发布,开发与构建统一走 Rust 的 Rolldown,JS 转译与压缩换成 Oxc,CSS 压缩默认 Lightning CSS。旧 esbuild 选项和 build.rollupOptions 会被自动转换,所以不少项目不改配置也能 build。但 output.manualChunks 的对象形式不会被自动转换。

报错

Vite 7.3.8 的空项目里,对象形式工作正常:

build: {
  rollupOptions: {
    output: {
      manualChunks: { vendor: ['cjs-pkg'] }
    }
  }
}

同一份配置升到 8.3.8,vite build 直接失败:

TypeError: manualChunks is not a function

迁移指南的说明是:对象形式的 output.manualChunks 不再支持,函数形式被标记弃用,替代方案是 Rolldown 的 codeSplitting。

最小改动前后

改后配置:

build: {
  rolldownOptions: {
    output: {
      codeSplitting: {
        groups: [
          { name: 'vendor', test: /cjs-pkg/, minSize: 0 }
        ]
      }
    }
  }
}

对应关系是逐项翻译:对象形式的 key vendor 变成 name,包名数组 ['cjs-pkg'] 变成 test 正则 /cjs-pkg/,外层 rollupOptions 换成 rolldownOptions。

minSize 不写就不会切出 chunk

这个例子容易踩坑:测试模块只有几行。第一次配置只写了 name 和 test,build 成功,但没有生成 vendor-*.js,产物里看不到独立 chunk。补上 minSize: 0 之后,vendor-*.js 才出现。

也就是说 groups 不是「命中 test 就切」,还要过体积阈值。真实项目不要照抄 minSize: 0,按 Rolldown 的 Manual Code Splitting 文档按需调整。

配置名对应

  • esbuild.jsx: 'automatic' → oxc.jsx: { runtime: 'automatic' },即 esbuild 选项整体换成 oxc
  • optimizeDeps.esbuildOptions → optimizeDeps.rolldownOptions
  • build.rollupOptions → build.rolldownOptions;worker.rollupOptions → worker.rolldownOptions
  • build.commonjsOptions 现在是 no-op,配了也不生效
  • build.rollupOptions.watch.chokidar 已移除,改为 build.rolldownOptions.watch.watcher

哪些能照抄,哪些要查文档

能直接照抄的情况:原来只用对象形式 manualChunks,一个 key 对一个包名数组,分组语义就是「把这些包单独切出去」。把每个 key 改 name、包名转 test 正则、rollupOptions 改 rolldownOptions,再按实际模块体积给 minSize 一个合理值即可。

需要读 Rolldown 文档再动手的情况:

  • 原来用函数形式 manualChunks(id) { ... } 按路径做细粒度判断的。函数形式已弃用,逻辑要重新表达成多个 groups,组之间的优先级和匹配顺序得自己确认。
  • 有多个分组、需要控制 shared chunk 归属的项目,groups 的匹配顺序直接决定产物结构。
  • 对 chunk 体积敏感、需要精确控制拆包边界的项目,minSize 和默认值的关系必须实测,不能凭感觉填。

函数形式的弃用是标记而非立即移除,但既然对象形式已经硬报错,同一处配置里两种写法混用没有意义,升级时一并换掉。

复制全文 生成海报 Vite 前端 构建 Rolldown

推荐文章

程序员茄子在线接单