Skip to content

从 v5 迁移

环境 API

作为新的实验性 环境 API 的一部分,我们进行了大规模的内部重构。Vite 6 努力避免引入破坏性的变更,以确保大多数项目能够快速升级到新的主要版本。我们会等待大部分的生态系统迁移并稳定后,再开始推荐使用新的 API。可能会有一些边缘情况,但这些应该只会影响到框架和工具的底层使用。我们已经与生态系统中的维护者合作,在发布前减轻了这些差异。如果你发现了回退性问题,请 新建 issue

由于 Vite 的实现发生了改变,一些内部的 API 已经被移除了。如果你依赖于其中的某一个,那么请创建一个 feature request

Vite Runtime API

实验性的 Vite Runtime API 已经演变为模块运行器 API(Module Runner API),这是作为新的实验性 环境 API 的一部分,在 Vite 6 中发布。鉴于这个功能是实验性的,所以在 Vite 5.1 中引入的先前 API 的移除并不是一个破坏性的更改,但是用户在迁移到 Vite 6 的过程中,需要将他们的使用方式更新为与模块运行器相等的方式。

总体变化

resolve.conditions 的默认值

此更改不会影响未配置 resolve.conditions / ssr.resolve.conditions / ssr.resolve.externalConditions 的用户。

在 Vite 5 中,resolve.conditions 的默认值是 [],某些条件是内部添加的。ssr.resolve.conditions 的默认值是 resolve.conditions 的值。

从 Vite 6 开始,部分条件不再在内部添加,需要包含在配置值中。 不再在内部添加的条件为

  • resolve.conditions['module', 'browser', 'development|production']
  • ssr.resolve.conditions['module', 'node', 'development|production']

这些选项的默认值会更新为相应的值,ssr.resolve.conditions 不再使用 resolve.conditions 作为默认值。请注意,development|production是一个特殊变量,会根据 process.env.NODE_ENV 的值被替换为 productiondevelopment

如果为 resolve.conditionsssr.resolve.conditions 指定了自定义值,则需要更新该值以包含新条件。 例如,如果先前为 resolve.conditions 指定了 ['custom'],那么现在就需要指定 ['custom','module','browser','develop|production']

JSON stringify

在 Vite 5 中,当设置 json.stringify: true 时,json.namedExports 会被禁用。

从 Vite 6 开始,即使设置了 json.stringify: truejson.namedExports 也不会被禁用。如果希望实现以前的行为,可以设置 json.namedExports: false

Vite 6 还为 json.stringify 引入了一个新的默认值,即 'auto',它只会对大型 JSON 文件进行字符串化处理。要禁用此行为,请设置 json.stringify: false

在 HTML 元素中扩展对资源引用的支持

在 Vite 5 中,只有少数支持的 HTML 元素能够引用由 Vite 处理和打包的资源,如<link href><img src> 等。

Vite 6 扩展了对更多 HTML 元素的支持。完整列表请参见 HTML 功能介绍 文档。

要在某些元素上选择不进行 HTML 处理,可以在元素上添加 vite-ignore 属性。

postcss-load-config

postcss-load-config 已从 v4 更新至 v6。现在需要 tsxjiti 来加载 TypeScript postcss 配置文件,而非 ts-node。此外,现在需要 yaml 来加​​载 YAML postcss 配置文件。

Sass 现在默认使用现代 API

在 Vite 5 中,Sass 默认使用传统 API。Vite 5.4 增加了对现代 API 的支持。

从 Vite 6 开始,Sass 默认使用现代 API。如果想继续使用传统 API,可以设置 css.preprocessorOptions.sass.api: 'legacy' / css.preprocessorOptions.scss.api: 'legacy'。但请注意,传统 API 支持将在 Vite 7 中移除。

要迁移到现代 API,请参阅 Sass 文档

在 library 模式下自定义 CSS 输出文件名

在 Vite 5 中,library 模式下的 CSS 输出文件名始终是 style.css,无法通过 Vite 配置轻松更改。

从 Vite 6 开始,默认文件名将使用 package.json 中的 "name",与 JS 输出文件类似。如果 build.lib.fileName 设置为字符串,该值也将用于 CSS 输出文件名。要明确设置不同的 CSS 文件名,可以使用新的 build.lib.cssFileName 进行配置。

迁移时,如果您依赖于 style.css 文件名,则应根据软件包名称将对该文件的引用更新为新名称。例如:

package.json
json
{
  "name": "my-lib",
  "exports": {
    "./style.css": "./dist/style.css"
    "./style.css": "./dist/my-lib.css"
  }
}

如果你更喜欢像在 Vite 5 中那样使用 style.css,可以设置 build.lib.cssFileName: 'style'

进阶

还有其他一些只影响少数用户的破坏性更改。

从 v4 迁移

在 Vite v5 文档中查看 从 v4 迁移指南中文版),了解如何将你的应用迁移到 Vite v5,然后再处理本页中所提及的变化。

Released under the MIT License. (dev)