Vite
ViteConf Logo

携手共建

ViteConf 2025

观看回放

构建选项 ​

除非另有说明，本节中的选项仅应用于构建。

build.target ​

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

最终产物的浏览器兼容性目标。默认值是一个特殊的 Vite 值 'baseline-widely-available'，它以 2026-01-01 广泛支持的 Baseline 浏览器为目标。具体而言，它是 ['chrome111', 'edge111', 'firefox114', 'safari16.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.rollupOptions.input 使用非 HTML 自定义入口，则需要在你的自定义入口中手动导入该 Polyfill。

js
import 'vite/modulepreload-polyfill'

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

可以使用 { polyfill: false } 禁用该 Polyfill。

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

目前提供实验性支持，可通过 resolveDependencies 函数对依赖列表及其路径进行细粒度控制。提供反馈。它需要一个类型为 ResolveModulePreloadDependenciesFn 的函数。

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

resolveDependencies 函数将为每个动态导入调用一次（传入其依赖的块列表），也会为入口 HTML 文件中导入的每个块调用一次。可以返回一个新的依赖数组，用于过滤、注入更多依赖或修改它们的路径。deps 路径相对于 build.outDir。返回值应为相对于 build.outDir 的路径。

js
modulePreload
: {
  
resolveDependencies
: (
filename
, 
deps
, { 
hostId
, 
hostType
 }) => {
    return 
deps
.
filter
(condition)
  },
},

解析后的依赖路径可以使用 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 占位符会自动排除在内联之外，因为它们不包含所代表文件的实际内容。

注意

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

build.cssCodeSplit ​

  • 类型： boolean
  • 默认值： true

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

如果禁用，整个项目中的所有 CSS 将被提取到一个单一的 CSS 文件中。

注意

如果你指定了 build.lib，build.cssCodeSplit 默认为 false。

build.cssTarget ​

  • 类型： string | string[]
  • 默认： 与 build.target 相同

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

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

build.cssMinify ​

  • 类型： boolean | 'lightningcss' | 'esbuild'
  • 默认： 客户端构建与 build.minify 相同，SSR 构建默认为 'lightningcss'

此选项允许用户明确覆盖 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

生成生产环境的源码映射文件。如果设为 true，将创建一个单独的 sourcemap 文件。如果设为 'inline'，sourcemap 将作为数据 URI 追加到输出文件中。'hidden' 的作用与 true 类似，但会禁止打包文件中相应的 sourcemap 注释。

build.rolldownOptions ​

直接自定义底层的 Rolldown 打包配置。这与从 Rolldown 配置文件中导出的选项相同，并将与 Vite 的内部 Rolldown 选项合并。更多详情请参阅 Rolldown 选项文档。

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，因为库不能使用 HTML 作为入口。name 是暴露的全局变量，当 formats 包含 'umd' 或 'iife' 时是必需的。默认 formats 为 ['es', 'umd']，如果使用多个入口，则为 ['es', 'cjs']。

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

如果你的包导入了 CSS，可以使用 cssFileName 来指定输出的 CSS 文件名。如果它是字符串，默认值与 fileName 相同，否则它也会回退到 package.json 中的 "name"。

vite.config.js
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
  • 相关： License

设置为 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..."
  }
]

提示

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

vite.config.js
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
  • 相关： 后端集成

是否生成一个包含非哈希资源文件名与其对应哈希版本映射的清单文件，该文件可供服务端框架用于渲染正确的资源链接。

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

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

build.ssrManifest ​

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

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

build.ssr ​

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

build.emitAssets ​

  • 类型： boolean
  • 默认值： false

在非客户端构建期间，静态资源不会被输出，因为假设它们将作为客户端构建的一部分输出。此选项允许框架在其他环境构建中强制输出它们。由框架负责在构建后合并这些资源。

build.ssrEmitAssets ​

  • 类型： boolean
  • 默认值： false

在 SSR 构建期间，静态资源不会被输出，因为假设它们将作为客户端构建的一部分输出。此选项允许框架强制在客户端和 SSR 构建中都输出它们。由框架负责在构建后合并这些资源。一旦环境 API (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

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

build.copyPublicDir ​

  • 类型： boolean
  • 默认值： true

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

build.reportCompressedSize ​

  • 类型： boolean
  • 默认值： true

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

build.chunkSizeWarningLimit ​

  • 类型： number
  • 默认： 500

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

build.watch ​

设置为 {} 以启用 rollup 监听器。这主要用于涉及仅构建插件或集成流程的情况。

在 Windows Linux 子系统 (WSL) 2 上使用 Vite

在某些情况下，文件系统监听在 WSL2 上无法工作。详见 server.watch。

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