从 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。

配置选项变化 ¶

• 下列在 v2 当中我们已经标记为弃用选项，现在已经被移除：

  • alias（改为了 resolve.alias）
  • dedupe（改为了 resolve.dedupe）
  • build.base（改为了 base）
  • build.brotliSize（改为了 build.reportCompressedSize）
  • build.cleanCssOptions（Vite 现在使用 esbuild 来做 CSS 最小化压缩）
  • build.polyfillDynamicImport（在没有支持动态导入的浏览器中，使用 @vitejs/plugin-legacy）
  • optimizeDeps.keepNames（改为了 optimizeDeps.esbuildOptions.keepNames）

架构变更和兼容选项 ¶

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

开发服务器变化 ¶

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.target 是 node 时，也默认置为了 false。inlineDynamicImports 它会改变执行顺序，并且 node 构建不需要打包到单个文件。

其他一般性变化 ¶

• SSR 和库模式中将会根据语法格式和包的类型，为输出的 JS 文件提供一个更合理的文件扩展名（js、mjs 或是 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()
})

进阶 ¶

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

• [#5868] refactor: remove deprecated api for 3.0
  • printHttpServerUrls 被移除
  • server.app、server.transformWithEsbuild 被移除
  • import.meta.hot.acceptDeps 被移除
• [#6901] fix: sequential injection of tags in transformIndexHtml
  • transformIndexHtml 现在会从更早的插件处获取到正确的内容，因此，现在注入的标签的顺序与预期的一样。
• [#7995] chore: do not fixStacktrace
  • ssrLoadModule 的 fixStacktrace 选项现在默认为 false
• [#8178] feat!: migrate to ESM
  • formatPostcssSourceMap 现在是异步的
  • resolvePackageEntry、resolvePackageData 在 CJS 构建中将不再可用（需要在 CJS 中使用动态导入）
• [#8626] refactor: type client maps
  • import.meta.hot.accept 的回调函数类型现在更严格了。现在是 (mod: (Record<string, any> & { [Symbol.toStringTag]: 'Module' }) | undefined) => void（之前是 (mod: any) => void）。

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

• [#5018] feat: enable generatedCode: 'es2015' for rollup build
  • 转义到 ES5 现在是必要的，即使用户代码仅含 ES5。
• [#7877] fix: vite client types
  • /// <reference lib="dom" /> 已从 vite/client.d.ts 中移除。必须在 tsconfig.json 使用 { "lib": ["dom"] } 或 { "lib": ["webworker"] }。
• [#8090] feat: preserve process env vars in lib build
  • process.env.* 现在在库模式下是被保留的了。
• [#8280] feat: non-blocking esbuild optimization at build time
  • server.force 选项现已移除，改为了直接的 force 选项。
• [#8550] fix: dont handle sigterm in middleware mode
  • 当以中间件模式运行时，Vite 不再在 SIGTERM 强制杀进程。
• [#8647] feat: print resolved address for localhost
  • server.printUrls 和 previewServer.printUrls 现在是异步的了。

从 v1 迁移 ¶

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