从 v5 迁移

环境 API

作为新的实验性 环境 API 的一部分，需要进行大量的内部重构。Vite 6 努力避免重大更改，以确保大多数项目能够快速升级到新的主要版本。我们将等待生态系统的大部分迁移完成，然后再稳定下来并开始推荐使用新的 API。可能会有一些极端情况，但这些情况只会影响框架和工具的低级用法。我们在发布之前已经与生态系统中的维护者合作，以减轻这些差异。如果您发现任何回归，请 提交问题。

由于 Vite 的实现发生了变化，一些内部 API 已被移除。如果您依赖其中一个，请创建一个 功能请求。

Vite 运行时 API

实验性的 Vite 运行时 API 已发展为模块运行器 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。这些默认值从 vite 导出为 defaultClientConditions 和 defaultServerConditions。

如果您为 resolve.conditions 或 ssr.resolve.conditions 指定了自定义值，则需要将其更新为包含新条件。例如，如果您之前为 resolve.conditions 指定了 ['custom']，则需要改为指定 ['custom', ...defaultClientConditions]。

JSON 字符串化

在 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 中，默认情况下使用旧版 API。Vite 5.4 添加了对现代 API 的支持。

从 Vite 6 开始，默认情况下使用现代 API。如果您希望继续使用旧版 API，可以设置 css.preprocessorOptions.sass.api: 'legacy' / css.preprocessorOptions.scss.api: 'legacy'。但请注意，旧版 API 支持将在 Vite 7 中移除。

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

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

在 Vite 5 中，库模式下的 CSS 输出文件名始终为 style.css，并且无法通过 Vite 配置轻松更改。

从 Vite 6 开始，默认文件名现在使用 package.json 中的 "name"，类似于 JS 输出文件。如果使用字符串设置 build.lib.fileName，则该值也将用于 CSS 输出文件名。要显式设置不同的 CSS 文件名，可以使用新的 build.lib.cssFileName 来配置它。

要迁移，如果您依赖 style.css 文件名，则应根据您的包名称将其引用更新为新名称。例如

package.json

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

如果您希望像在 Vite 5 中一样坚持使用 style.css，则可以改为设置 build.lib.cssFileName: 'style'。

高级

还有一些其他重大更改，只会影响少数用户。

• [#17922] fix(css)!: 移除 ssr 开发模式中的默认导入

  • 对 CSS 文件的默认导入的支持在 Vite 4 中已弃用并在 Vite 5 中移除，但在 SSR 开发模式中仍意外地得到支持。此支持现已移除。

• [#15637] fix!: 将 SSR 的默认 build.cssMinify 设置为 'esbuild'

  • build.cssMinify 现在默认启用，即使对于 SSR 构建也是如此。

• [#18070] feat!: 使用 WebSocket 进行代理绕过

  • server.proxy[path].bypass 现在被用于 WebSocket 升级请求，在这种情况下，res 参数将为 undefined。

• [#18209] refactor!: 将最小 terser 版本提升到 5.16.0

  • 对于 build.minify: 'terser'，最小支持的 terser 版本已从 5.4.0 提升到 5.16.0。

• [#18231] chore(deps): 更新依赖项 @rollup/plugin-commonjs 到 v28

  • commonjsOptions.strictRequires 现在默认为 true（之前为 'auto'）。
    • 这可能会导致更大的包体积，但会使构建结果更具确定性。
    • 如果您将 CommonJS 文件指定为入口点，则可能需要额外的步骤。阅读commonjs 插件文档以获取更多详细信息。

• [#18243] chore(deps)!: 将 fast-glob 迁移到 tinyglobby

  • 范围大括号 ({01..03} ⇒ ['01', '02', '03']) 和增量大括号 ({2..8..2} ⇒ ['2', '4', '6', '8']) 不再支持在 glob 中使用。

• [#18395] feat(resolve)!: 允许移除条件

  • 此 PR 不仅引入了上面提到的“resolve.conditions 的默认值”的重大更改，还使 resolve.mainFields 不再用于 SSR 中的非外部化依赖项。如果您正在使用 resolve.mainFields 并希望将其应用于 SSR 中的非外部化依赖项，则可以使用ssr.resolve.mainFields。

• [#18493] refactor!: 删除 fs.cachedChecks 选项

  • 此可选优化已删除，因为在将文件写入缓存文件夹并立即导入它时存在边缘情况。

• [#18697] fix(deps)!: 将依赖项 dotenv-expand 更新到 v12

  • 现在，在插值之前应声明用于插值的变量。有关更多详细信息，请参阅dotenv-expand 的变更日志。

• [#16471] feat: v6 - 环境 API

  • 对仅 SSR 模块的更新不再触发客户端的完整页面重新加载。要恢复到之前的行为，可以使用自定义 Vite 插件。

    点击展开示例

    import type { Plugin, EnvironmentModuleNode } from 'vite'
    
    function hmrReload(): Plugin {
      return {
        name: 'hmr-reload',
        enforce: 'post',
        hotUpdate: {
          order: 'post',
          handler({ modules, server, timestamp }) {
            if (this.environment.name !== 'ssr') return
    
            let hasSsrOnlyModules = false
    
            const invalidatedModules = new Set<EnvironmentModuleNode>()
            for (const mod of modules) {
              if (mod.id == null) continue
              const clientModule =
                server.environments.client.moduleGraph.getModuleById(mod.id)
              if (clientModule != null) continue
    
              this.environment.moduleGraph.invalidateModule(
                mod,
                invalidatedModules,
                timestamp,
                true,
              )
              hasSsrOnlyModules = true
            }
    
            if (hasSsrOnlyModules) {
              server.ws.send({ type: 'full-reload' })
              return []
            }
          },
        },
      }
    }

从 v4 迁移

首先查看 Vite v5 文档中的从 v4 迁移指南，以了解将您的应用程序移植到 Vite 5 所需的更改，然后继续执行此页面上的更改。