构建选项

vite-main配置参考

构建选项

除非特别说明，本节中的选项仅适用于构建。

build.target

类型： string | string[]
默认值： 'baseline-widely-available'
相关： 浏览器兼容性

最终包的浏览器兼容目标。默认值是 Vite 的特殊值 'baseline-widely-available'，它针对 Baseline Widely Available 在固定日期（本主版本为 2026-01-01）所对应的最低浏览器版本。具体来说，是 ['chrome111', 'edge111', 'firefox114', 'safari16.4', 'ios16.4']。

另一个特殊值是 'esnext'——它假定支持原生动态导入，并且只执行最小化的转译。

转换使用 Oxc Transformer 执行，该值应为有效的 Oxc Transformer 目标选项。自定义目标可以是 ES 版本（例如 es2015）、带版本的浏览器（例如 chrome58）或多个目标字符串的数组。

注意：如果代码包含无法由 Oxc 安全转译的特性，构建将输出警告。参见 Oxc 文档了解更多详情。

build.modulePreload

类型： boolean | { polyfill?: boolean, resolveDependencies?: ResolveModulePreloadDependenciesFn }
默认值： { polyfill: true }

默认情况下，会自动注入模块预加载 polyfill。该 polyfill 会被自动注入到每个 index.html 入口的代理模块中。如果构建配置为通过 build.rolldownOptions.input 使用非 HTML 自定义入口，则需要在自定义入口中手动导入这个 polyfill：

js 复制代码

import 'vite/modulepreload-polyfill'

注意：该 polyfill 不适用于库模式。如果你需要支持没有原生动态导入的浏览器，你可能应该避免在库中使用它。

可以使用 { polyfill: false } 来禁用 polyfill。

每个动态导入要预加载的块列表由 Vite 计算。默认情况下，加载这些依赖时使用包含 base 的绝对路径。如果 base 是相对路径（'' 或 './'），则在运行时使用 import.meta.url，以避免依赖最终部署 base 的绝对路径。

可以试验性地使用 resolveDependencies 函数对依赖列表及其路径进行细粒度控制。提供反馈。它期望一个 ResolveModulePreloadDependenciesFn 类型的函数：

ts 复制代码

type ResolveModulePreloadDependenciesFn = (
  url: string,
  deps: string[],
  context: {
    hostId: string
    hostType: 'html' | 'js'
  },
) => string[]

resolveDependencies 函数会针对每个动态导入及其依赖的块列表调用，也会针对入口 HTML 文件中导入的每个块调用。可以返回一个新的依赖数组，这些依赖可以被过滤或注入更多依赖，并修改它们的路径。deps 路径相对于 build.outDir。返回值应是对 build.outDir 的相对路径。

js twoslash 复制代码

/** @type {import('vite').UserConfig} */
const config = {
  // prettier-ignore
  build: {
// ---cut-before---
modulePreload: {
  resolveDependencies: (filename, deps, { hostId, hostType }) => {
    return deps.filter(condition)
  },
},
// ---cut-after---
  },
}

解析后的依赖路径可以通过 experimental.renderBuiltUrl 进一步修改。

build.polyfillModulePreload

类型： boolean
默认值： true
已弃用 使用 build.modulePreload.polyfill 代替

是否自动注入模块预加载 polyfill。

build.outDir

类型： string
默认值： dist

build.assetsDir

类型： string
默认值： assets

指定嵌套生成资源的目录（相对于 build.outDir。此选项不用于库模式）。

build.assetsInlineLimit

类型： number | ((filePath: string, content: Buffer) => boolean | undefined)
默认值： 4096（4 KiB）

小于此阈值的导入或引用资源将作为 base64 URL 内联，以避免额外的 http 请求。设置为 0 可完全禁用内联。

如果传入回调，则可以返回布尔值来选择启用或禁用。如果未返回任何内容，则应用默认逻辑。

Git LFS 占位符会自动排除内联，因为它们不包含其代表的文件的内容。

::: tip 注意
如果你指定了 build.lib，build.assetsInlineLimit 将被忽略，资源将始终内联，无论文件大小或是否为 Git LFS 占位符。

build.cssCodeSplit

类型： boolean

默认值： true

启用/禁用 CSS 代码分割。启用时，在异步 JS 块中导入的 CSS 将保留为块，并在获取该块时一同获取。

如果禁用，项目中的所有 CSS 将被提取到单个 CSS 文件中。 tip 注意
如果你指定了 build.lib，build.cssCodeSplit 默认为 false。

build.cssTarget

类型： string | string[]

默认值： 与 build.target 相同

此选项允许用户为 CSS 压缩设置与 JavaScript 转译所使用的不同浏览器目标。

