Skip to content

从 v2 迁移

Node 支持

Vite 不再支持 Node v12,因为它已经进入了 EOL 阶段。现在你必须使用 Node 14.18+ 及以上版本。

现代浏览器基准线变化

生产构建打包时加会假定目标支持现代 JavaScript。默认情况下,Vite 的目标是支持 原生 ES 模块原生 ESM 动态导入 以及 import.meta 的浏览器:

  • Chrome >=87
  • Firefox >=78
  • Safari >=13
  • Edge >=88

一小部分用户需要 @vitejs/plugin-legacy,它会自动生成兼容性 chunk 以及相应的 ES 语言功能的 polyfill。

配置选项变化

架构变更和兼容选项

这一小节描述了 Vite v3 中最大的架构变更。在项目从 v2 迁移、遇到兼容性问题时,可以使用新添加的兼容选项来恢复到 Vite v2 策略。

WARNING

这些选项曾被标记为实验性,如今已经废弃。它们可能将在 v3 后续版本中被移除,因此使用它们时请固定 Vite 版本。

  • legacy.devDepsScanner
  • legacy.buildRollupPluginCommonjs
  • legacy.buildSsrCjsExternalHeuristics

开发服务器变化

Vite 的默认开发服务器端口号现在改为了 5173。你可以使用 server.port 将其设置为 3000。

Vite 的默认开发服务器主机地址现在改为了 localhost。你可以使用 server.host 将其设置为 127.0.0.1

Vite 使用 esbuild 优化了依赖关系,以将仅提供 CJS 格式的依赖转换成 ESM 格式,并减少浏览器需要请求的模块数量。在 v3 中,检索和批处理依赖的默认策略已经改变。Vite 不再使用 esbuild 预扫描用户代码,以获得冷启动时的初始依赖性列表。取而代之的是将第一次运行依赖性优化推迟到加载时每个导入的用户模块都得到处理之后。

若想要回到 v2 的策略,你可以使用 legacy.devDepsScanner

构建变化

在 v3 版本中,Vite 使用 esbuild 来默认优化依赖。这样做的效果是消除了 v2 版中存在的开发和生产环境之间最显著的差异之一。因为 esbuild 将 CJS 格式转换为了 ESM 格式,因此我们不再使用 @rollupjs/plugin-commonjs 了。

若想要回到 v2 的策略,你可以使用 legacy.buildRollupPluginCommonjs

SSR Changes

Vite v3 默认在 SSR 构建时使用 ESM 格式。当使用 ESM 时,SSR 外部化的启发式方法 将不再需要。默认情况下所有的依赖都将被外部化。你可以使用 ssr.noExternal 来控制哪些依赖需要被包含进 SSR 的打包产物中。

如果你无法在你的 SSR 项目中使用 ESM,你可以设置 ssr.format: 'cjs' 来生成一个 CJS 格式的产物。在这种情况下,会使用和 Vite v2 相同的外部化策略。

同样 build.rollupOptions.output.inlineDynamicImports 现在在 ssr.targetnode 时,也默认置为了 falseinlineDynamicImports 它会改变执行顺序,并且 node 构建不需要打包到单个文件。

其他一般性变化

  • SSR 和库模式中将会根据语法格式和包的类型,为输出的 JS 文件提供一个更合理的文件扩展名(jsmjs 或是 cjs)。
  • Terser 现在是一个可选依赖。如果你使用的是 build.minify: 'terser',你需要手动安装它:
    npm add -D terser
    

import.meta.glob

  • 原始 import.meta.glob{ assert: { type: 'raw' }} 迁移为 { as: 'raw' }

  • import.meta.glob 的 key 现在是相对与当前模块。

    // 文件:/foo/index.js
    const modules = import.meta.glob('../foo/*.js')
    
    // 转换为:
    const modules = {
    -  '../foo/bar.js': () => {}
    +  './bar.js': () => {}
    }
    
  • 当在 import.meta.glob 中使用别名(alias)时,键值总是绝对路径。

  • import.meta.globEager 已经弃用,请使用 import.meta.glob('*', { eager: true }) 来代替。

WebAssembly 支持

import init from 'example.wasm' 语法被弃用,以防止将来与 "WASM 的 ESM 集成" 冲突。

你可以使用 ?init 参数,和之前的行为类似:

-import init from 'example.wasm'
+import init from 'example.wasm?init'

-init().then((exports) => {
+init().then(({ exports }) => {
  exports.test()
})

进阶

下列改动仅会影响到插件/工具的作者:

此外,还有其他一些只影响少数用户的破坏性变化。

从 v1 迁移

在 Vite v2 文档中查看 Migration from v1 Guide中文版),了解如何将你的应用迁移到 Vite v2,然后再处理本页中所提及的变化。