Vite
ViteConf Logo

携手共建

ViteConf 2025

观看回放

从 v7 迁移 ​

如果您是从 rolldown-vite（Rolldown 集成 Vite 的技术预览版，适用于 v6 和 v7）进行迁移，则仅标题中带有 NRV 的部分适用。

默认浏览器目标变更 NRV ​

build.target 和 'baseline-widely-available' 的默认浏览器值已更新为更新的浏览器版本

  • Chrome 107 → 111
  • Edge 107 → 111
  • Firefox 104 → 114
  • Safari 16.0 → 16.4

这些浏览器版本与截至 2026-01-01 的 基准广泛可用 (Baseline Widely Available) 功能集一致。换句话说，它们都是在大约两年半前发布的。

Rolldown ​

Vite 8 使用基于 Rolldown 和 Oxc 的工具，而不是 esbuild 和 Rollup。

渐进式迁移 ​

rolldown-vite 包在 Vite 7 中实现了 Rolldown，但不包含其他 Vite 8 的更改。这可以用作迁移到 Vite 8 的中间步骤。请参阅 Vite 7 文档中的 Rolldown 集成指南，以从 Vite 7 切换到 rolldown-vite。

对于从 rolldown-vite 迁移到 Vite 8 的用户，您可以撤销 package.json 中的依赖项更改并更新到 Vite 8

json
{
  "devDependencies": {
    "vite": "npm:rolldown-vite@7.2.2"
    "vite": "^8.0.0"
  }
}

依赖项优化器现在使用 Rolldown ​

Rolldown 现在用于依赖项优化，而不是 esbuild。为了向后兼容，Vite 仍然支持 optimizeDeps.esbuildOptions，并会自动将其转换为 optimizeDeps.rolldownOptions。optimizeDeps.esbuildOptions 现已被弃用，将来会被移除，我们建议您迁移到 optimizeDeps.rolldownOptions。

以下选项会自动转换

您可以从 configResolved 钩子获取由兼容层设置的选项

js
const plugin = {
  name: 'log-config',
  configResolved(config) {
    console.log('options', config.optimizeDeps.rolldownOptions)
  },
},

由 Oxc 进行的 JavaScript 转换 ​

Oxc 现在用于 JavaScript 转换，而不是 esbuild。为了向后兼容，Vite 仍然支持 esbuild 选项，并会自动将其转换为 oxc。esbuild 现已被弃用，将来会被移除，我们建议您迁移到 oxc。

以下选项会自动转换

Oxc 不支持 esbuild.supported 选项。如果您需要此选项，请参阅 oxc-project/oxc#15373。

您可以从 configResolved 钩子获取由兼容层设置的选项

js
const plugin = {
  name: 'log-config',
  configResolved(config) {
    console.log('options', config.oxc)
  },
},

