从 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
的值被替换为 production
或 development
。
如果为 resolve.conditions
或 ssr.resolve.conditions
指定了自定义值,则需要更新该值以包含新条件。 例如,如果先前为 resolve.conditions
指定了 ['custom']
,那么现在就需要指定 ['custom','module','browser','develop|production']
。
JSON stringify
在 Vite 5 中,当设置 json.stringify: true
时,json.namedExports
会被禁用。
从 Vite 6 开始,即使设置了 json.stringify: true
,json.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。现在需要 tsx
或 jiti
来加载 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
文件名,则应根据软件包名称将对该文件的引用更新为新名称。例如:
{
"name": "my-lib",
"exports": {
"./style.css": "./dist/style.css"
"./style.css": "./dist/my-lib.css"
}
}
如果你更喜欢像在 Vite 5 中那样使用 style.css
,可以设置 build.lib.cssFileName: 'style'
。
进阶
还有其他一些只影响少数用户的破坏性更改。
- [#15637] fix!: default
build.cssMinify
to'esbuild'
for SSRbuild.cssMinify
现在即使是 SSR 版本也默认为启用。
- [#18070] feat!: proxy bypass with WebSocket
server.proxy[path].bypass
现在用于 WebSocket 升级请求,在这种情况下,res
参数将是undefined
。
- [#18209] refactor!: bump minimal terser version to 5.16.0
build.minify: 'terser'
所支持的最小 terser 版本从 5.4.0 提升至 5.16.0
- [#18231] chore(deps): update dependency @rollup/plugin-commonjs to v28
commonjsOptions.strictRequires
现在默认为true
(之前为'auto'
)。- 这可能会导致包的大小增大,但会使构建更加确定。
- 如果将 CommonJS 文件指定为入口点,则可能需要额外的步骤。阅读 commonjs plugin 文档 了解更多详情.
- [#18243] chore(deps)!: migrate
fast-glob
totinyglobby
- globs 中不再支持范围大括号 (
{01..03}
⇒['01', '02', '03']
) 和递增大括号 ({2..8..2}
⇒['2', '4', '6', '8']
) 。
- globs 中不再支持范围大括号 (
- [#18493] refactor!: remove fs.cachedChecks option
- 由于在缓存文件夹中写入文件并立即导入时会出现边缘情况,因此删除了这一选择优化。
从 v4 迁移
在 Vite v5 文档中查看 从 v4 迁移指南(中文版),了解如何将你的应用迁移到 Vite v5,然后再处理本页中所提及的变化。