Vite build 配置项深度解析：从 build.target 到产物输出的全链路配置指南

Vite build 配置项深度解析：从 build.target 到产物输出的全链路配置指南

【免费下载链接】viteNext generation frontend tooling. It's fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite

Vite 生产构建的几乎所有行为都由build.*系列配置项控制，它们决定了最终产物的浏览器兼容目标、代码分割与预加载策略、CSS 处理、压缩方式以及输出目录结构。本文以 Vite 官方文档 build-options.md 为主体，逐项讲解全部 build 配置的类型、默认值与适用场景，并结合仓库源码（如 build.ts、constants.ts）验证默认值与解析逻辑，帮助你为前端项目、库构建（Library Mode）和 SSR 构建写出可复制、可预期的build配置。

需要特别说明：文档原文明确指出，除非另有说明，本节所有选项仅作用于 build，不影响 dev 行为。

1. build.target：浏览器兼容目标

• Type:string | string[]
• Default:'baseline-widely-available'

这是控制最终 bundle 浏览器兼容性的核心选项，详见 浏览器兼容性指南。默认值'baseline-widely-available'是 Vite 的特殊值：它对应每个大版本固定日期的 Baseline Widely Available 最低浏览器版本。当前大版本对应的具体目标数组为['chrome111', 'edge111', 'firefox114', 'safari16.4', 'ios16.4']。

这个结论在源码中可以印证：constants.ts 中定义了ESBUILD_BASELINE_WIDELY_AVAILABLE_TARGET常量，其内容正是上述五个浏览器目标，并注释说明该值会随 Vite 每个大版本更新（由pnpm generate-target脚本生成）。而 build.ts 的配置解析逻辑中，当检测到merged.target === 'baseline-widely-available'时，会将其替换为该常量数组，随后对数组去重后交给转换器。

另一个特殊值是'esnext'——假设浏览器原生支持动态 import，只做最少的转译。

转译由 Oxc Transformer 完成，自定义目标可以是：

• ES 版本，如es2015；
• 带版本的浏览器，如chrome58；
• 多个目标字符串的数组。

注意：如果代码中包含 Oxc 无法安全转译的特性，build 会输出警告，可参考 Oxc 的 lowering 文档了解具体警告项。

2. build.modulePreload：模块预加载策略

• Type:boolean | { polyfill?: boolean, resolveDependencies?: ResolveModulePreloadDependenciesFn }
• Default:{ polyfill: true }

默认情况下 Vite 会自动注入 module preload polyfill。

如果使用非 HTML 自定义入口（即通过build.rolldownOptions.input配置），则需要在自定义入口中手动引入 polyfill：

import 'vite/modulepreload-polyfill'

两点注意：

• polyfill不适用于Library Mode——如果你的库需要支持没有原生动态 import 的浏览器，应避免在库中使用动态 import；
• 可通过{ polyfill: false }关闭 polyfill。

预加载依赖列表如何计算

每个动态 import 对应的预加载 chunk 列表由 Vite 计算。默认使用包含base的绝对路径；如果base是相对路径（''或'./'），运行时会使用import.meta.url，避免生成依赖最终部署 base 的绝对路径。

resolveDependencies：精细控制预加载依赖

可以通过resolveDependencies函数对依赖列表及其路径做精细控制（实验性功能）。它接收如下类型的函数：

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

该函数会在每个动态 import处被调用，传入其依赖的 chunk 列表；同时也会为入口 HTML 文件中导入的每个 chunk调用一次。你可以返回过滤后的数组、注入更多依赖，或修改路径。其中deps是相对build.outDir的路径，返回值也应是相对build.outDir的路径。配置示例（摘自文档原文）：

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

解析出的依赖路径还可以结合experimental.renderBuiltUrl进一步修改。

build.polyfillModulePreload（已废弃）

• Type:boolean
• Default:true
• Deprecated，请改用build.modulePreload.polyfill

作用是是否自动注入 module preload polyfill，功能上已被modulePreload.polyfill取代。

3. 输出目录与静态资源策略

build.outDir 与 build.assetsDir

• build.outDir（string，默认'dist'）：指定输出目录，相对项目根目录解析；
• build.assetsDir（string，默认'assets'）：指定生成资源在outDir下的嵌套目录名。该选项在 Library Mode 下不生效。

build.assetsInlineLimit

• Type:number|((filePath: string, content: Buffer) => boolean | undefined)
• Default:4096（4 KiB）

小于该阈值的导入或被引用资源会被内联为 base64 URL，以减少额外的 HTTP 请求；设为0则完全禁用内联。默认值在源码 constants.ts 中定义为DEFAULT_ASSETS_INLINE_LIMIT = 4096，build.ts 的默认值对象中直接引用该常量。