当 build.cssMinify 为 'lightningcss'（默认）时，此选项在压缩步骤中优先于 css.lightningcss.targets。

它只应在目标为非主流浏览器时使用。一个例子是 Android 微信 WebView，它支持大多数现代 JavaScript 功能，但不支持 CSS 中的 #RGBA 十六进制颜色表示法。在这种情况下，你需要将 build.cssTarget 设置为 chrome61，以防止 Vite 将 rgba() 颜色转换为 #RGBA 十六进制表示法。

build.cssMinify

类型： boolean | 'lightningcss' | 'esbuild'

默认值： 'lightningcss'，但如果客户端构建的 build.minify 被禁用，则为 false

此选项允许用户专门覆盖 CSS 压缩，而不是默认使用 build.minify，因此你可以分别配置 JS 和 CSS 的压缩。Vite 默认使用 Lightning CSS 来压缩 CSS。可以通过 css.lightningcss 对其进行配置。将选项设置为 'esbuild' 以改用 esbuild。

当设置为 'esbuild' 时，必须安装 esbuild。
sh 复制代码
npm add -D esbuild
build.sourcemap

类型： boolean | 'inline' | 'hidden'

默认值： false

生成生产环境 source map。如果为 true，将创建一个单独的 sourcemap 文件。如果为 'inline'，sourcemap 将作为 data URI 附加到结果输出文件中。'hidden' 的工作方式类似于 true，但会抑制打包文件中的相应 sourcemap 注释。

build.chunkImportMap

类型： boolean

默认值： false

实验性

相关： 块导入映射优化

是否使用导入映射功能来优化块缓存效率。

注意，此选项需要 import.meta.resolve 支持。如果你需要支持旧浏览器，请查看 @vitejs/plugin-legacy。

build.rolldownOptions

类型： RolldownOptions

直接自定义底层 Rolldown 打包。这等同于可以从 Rolldown 配置文件导出的选项，并将与 Vite 内部的 Rolldown 选项合并。参见 Rolldown 选项文档了解更多详情。

建议设置顶层 input 选项，而不是 build.rolldownOptions.input，因为它在开发环境中也会被使用。如果设置了 build.rolldownOptions.input，它将仅在构建时覆盖顶层 input 选项。

build.rollupOptions

类型： RolldownOptions

已弃用

此选项是 build.rolldownOptions 选项的别名。请改用 build.rolldownOptions 选项。

build.dynamicImportVarsOptions

类型： { include?: string | RegExp | (string | RegExp)[], exclude?: string | RegExp | (string | RegExp)[] }

相关： 动态导入

是否转换带变量的动态导入。

build.lib

类型： { entry?: string | string[] | { [entryAlias: string]: string }, name?: string, formats?: ('es' | 'cjs' | 'umd' | 'iife')[], fileName?: string | ((format: ModuleFormat, entryName: string) => string), cssFileName?: string }

相关： 库模式

作为库进行构建。entry 默认为顶层 input 选项，并且必须在两者中指定一个，因为库不能使用 HTML 作为入口。name 是暴露的全局变量，当 formats 包含 'umd' 或 'iife' 时需要。默认 formats 为 ['es', 'umd']，如果使用多个入口，则为 ['es', 'cjs']。

fileName 是包文件输出的名称，默认为 package.json 中的 "name"。也可以定义为一个函数，接收 format 和 entryName 作为参数，并返回文件名。

如果你的包导入了 CSS，可以使用 cssFileName 来指定输出的 CSS 文件名称。如果 fileName 设置为字符串，则默认为与 fileName 相同，否则也回退到 package.json 中的 "name"。
js twoslash [vite.config.js] 复制代码
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    lib: {
      entry: ['src/main.js'],
      fileName: (format, entryName) => `my-lib-${entryName}.${format}.js`,
      cssFileName: 'my-lib-style',
    },
  },
})
build.license

类型： boolean | { fileName?: string }

默认值： false

相关： 许可证

设置为 true 时，构建将生成一个 .vite/license.md 文件，其中包含所有打包依赖项的许可证。

