Skip to content

从 v2 迁移

Node 支持

Vite 不再支持 Node 12 / 13 / 15,因为上述版本已经进入了 EOL 阶段。现在你必须使用 Node 14.18+ / 16+ 版本。

现代浏览器基准线变化

生产构建打包时会假定目标支持现代 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 策略。

开发服务器变化

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

Vite 的默认开发服务器主机地址现在改为了 localhost。在 Vite v2,Vite 默认监听的是 127.0.0.1。Node.js 在 v17 版本以下通常会解析 localhost127.0.0.1,因此对这些版本,主机地址并未变更。若明确需要,对于 Node.js v17 版本以上,你可以使用 server.host、将其设置为 127.0.0.1

请注意,现在 Vite v3 会打印出正确的主机地址。这意味着使用 localhost 时 Vite 可能会打印 127.0.0.1 作为正在监听的地址。你可以设置 dns.setDefaultResultOrder('verbatim') 来避免这一表现。查看 server.host 了解详情。

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()
})

自动生成 https 证书

当使用 https 时需要一个合法可用的证书。在 Vite v2 中,如果没有配置证书,Vite 会自动生成和缓存一个自签名的证书。 从 Vite v3 开始,我们推荐手动创建你自己的证书。如果你仍想要使用 v2 中的自动生成,该功能可以通过添加 @vitejs/plugin-basic-ssl 到项目插件中来实现。

import basicSsl from '@vitejs/plugin-basic-ssl'

export default {
  plugins: [basicSsl()]
}

实验性

在构建阶段使用 esbuild 依赖优化

在 v3 版本下,Vite 允许在构建阶段使用 esbuild 进行依赖优化。如果开启此项,那么它将消除 v2 版本中存在的最明显的开发与构建最终产物之间的区别。@rollupjs/plugin-commonjs 在此处不再需要,因为 esbuild 会将纯 CommonJS 依赖转换为 ESM。

如果你想尝试该构建策略,你可以使用 optimizeDeps.disabled: false(在 v3 中默认是 disabled: 'build')。@rollup/plugin-commonjs 可以通过设置 build.commonjsOptions: { include: [] } 来移除。

进阶

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

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

从 v1 迁移

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