前端工程化 / 系统课时

迁移 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 最终解析到的优化器选项,便于发现仍由兼容层补入的旧配置。

ts
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 忽略已缓存的预构建产物,并观察检查插件打印的最终配置。

bash
npm exec vite -- --force

预期输出的关键部分如下,Vite 可能额外加入内部字段,版本、耗时和端口也会因环境而不同。

text
[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。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

迁移 Rolldown 优化选项

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通