目前，Oxc 转换器不支持降级原生装饰器（native decorators），因为我们正在等待规范的进展，请参阅 (oxc-project/oxc#9170)。

降级原生装饰器的变通方法

您可以暂时使用 Babel 或 SWC 来降级原生装饰器。虽然 SWC 比 Babel 快，但它不支持 esbuild 所支持的最新装饰器规范。

装饰器规范在达到 stage 3 后已经更新了多次。每个工具支持的版本如下：

  • "2023-11" (esbuild、TypeScript 5.4+ 和 Babel 支持此版本)
  • "2023-05" (TypeScript 5.2+ 支持此版本)
  • "2023-01" (TypeScript 5.0+ 支持此版本)
  • "2022-03" (SWC 支持此版本)

请参阅 Babel 装饰器版本指南，了解各版本之间的差异。

使用 Babel

bash
$ npm install -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
bash
$ yarn add -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
bash
$ pnpm add -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
bash
$ bun add -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
bash
$ deno add -D npm:@rolldown/plugin-babel npm:@babel/plugin-proposal-decorators
vite.config.ts
ts
import { defineConfig } from 'vite'
import babel from '@rolldown/plugin-babel'

function decoratorPreset(options: Record<string, unknown>) {
  return {
    preset: () => ({
      plugins: [['@babel/plugin-proposal-decorators', options]],
    }),
    rolldown: {
      // Only run this transform if the file contains a decorator.
      filter: {
        code: '@',
      },
    },
  }
}

export default defineConfig({
  plugins: [babel({ presets: [decoratorPreset({ version: '2023-11' })] })],
})

使用 SWC

bash
$ npm install -D @rollup/plugin-swc @swc/core
bash
$ yarn add -D @rollup/plugin-swc @swc/core
bash
$ pnpm add -D @rollup/plugin-swc @swc/core
bash
$ bun add -D @rollup/plugin-swc @swc/core
bash
$ deno add -D npm:@rollup/plugin-swc npm:@swc/core
js
import { defineConfig, withFilter } from 'vite'

export default defineConfig({
  // ...
  plugins: [
    withFilter(
      swc({
        swc: {
          jsc: {
            parser: { decorators: true, decoratorsBeforeExport: true },
            // NOTE: SWC doesn't support the '2023-11' version yet.
            transform: { decoratorVersion: '2022-03' },
          },
        },
      }),
      // Only run this transform if the file contains a decorator.
      { transform: { code: '@' } },
    ),
  ],
})

esbuild 后备方案 ​

esbuild 不再被 Vite 直接使用，现在是一个可选依赖项。如果您使用的插件调用了 transformWithEsbuild 函数，您需要将 esbuild 安装为 devDependency。transformWithEsbuild 函数已被弃用，将来会被移除。我们建议改为迁移到新的 transformWithOxc 函数。

由 Oxc 进行的 JavaScript 压缩 ​

Oxc Minifier 现在用于 JavaScript 压缩，而不是 esbuild。您可以使用已弃用的 build.minify: 'esbuild' 选项切换回 esbuild。此配置选项将来会被移除，并且您需要将 esbuild 安装为 devDependency，因为 Vite 不再直接依赖 esbuild。

如果您过去使用 esbuild.minify* 选项来控制压缩行为，现在可以使用 build.rolldownOptions.output.minify 代替。如果您过去使用 esbuild.drop 选项，现在可以使用 build.rolldownOptions.output.minify.compress.drop* 选项。

属性混淆（Property mangling）及其相关选项（mangleProps, reserveProps, mangleQuoted, mangleCache）不受 Oxc 支持。如果您需要这些选项，请参阅 oxc-project/oxc#15375。

esbuild 和 Oxc Minifier 对源代码的假设略有不同。如果您怀疑压缩器导致代码损坏，可以在此处对比这些假设：

如果您发现 JavaScript 应用在压缩方面有任何问题，请务必报告。

由 Lightning CSS 进行的 CSS 压缩 ​

Lightning CSS 现在默认用于 CSS 压缩。您可以使用 build.cssMinify: 'esbuild' 选项切换回 esbuild。请注意，您需要安装 esbuild 作为 devDependency。

Lightning CSS 支持更好的语法降级，您的 CSS 包体积可能会略有增加。

一致的 CommonJS 互操作性 ​

现在，从 CommonJS (CJS) 模块进行的 default 导入以一致的方式处理。

如果满足以下任一条件，default 导入即为所导入 CJS 模块的 module.exports 值。否则，default 导入为所导入 CJS 模块的 module.exports.default 值：

  • 导入者是 .mjs 或 .mts 文件。
  • 导入者最近的 package.json 中 type 字段设置为 module。
  • 所导入 CJS 模块的 module.exports.__esModule 值未设置为 true。
之前的行为

在开发环境下，如果满足以下任一条件，default 导入为所导入 CJS 模块的 module.exports 值。否则，default 导入为所导入 CJS 模块的 module.exports.default 值：

  • 导入者被包含在依赖项优化中且为 .mjs 或 .mts 文件。
  • 导入者被包含在依赖项优化中且导入者最近的 package.json 中 type 字段设置为 module。
  • 所导入 CJS 模块的 module.exports.__esModule 值未设置为 true。

在构建环境下，条件为：

  • 所导入 CJS 模块的 module.exports.__esModule 值未设置为 true。
  • module.exports 的 default 属性不存在.

(假设 build.commonjsOptions.defaultIsModuleExports 未从默认值 'auto' 修改)

有关此问题的更多详细信息，请参阅 Rolldown 文档：Ambiguous default import from CJS modules - Bundling CJS | Rolldown。

此更改可能会破坏某些导入 CJS 模块的现有代码。您可以使用已弃用的 legacy.inconsistentCjsInterop: true 选项暂时恢复之前的行为。如果您发现有受此更改影响的包，请向包作者报告或提交 Pull Request。请确保链接到上面的 Rolldown 文档，以便作者了解上下文。

移除了使用格式嗅探的模块解析 ​

当 package.json 中同时存在 browser 和 module 字段时，Vite 过去会根据文件内容解析字段，并为浏览器选择 ESM 文件。引入此机制是因为一些包使用 module 字段指向 Node.js 的 ESM 文件，而另一些包使用 browser 字段指向浏览器的 UMD 文件。鉴于现代 exports 字段解决了此问题并已被许多包采用，Vite 不再使用此启发式方法，始终遵循 resolve.mainFields 选项的顺序。如果您依赖于此行为，可以使用 resolve.alias 选项将该字段映射到所需文件，或使用包管理器打补丁（例如 patch-package, pnpm patch）。

外部化模块的 Require 调用 ​

外部化模块的 require 调用现在保留为 require 调用，而不会转换为 import 语句。这是为了保留 require 调用的语义。如果您想将它们转换为 import 语句，可以使用 Rolldown 内置的 esmExternalRequirePlugin（从 vite 中重新导出）。

js
import { defineConfig, esmExternalRequirePlugin } from 'vite'

export default defineConfig({
  // ...
  plugins: [
    esmExternalRequirePlugin({
      external: ['react', 'vue', /^node:/],
    }),
  ],
})

有关详细信息，请参阅 Rolldown 文档：require external modules - Bundling CJS | Rolldown。

UMD / IIFE 中的 import.meta.url ​

import.meta.url 不再在 UMD / IIFE 输出格式中被 polyfill。默认情况下，它将被替换为 undefined。如果您更喜欢之前的行为，可以使用 define 选项配合 build.rolldownOptions.output.intro 选项。有关详细信息，请参阅 Rolldown 文档：Well-known import.meta properties - Non ESM Output Formats | Rolldown。

移除了 build.rollupOptions.watch.chokidar 选项 ​

build.rollupOptions.watch.chokidar 选项已被移除。请迁移到 build.rolldownOptions.watch.watcher 选项。

移除了对象形式的 build.rollupOptions.output.manualChunks 并弃用了函数形式 ​

对象形式的 output.manualChunks 选项不再支持。函数形式的 output.manualChunks 已被弃用。Rolldown 拥有更灵活的 codeSplitting 选项。有关 codeSplitting 的详细信息，请参阅 Rolldown 文档：Manual Code Splitting - Rolldown。

build() 抛出 BundleError ​

此更改仅影响 JS API 用户。

build() 现在抛出 BundleError，而不是插件中抛出的原始错误。BundleError 的类型定义为 Error & { errors?: RolldownError[] }，它将各个错误包装在一个 errors 数组中。如果您需要获取具体的单个错误，需要访问 .errors。

js
try {
  await build()
} catch (e) {
  if (e.errors) {
    for (const error of e.errors) {
      console.log(error.code) // error code
    }
  }
}

模块类型支持和自动检测 ​

此更改仅影响插件作者。

Rolldown 对 模块类型 (Module types) 提供了实验性支持，类似于 esbuild 的 loader 选项。因此，Rolldown 会根据解析出的 ID 扩展名自动设置模块类型。如果您在 load 或 transform 钩子中将内容转换为 JavaScript，您可能需要向返回值添加 moduleType: 'js'。

js
const plugin = {
  name: 'txt-loader',
  load(id) {
    if (id.endsWith('.txt')) {
      const content = fs.readFile(id, 'utf-8')
      return {
        code: `export default ${JSON.stringify(content)}`,
        moduleType: 'js', 
      }
    }
  },
}

以下选项已弃用，将来会被移除：

  • build.rollupOptions：更名为 build.rolldownOptions
  • worker.rollupOptions：更名为 worker.rolldownOptions
  • build.commonjsOptions：现已无效 (no-op)
  • build.dynamicImportVarsOptions.warnOnError：现已无效 (no-op)
  • resolve.alias[].customResolver：改为使用带有 resolveId 钩子且设置 enforce: 'pre' 的自定义插件

移除了已弃用的功能 NRV ​

  • 不再支持将 URL 传递给 import.meta.hot.accept。请改为传递 id。（#21382）

进阶 ​

预计这些破坏性更改只会影响少数用例

  • Extglobs 尚不支持（rolldown-vite#365）
  • TypeScript 遗留命名空间（legacy namespace）仅部分支持。有关详细信息，请参阅 Oxc Transformer 相关文档。
  • define 不共享对象的引用：当您将对象作为值传递给 define 时，每个变量都将拥有该对象的独立副本。有关详细信息，请参阅 Oxc Transformer 相关文档。
  • bundle 对象变更（bundle 是传递给 generateBundle / writeBundle 钩子的对象，也是 build 函数返回的对象）
    • 不支持赋值给 bundle[foo]。Rollup 也不建议这样做。请改为使用 this.emitFile()。
    • 引用在钩子之间不共享（rolldown-vite#410）
    • structuredClone(bundle) 会报错 DataCloneError: #<Object> could not be cloned。此操作不再支持。请使用 structuredClone({ ...bundle }) 进行克隆。（rolldown-vite#128）
  • Rollup 中的所有并行钩子现在都作为顺序钩子执行。有关详细信息，请参阅 Rolldown 文档。
  • "use strict"; 有时不会被注入。有关详细信息，请参阅 Rolldown 文档。
  • 不支持通过 plugin-legacy 转换为 ES5 及以下版本（rolldown-vite#452）
  • 向 build.target 选项传递同一个浏览器的多个版本现在会报错：esbuild 会选择该浏览器的最新版本，这很可能不是您的本意。
  • Rolldown 不支持：以下功能不受 Rolldown 支持，因此 Vite 也不再支持。
  • parseAst / parseAstAsync 函数现已被弃用，取而代之的是功能更强的 parseSync / parse 函数。

从 v6 迁移 ​

请先查看 Vite v7 文档中的 从 v6 迁移指南，了解将应用移植到 Vite 7 所需的更改，然后再继续进行此页面上的更改。

© 2019-至今 VoidZero Inc. 和 Vite 贡献者。(b59265c8)