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

配置选项变化 ¶

下列在 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。在 Vite v2，Vite 默认监听的是 127.0.0.1。Node.js 在 v17 版本以下通常会解析 localhost 到 127.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.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()
})

自动生成 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: [] } 来移除。

进阶 ¶

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

[#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 强制杀进程。

从 v1 迁移 ¶

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