如果传入了 fileName，它将被用作相对于 outDir 的许可证文件名。如果它以 .json 结尾，将生成原始 JSON 元数据，可用于进一步处理。例如：
json 复制代码
[
  {
    "name": "dep-1",
    "version": "1.2.3",
    "identifier": "CC0-1.0",
    "text": "CC0 1.0 Universal\n\n..."
  },
  {
    "name": "dep-2",
    "version": "4.5.6",
    "identifier": "MIT",
    "text": "MIT License\n\n..."
  }
]
``` tip

如果你想在构建后的代码中引用许可证文件，可以使用 build.rolldownOptions.output.postBanner 在文件顶部注入注释。例如：

js twoslash [vite.config.js] 复制代码

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    license: true,
    rolldownOptions: {
      output: {
        postBanner:
          '/* See licenses of bundled dependencies at https://example.com/license.md */',
      },
    },
  },
})

build.manifest

类型： boolean | string

默认值： false

相关： 后端集成

是否生成 manifest 文件，其中包含未哈希的资源文件名到其哈希版本的映射，服务器框架可以用它来渲染正确的资源链接。

当值为字符串时，它将用作相对于 build.outDir 的 manifest 文件路径。当设置为 true 时，路径为 .vite/manifest.json。

如果你正在编写插件，并需要在构建期间检查每个输出块或资源的关联 CSS 和静态资源，你也可以使用 viteMetadata 输出包元数据 API。

build.ssrManifest

类型： boolean | string

默认值： false

相关： 服务端渲染

是否生成 SSR manifest 文件，用于在生产环境中确定样式链接和资源预加载指令。

当值为字符串时，它将用作相对于 build.outDir 的 manifest 文件路径。当设置为 true 时，路径为 .vite/ssr-manifest.json。

build.ssr

类型： boolean | string

默认值： false

相关： 服务端渲染

生成面向 SSR 的构建。该值可以是字符串以直接指定 SSR 入口，或者 true，此时需要通过 input 或 build.rolldownOptions.input 指定 SSR 入口。

build.emitAssets

类型： boolean

默认值： false

在非客户端构建期间，静态资源不会被发出，因为假定它们会作为客户端构建的一部分被发出。此选项允许框架强制在其他环境构建中发出它们。框架有责任通过构建后步骤合并资源。

build.ssrEmitAssets

类型： boolean

默认值： false

在 SSR 构建期间，静态资源不会被发出，因为假定它们会作为客户端构建的一部分被发出。此选项允许框架强制在客户端和 SSR 构建中都发出它们。框架有责任通过构建后步骤合并资源。一旦 Environment API 稳定，此选项将被 build.emitAssets 取代。

build.minify

类型： boolean | 'oxc' | 'terser' | 'esbuild'

默认值： 客户端构建为 'oxc'，SSR 构建为 false

设置为 false 以禁用压缩，或指定要使用的压缩器。默认是 Oxc Minifier，它比 terser 快 30 ~ 90 倍，且压缩率仅差 0.5 ~ 2%。基准测试

build.minify: 'esbuild' 已弃用，将在未来移除。

注意：在库模式下使用 'es' 格式时，build.minify 选项不会压缩空白，因为它会移除纯注释并破坏 tree-shaking。

当设置为 'esbuild' 或 'terser' 时，必须分别安装 esbuild 或 Terser。
sh 复制代码
npm add -D esbuild
npm add -D terser
build.terserOptions

类型： TerserOptions

要传给 Terser 的附加压缩选项。

此外，你还可以传入 maxWorkers: number 选项来指定要生成的最大工作线程数。默认为 CPU 数量减 1。

build.write

类型： boolean

默认值： true

设置为 false 以禁用将打包结果写入磁盘。这主要用于编程式 build() 调用，在写入磁盘前需要对打包结果进行进一步后处理。

build.emptyOutDir

类型： boolean

默认值： 如果 outDir 在 root 内，则为 true

默认情况下，如果 outDir 在项目根目录内，Vite 会在构建时清空它。如果 outDir 在根目录之外，会发出警告，以避免意外删除重要文件。你可以显式设置此选项来抑制警告。也可以通过命令行使用 --emptyOutDir。

build.copyPublicDir

类型： boolean

默认值： true

默认情况下，Vite 会在构建时将 publicDir 中的文件复制到 outDir。设置为 false 可禁用此行为。

build.reportCompressedSize

类型： boolean

默认值： true

启用/禁用 gzip 压缩大小报告。压缩大型输出文件可能很慢，因此对于大型项目，禁用此功能可能会提高构建性能。

build.chunkSizeWarningLimit

类型： number

默认值： 500

块大小警告的限制（以 kB 为单位）。它与未压缩的块大小进行比较，因为 JavaScript 大小本身与执行时间相关。

build.watch

类型： WatcherOptions| null

默认值： null

设置为 {} 以启用 Rolldown watcher。这主要用于涉及仅构建插件或集成进程的情况。 warning 在适用于 Linux 的 Windows 子系统 (WSL2) 上使用 Vite

在某些情况下，文件系统监视在 WSL2 中无法工作。
参见 server.watch 了解更多详情。

:::

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。