构建选项

build.target

• 类型： string | string[]
• 默认值： 'modules'
• 相关： 浏览器兼容性

最终捆绑包的浏览器兼容性目标。默认值为 Vite 特殊值 'modules'，它针对支持 原生 ES 模块、原生 ESM 动态导入 和 import.meta 的浏览器。Vite 将把 'modules' 替换为 ['es2020', 'edge88', 'firefox78', 'chrome87', 'safari14']

另一个特殊值是 'esnext' - 它假设支持原生动态导入，并将尽可能少地进行转译。

• 如果 build.minify 选项为 'terser' 且安装的 Terser 版本低于 5.16.0，则 'esnext' 将强制降级为 'es2021'。
• 在其他情况下，它将完全不执行转译。

转译使用 esbuild 执行，该值应为有效的 esbuild 目标选项。自定义目标可以是 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 计算。默认情况下，加载这些依赖项时将使用包含 base 的绝对路径。如果 base 是相对的（'' 或 './'），则在运行时使用 import.meta.url 来避免依赖于最终部署基址的绝对路径。

使用 resolveDependencies 函数对依赖项列表及其路径进行细粒度控制存在实验性支持。提供反馈。它期望一个类型为 ResolveModulePreloadDependenciesFn 的函数。

type ResolveModulePreloadDependenciesFn = (
  url: string,
  deps: string[],
  context: {
    importer: string
  },
) => string[]

resolveDependencies 函数将针对每个动态导入调用，其中包含它所依赖的块列表，并且它还将针对在入口 HTML 文件中导入的每个块调用。可以返回一个新的依赖项数组，其中包含这些经过过滤或注入的更多依赖项，以及它们修改后的路径。deps 路径相对于 build.outDir。允许返回相对于 hostId 的相对路径，以供 hostType === 'js' 使用，在这种情况下，new URL(dep, import.meta.url) 用于在 HTML 头部注入此模块预加载时获取绝对路径。

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 | 'esbuild' | 'lightningcss'
• 默认值： 与 build.minify 相同

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

build.sourcemap

• 类型： boolean | 'inline' | 'hidden'
• 默认值： false

生成生产源映射。如果为 true，将创建单独的源映射文件。如果为 'inline'，则源映射将作为数据 URI 附加到生成的输出文件。'hidden' 的工作方式与 true 相同，只是捆绑文件中相应的源映射注释被抑制。

build.rollupOptions

• 类型： RollupOptions

直接自定义底层的 Rollup 捆绑包。这与可以从 Rollup 配置文件导出的选项相同，并将与 Vite 的内部 Rollup 选项合并。有关更多详细信息，请参阅 Rollup 选项文档。

build.commonjsOptions

• 类型： RollupCommonJSOptions

要传递给 @rollup/plugin-commonjs 的选项。

build.dynamicImportVarsOptions

• 类型： RollupDynamicImportVarsOptions
• 相关： 动态导入

要传递给 @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) }
• 相关: 库模式

构建为库。entry 是必需的，因为库不能使用 HTML 作为入口。name 是暴露的全局变量，当 formats 包含 'umd' 或 'iife' 时是必需的。默认 formats 为 ['es', 'umd']，或者如果使用多个入口，则为 ['es', 'cjs']。fileName 是包文件输出的名称，默认 fileName 是 package.json 的 name 选项，它也可以定义为接受 format 和 entryAlias 作为参数的函数。

build.manifest

• 类型: boolean | string
• 默认值： false
• 相关: 后端集成

当设置为 true 时，构建还会生成一个 .vite/manifest.json 文件，其中包含非哈希资产文件名的映射及其哈希版本，然后服务器框架可以使用该映射来渲染正确的资产链接。当值为字符串时，它将用作清单文件名。

build.ssrManifest

• 类型: boolean | string
• 默认值： false
• 相关: 服务器端渲染

当设置为 true 时，构建还会生成一个 SSR 清单，用于在生产环境中确定样式链接和资产预加载指令。当值为字符串时，它将用作清单文件名。

build.ssr

• 类型: boolean | string
• 默认值： false
• 相关: 服务器端渲染

生成面向 SSR 的构建。该值可以是字符串，直接指定 SSR 入口，也可以是 true，这需要通过 rollupOptions.input 指定 SSR 入口。

build.ssrEmitAssets

• 类型： boolean
• 默认值： false

在 SSR 构建期间，静态资产不会被发出，因为假设它们将作为客户端构建的一部分被发出。此选项允许框架在客户端和 SSR 构建中强制发出它们。框架有责任在构建后步骤中合并资产。

build.minify

• 类型: boolean | 'terser' | 'esbuild'
• 默认: 客户端构建为 'esbuild'，SSR 构建为 false

设置为 false 以禁用缩小，或指定要使用的缩小器。默认值为 esbuild，它比 terser 快 20 ~ 40 倍，压缩率仅差 1 ~ 2%。基准测试

请注意，当在 lib 模式下使用 'es' 格式时，build.minify 选项不会缩小空格，因为它会删除纯注释并破坏树摇动。

当设置为 'terser' 时，必须安装 Terser。

npm add -D terser

build.terserOptions

• 类型: TerserOptions

要传递给 Terser 的其他 缩小选项。

此外，您还可以传递一个 maxWorkers: number 选项来指定要生成的 worker 的最大数量。默认为 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

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

build.watch

• 类型: WatcherOptions| null
• 默认: null

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

在 Windows Subsystem for Linux (WSL) 2 上使用 Vite

在某些情况下，文件系统观察无法与 WSL2 一起使用。有关更多详细信息，请参阅 server.watch。