构建选项
除非另有说明,本节中的选项仅应用于构建。
build.target
- 类型:
string | string[]
- 默认:
'baseline-widely-available'
- 相关: 浏览器兼容性
最终包的浏览器兼容性目标。默认值是一个 Vite 特殊值,'baseline-widely-available'
,它针对的是 Baseline 广泛适用于 2025-05-01 的浏览器。具体来说,它是 ['chrome107', 'edge107', 'firefox104', 'safari16']
。
另一个特殊值是 'esnext'
- 它假定原生动态导入支持,并且只会执行最小的转译。
转换是使用 esbuild 执行的,该值应该是有效的 esbuild target 选项。自定义目标可以是 ES 版本(例如 es2015
),带有版本的浏览器(例如 chrome58
),或多个目标字符串的数组。
请注意,如果代码包含 esbuild 无法安全转译的功能,则构建将失败。有关更多详细信息,请参阅 esbuild 文档。
build.modulePreload
- 类型:
boolean | { polyfill?: boolean, resolveDependencies?: ResolveModulePreloadDependenciesFn }
- 默认:
{ polyfill: true }
默认情况下,会自动注入 模块预加载 polyfill。polyfill 会自动注入到每个 index.html
入口的代理模块中。如果构建配置为通过 build.rollupOptions.input
使用非 HTML 自定义入口,则需要在您的自定义入口中手动导入 polyfill
import 'vite/modulepreload-polyfill'
注意:polyfill 不适用于 库模式。如果您需要支持没有原生动态导入的浏览器,您应该避免在您的库中使用它。
可以使用 { polyfill: false }
禁用 polyfill。
Vite 会计算每个动态导入要预加载的 chunk 列表。默认情况下,加载这些依赖项时将使用包含 base
的绝对路径。如果 base
是相对的(''
或 './'
),则在运行时使用 import.meta.url
以避免依赖于最终部署 base 的绝对路径。
使用 resolveDependencies
函数可以对依赖项列表及其路径进行细粒度控制,这是一种实验性支持。提供反馈。它需要一个 ResolveModulePreloadDependenciesFn
类型的函数
type ResolveModulePreloadDependenciesFn = (
url: string,
deps: string[],
context: {
hostId: string
hostType: 'html' | 'js'
},
) => string[]
对于每个动态导入,都会调用 resolveDependencies
函数,其中包含它所依赖的 chunk 列表,并且还会为入口 HTML 文件中导入的每个 chunk 调用该函数。可以返回一个新的依赖项数组,其中包含已过滤或注入的更多依赖项,并且它们的路径已修改。deps
路径相对于 build.outDir
。返回值应该是 build.outDir
的相对路径。
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 chunk 中导入的 CSS 将保留为 chunk,并在获取 chunk 时一起获取。
如果禁用,则整个项目中的所有 CSS 将提取到单个 CSS 文件中。
注意
如果您指定 build.lib
,则默认情况下 build.cssCodeSplit
将为 false
。
build.cssTarget
- 类型:
string | string[]
- 默认: 与
build.target
相同
此选项允许用户为 CSS 压缩设置与用于 JavaScript 转译不同的浏览器目标。
它应该只在您定位非主流浏览器时使用。一个示例是 Android WeChat WebView,它支持大多数现代 JavaScript 功能,但不支持 CSS 中的 #RGBA
十六进制颜色表示法。在这种情况下,您需要将 build.cssTarget
设置为 chrome61
,以防止 vite 将 rgba()
颜色转换为 #RGBA
十六进制表示法。
build.cssMinify
- 类型:
boolean | 'esbuild' | 'lightningcss'
- 默认: 客户端与
build.minify
相同,SSR 为'esbuild'
此选项允许用户专门覆盖 CSS 压缩,而不是默认为 build.minify
,因此您可以单独配置 JS 和 CSS 的压缩。Vite 默认使用 esbuild
来压缩 CSS。将该选项设置为 'lightningcss'
以改为使用 Lightning CSS。如果选择它,可以使用 css.lightningcss
进行配置。
build.sourcemap
- 类型:
boolean | 'inline' | 'hidden'
- 默认:
false
生成生产环境 Source Maps。如果为 true
,将创建一个单独的 sourcemap 文件。如果为 'inline'
,sourcemap 将作为 data URI 附加到结果输出文件中。'hidden'
的工作方式类似于 true
,只是会禁止在捆绑文件中显示相应的 sourcemap 注释。
build.rollupOptions
- 类型:
RollupOptions
直接自定义底层 Rollup 打包。这与可以从 Rollup 配置文件导出的选项相同,并将与 Vite 的内部 Rollup 选项合并。有关更多详细信息,请参阅 Rollup 选项文档。
build.commonjsOptions
传递给 @rollup/plugin-commonjs 的选项。
build.dynamicImportVarsOptions
传递给 @rollup/plugin-dynamic-import-vars 的选项。
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"
。
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.manifest
- 类型:
boolean | string
- 默认:
false
- 相关: 后端集成
是否生成一个 manifest 文件,其中包含非哈希静态资源文件名到其哈希版本的映射,然后服务器框架可以使用该映射来呈现正确的静态资源链接。
当该值为字符串时,它将用作相对于 build.outDir
的 manifest 文件路径。当设置为 true
时,路径将为 .vite/manifest.json
。
build.ssrManifest
- 类型:
boolean | string
- 默认:
false
- 相关: 服务器端渲染
是否生成一个 SSR manifest 文件,用于确定生产环境中的样式链接和静态资源预加载指令。
当该值为字符串时,它将用作相对于 build.outDir
的 manifest 文件路径。当设置为 true
时,路径将为 .vite/ssr-manifest.json
。
build.ssr
- 类型:
boolean | string
- 默认:
false
- 相关: 服务器端渲染
生成面向 SSR 的构建。该值可以是直接指定 SSR 入口的字符串,也可以是 true
,这需要通过 rollupOptions.input
指定 SSR 入口。
build.emitAssets
- 类型:
boolean
- 默认:
false
在非客户端构建期间,不会发出静态资源,因为假定它们将作为客户端构建的一部分发出。此选项允许框架强制在其他环境构建中发出它们。框架有责任在构建后步骤中合并静态资源。
build.ssrEmitAssets
- 类型:
boolean
- 默认:
false
在 SSR 构建期间,不会发出静态资源,因为假定它们将作为客户端构建的一部分发出。此选项允许框架强制在客户端和 SSR 构建中发出它们。框架有责任在构建后步骤中合并静态资源。一旦环境 API 稳定,此选项将被 build.emitAssets
替换。
build.minify
- 类型:
boolean | 'terser' | 'esbuild'
- 默认: 客户端构建为
'esbuild'
,SSR 构建为false
设置为 false
以禁用压缩,或指定要使用的压缩器。默认值为 esbuild,它比 terser 快 20 ~ 40 倍,压缩率仅差 1 ~ 2%。基准测试
请注意,当在库模式下使用 'es'
格式时,build.minify
选项不会压缩空格,因为它会删除 pure 注释并破坏 tree-shaking。
当设置为 'terser'
时,必须安装 Terser。
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
。如果 outDir
在根目录外部,它将发出警告,以避免意外删除重要文件。您可以显式设置此选项以禁止显示该警告。这也可以通过命令行 --emptyOutDir
获得。
build.copyPublicDir
- 类型:
boolean
- 默认:
true
默认情况下,Vite 将在构建时将文件从 publicDir
复制到 outDir
。设置为 false
可禁用此功能。
build.reportCompressedSize
- 类型:
boolean
- 默认:
true
启用/禁用 gzip 压缩大小报告。压缩大型输出文件可能很慢,因此禁用此功能可能会提高大型项目的构建性能。
build.chunkSizeWarningLimit
- 类型:
number
- 默认:
500
chunk 大小警告的限制(以 kB 为单位)。它与未压缩的 chunk 大小进行比较,因为 JavaScript 大小本身与执行时间有关。
build.watch
- 类型:
WatcherOptions
| null
- 默认:
null
设置为 {}
以启用 rollup 监视器。这主要用于涉及仅构建插件或集成过程的情况。
在 Windows Subsystem for Linux (WSL) 2 上使用 Vite
在某些情况下,文件系统监视不适用于 WSL2。有关更多详细信息,请参见 server.watch
。