前端工程化 / 系统课时
迁移 Rolldown 优化选项
迁移 Rolldown 优化选项
本课把 Vite 旧版 optimizeDeps.esbuildOptions 迁移为 optimizeDeps.rolldownOptions,并通过解析后的配置确认兼容层是否仍在工作。完成后,你能区分可直接映射、需要反转语义和必须重写的选项,避免升级后只消除警告却留下行为差异。
学习目标
- 将常用 esbuild 依赖优化选项改写为 Rolldown 结构
- 识别兼容层、弃用项和不能直接复制的插件配置
- 强制重建依赖缓存并验证最终生效配置
先划清迁移范围
Vite 8 的依赖预构建由 Rolldown 执行。optimizeDeps.esbuildOptions 仍会被兼容层转换,但它已经弃用,后续版本可能移除。迁移时只处理依赖扫描与预构建配置,不要把顶层 esbuild 转换配置或 build.rollupOptions 混入同一次替换。
常见映射如下。多数选项只是移动层级,preserveSymlinks 则需要反转布尔语义。
| 旧选项 | 新选项 | 迁移要点 |
|---|---|---|
minify |
output.minify |
进入输出配置 |
treeShaking |
treeshake |
名称与大小写变化 |
define |
transform.define |
进入转换配置 |
loader |
moduleTypes |
按文件类型重新核对 |
resolveExtensions |
resolve.extensions |
保持扩展名顺序 |
conditions |
resolve.conditionNames |
只影响优化器解析 |
preserveSymlinks |
resolve.symlinks |
新值等于旧值取反 |
plugins |
plugins |
仅部分兼容,必须逐个验证 |
改写为 Rolldown 配置
下面的完整配置关闭依赖压缩、保留函数名、启用摇树,并注入一个编译期常量。检查插件会打印 Vite 最终解析到的优化器选项,便于发现仍由兼容层补入的旧配置。
import { defineConfig, type Plugin } from 'vite'
function inspectOptimizer(): Plugin {
return {
name: 'inspect-optimizer',
configResolved(config) {
console.log(
'[optimizer]',
JSON.stringify(config.optimizeDeps.rolldownOptions, null, 2),
)
},
}
}
export default defineConfig({
optimizeDeps: {
rolldownOptions: {
treeshake: true,
transform: {
define: {
__DEV_TOOLS__: 'false',
},
},
output: {
minify: false,
keepNames: true,
},
},
},
plugins: [inspectOptimizer()],
})这份配置生效后,依赖优化阶段直接读取 Rolldown 选项,不再依赖 esbuildOptions 的自动转换。define 的值仍应写成可嵌入源码的字符串表达式,因此布尔值使用 'false',而不是 JavaScript 布尔量。
识别兼容层与弃用项
兼容层适合短期过渡,不适合长期保留。若仓库中同时存在 esbuildOptions 和 rolldownOptions,先删除旧项再验证,避免维护者误以为两套配置都会独立执行。
esbuild 插件对象不能默认视为 Rolldown 插件。虽然 plugins 有部分兼容支持,但涉及 onResolve、onLoad 或 esbuild 专用命名空间时,应改用 Rolldown 或 Vite 插件钩子,并为真实依赖准备回归用例。迁移也不要顺手保留已经无效的构建项,例如 Vite 8 中不再起作用的 build.commonjsOptions。
强制重建并验证
修改优化器配置后,旧缓存可能掩盖结果。使用 --force 忽略已缓存的预构建产物,并观察检查插件打印的最终配置。
npm exec vite -- --force预期输出的关键部分如下,Vite 可能额外加入内部字段,版本、耗时和端口也会因环境而不同。
[optimizer] {
"treeshake": true,
"transform": {
"define": {
"__DEV_TOOLS__": "false"
}
},
"output": {
"minify": false,
"keepNames": true
}
}
VITE v<VERSION> ready in <TIME> ms
Local: http://localhost:<PORT>/若输出仍出现从旧配置转换来的字段,继续搜索共享配置、框架封装或插件注入。若启动时报未知选项,先对照 Rolldown 的层级和类型,再检查是否把构建阶段的 build.rolldownOptions 错放进了 optimizeDeps.rolldownOptions。