传入回调函数时，返回boolean可以针对单个文件选择启用或跳过内联；返回undefined（即不返回）时回退到默认大小判断逻辑。此外，Git LFS 占位符文件会被自动排除在内联之外，因为它们不包含所代表文件的真实内容。

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

build.emptyOutDir

• Type:boolean
• Default:当outDir位于项目根目录内时为true

默认情况下，如果outDir在项目根目录内，build 会清空它；如果outDir在根目录外，Vite 会输出警告以避免误删重要文件，此时可显式设置该选项来抑制警告。该选项也可通过命令行--emptyOutDir传入。源码中该字段默认值为null（即"未显式设置"），由 build.ts 在构建时结合resolveEmptyOutDir逻辑根据outDir与 root 的相对位置推导。

build.copyPublicDir

• Type:boolean
• Default:true

默认情况下，build 会把publicDir中的文件复制到outDir；设为false可禁用此行为。

build.write

• Type:boolean
• Default:true

设为false可禁用将 bundle 写入磁盘。这主要用于 programmaticbuild()调用场景：当需要在写盘前对产物做进一步后处理时，关闭写盘、在内存中操作再自行落盘。

4. CSS 处理：cssCodeSplit、cssTarget 与 cssMinify

build.cssCodeSplit

• Type:boolean
• Default:true

启用/禁用 CSS 代码分割。启用时，异步 JS chunk 中导入的 CSS 会被保留为独立 chunk，并随 JS chunk 一起被加载。禁用时，整个项目的所有 CSS 会被提取到单个CSS 文件中。

注意：指定build.lib后，build.cssCodeSplit默认值为false。

build.cssTarget

• Type:string | string[]
• Default:与build.target相同

该选项允许为 CSS 压缩单独设置浏览器目标，与 JS 转译目标解耦。当build.cssMinify为'lightningcss'（默认）时，此选项在压缩步骤中优先于css.lightningcss.targets生效。

它只在目标是非主流浏览器时才需要单独设置。文档给出的典型例子是 Android 微信 WebView：它支持大多数现代 JS 特性，但不支持 CSS 的#RGBA十六进制颜色写法，此时需将build.cssTarget设为chrome61，防止 Vite 把rgba()颜色转成#RGBA十六进制记法。

build.cssMinify

• Type:boolean | 'lightningcss' | 'esbuild'
• Default:'lightningcss'；但如果build.minify对 client build 被禁用，则为false

该选项允许单独覆盖 CSS 压缩行为，而不受build.minify默认影响，从而为 JS 和 CSS 分别配置压缩。Vite 默认使用 Lightning CSS 压缩 CSS，可通过css.lightningcss配置；设为'esbuild'则改用 esbuild。

设为'esbuild'时 esbuild 必须已安装：

npm add -D esbuild

5. build.sourcemap

• Type:boolean | 'inline' | 'hidden'
• Default:false

生成生产环境 sourcemap。true表示生成独立的 sourcemap 文件；'inline'表示以 data URI 形式追加到产物文件末尾；'hidden'与true相同，但会抑制 bundle 文件中的 sourcemap 注释（即文件存在、浏览器 DevTools 不提示、但可手动加载）。源码默认值对象中同样为sourcemap: false（见 build.ts）。

6. build.chunkImportMap

• Type:boolean
• Default:false
• Experimental

是否使用 import map 特性优化 chunk 缓存效率，详见 Chunk Import Map 优化。该特性要求浏览器支持import.meta.resolve；如需兼容旧浏览器，可查看仓库内的 plugin-legacy 包。

7. 透传打包器选项：build.rolldownOptions 与 build.rollupOptions

build.rolldownOptions

• Type:RolldownOptions

直接自定义底层的 Rolldown bundle。它与 Rolldown 配置文件中可导出的选项一致，会与 Vite 内部选项合并。

一个推荐做法：不要使用build.rolldownOptions.input设置入口，而应使用顶层input选项，因为它在 dev 中同样生效；如果设置了build.rolldownOptions.input，它只在 build 时覆盖顶层input。

build.rollupOptions（已废弃）

• Type:RolldownOptions
• Deprecated

它是build.rolldownOptions的别名，请使用build.rolldownOptions。

8. build.dynamicImportVarsOptions

• Type:{ include?: string | RegExp | (string | RegExp)[], exclude?: string | RegExp | (string | RegExp)[] }

控制是否转换携带变量的动态 import（import(var)语法），通过include/exclude白名单/黑名单精确圈定生效范围，详见 动态导入。

9. build.lib：库模式构建

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

以库的形式构建，详见 Library Mode。关键规则：

• entry默认取顶层input选项，二者必须有其一，因为库不能使用 HTML 作为入口。源码中该回退逻辑可在 build.ts 的配置解析处看到：当merged.lib.entry == null && input != null时，会将顶层input拷贝进lib.entry；
• 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', }, }, })

