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 选项整体换成 oxcoptimizeDeps.esbuildOptions→optimizeDeps.rolldownOptionsbuild.rollupOptions→build.rolldownOptions;worker.rollupOptions→worker.rolldownOptionsbuild.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和默认值的关系必须实测,不能凭感觉填。
函数形式的弃用是标记而非立即移除,但既然对象形式已经硬报错,同一处配置里两种写法混用没有意义,升级时一并换掉。