10. build.license：生成依赖许可证文件

• Type:boolean | { fileName?: string }
• Default:false

设为true时，build 会生成.vite/license.md文件，收录所有打包依赖的许可证；详见 License。

如果传入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在文件顶部注入注释：

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

11. Manifest 与 SSR 构建相关选项

build.manifest

• Type:boolean | string
• Default:false

是否生成 manifest 文件，其中包含非哈希资产文件名到其哈希版本的映射，供服务端框架渲染正确的资源链接使用，详见 Backend Integration。值为字符串时作为相对outDir的 manifest 文件路径；设为true时路径为.vite/manifest.json。

如果正在编写插件，需要在 build 中检查每个输出 chunk 或资产的关联 CSS 与静态资源，也可以使用viteMetadataoutput bundle 元数据 API。

build.ssrManifest

• Type:boolean | string
• Default:false

是否生成 SSR manifest 文件，用于在生产环境决定样式链接与资源预加载指令，详见 SSR。字符串值作为相对outDir的路径；设为true时路径为.vite/ssr-manifest.json。

build.ssr

• Type:boolean | string
• Default:false

产出面向 SSR 的构建。字符串值可直接指定 SSR 入口；true则需要通过顶层input或build.rolldownOptions.input指定 SSR 入口。

build.emitAssets 与 build.ssrEmitAssets

• 两者均为boolean，默认false。

在非 client build 中，静态资产默认不输出（假设它们会随 client build 一起产出）。build.emitAssets允许框架在其他环境的构建中强制输出这些资产，资产合并由框架在构建后的步骤中负责。build.ssrEmitAssets则是针对 SSR build 的同义开关，在 Environment API 稳定后将被build.emitAssets取代。

12. 压缩与压缩选项：build.minify 与 build.terserOptions

build.minify

• Type:boolean | 'oxc' | 'terser' | 'esbuild'
• Default:client build 为'oxc'，SSR build 为false

设为false禁用压缩，或指定压缩器。默认使用 Oxc Minifier，官方文档给出的数据是比 terser 快 30 ~ 90 倍、压缩率仅差 0.5 ~ 2%。注意build.minify: 'esbuild'已废弃，将在未来版本移除。

另一个细节：库模式下使用'es'格式时，build.minify不会压缩空白符，因为那会移除 pure 注解并破坏 tree-shaking。

设为'esbuild'或'terser'时，对应工具必须已安装：

npm add -D esbuild npm add -D terser

build.terserOptions

• Type:TerserOptions

传递给 Terser 的额外 minify 选项。此外还支持maxWorkers: number，指定生成的 worker 最大数量，默认值为主板 CPU 数减 1。

13. build.watch 与构建过程调优

build.watch

• Type:WatcherOptions | null
• Default:null

设为{}即可启用 Rolldown watcher。这主要用于涉及 build-only 插件或集成构建流程的场景。在 WSL2 上使用 Vite 时，文件监听存在失效的可能，可参考server.watch的说明。

build.reportCompressedSize

• Type:boolean
• Default:true

启用/禁用 gzip 压缩体积报告。压缩大产物文件可能较慢，大型项目禁用此项可以提升构建性能。

build.chunkSizeWarningLimit

• Type:number
• Default:500

chunk 体积警告阈值（单位 kB），比较对象是未压缩的 chunk 体积——因为 JS 体积本身与执行时间相关。

14. 默认值速查与源码对照

汇总文档声明的全部 build 选项默认值（未列出的无默认值/按需启用）：

这些默认值在源码中的落点是 build.ts 中的_buildEnvironmentOptionsDefaults冻结对象：其中target: 'baseline-widely-available'、outDir: 'dist'、assetsDir: 'assets'、assetsInlineLimit: DEFAULT_ASSETS_INLINE_LIMIT（即 4096，见 constants.ts）、sourcemap: false、emptyOutDir: null、reportCompressedSize: true、chunkSizeWarningLimit: 500等，与文档声明一一对应。

小结

build.*配置覆盖了 Vite 构建的完整生命周期：build.target与build.cssTarget决定产物兼容性边界，build.modulePreload与build.chunkImportMap决定加载与缓存策略，build.outDir/build.assetsInlineLimit/build.emptyOutDir决定产物落盘形态，build.lib/build.ssr切换构建目标形态，build.minify/build.cssMinify控制体积优化，build.manifest/build.ssrManifest/build.license则服务于部署与合规。配置时只需注意三件事：库模式会隐式改变cssCodeSplit、assetsInlineLimit与 polyfill 的行为；rollupOptions与polyfillModulePreload、minify: 'esbuild'均已废弃，应迁移到对应新选项；所有默认值均可在上述源码位置交叉验证。

【免费下载链接】viteNext generation frontend tooling. It's fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite