Vite build 配置项深度解析从 build.target 到产物输出的全链路配置指南【免费下载链接】viteNext generation frontend tooling. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vi/viteVite 生产构建的几乎所有行为都由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配置则需要在自定义入口中手动引入 polyfillimport 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:booleanDefault:trueDeprecated请改用build.modulePreload.polyfill作用是是否自动注入 module preload polyfill功能上已被modulePreload.polyfill取代。3. 输出目录与静态资源策略build.outDir 与 build.assetsDirbuild.outDirstring默认dist指定输出目录相对项目根目录解析build.assetsDirstring默认assets指定生成资源在outDir下的嵌套目录名。该选项在 Library Mode 下不生效。build.assetsInlineLimitType:number|((filePath: string, content: Buffer) boolean | undefined)Default:40964 KiB小于该阈值的导入或被引用资源会被内联为 base64 URL以减少额外的 HTTP 请求设为0则完全禁用内联。默认值在源码 constants.ts 中定义为DEFAULT_ASSETS_INLINE_LIMIT 4096build.ts 的默认值对象中直接引用该常量。传入回调函数时返回boolean可以针对单个文件选择启用或跳过内联返回undefined即不返回时回退到默认大小判断逻辑。此外Git LFS 占位符文件会被自动排除在内联之外因为它们不包含所代表文件的真实内容。::: tip 如果指定了build.libbuild.assetsInlineLimit将被忽略无论文件大小与是否为 Git LFS 占位符资源都会始终内联。 :::build.emptyOutDirType:booleanDefault:当outDir位于项目根目录内时为true默认情况下如果outDir在项目根目录内build 会清空它如果outDir在根目录外Vite 会输出警告以避免误删重要文件此时可显式设置该选项来抑制警告。该选项也可通过命令行--emptyOutDir传入。源码中该字段默认值为null即未显式设置由 build.ts 在构建时结合resolveEmptyOutDir逻辑根据outDir与 root 的相对位置推导。build.copyPublicDirType:booleanDefault:true默认情况下build 会把publicDir中的文件复制到outDir设为false可禁用此行为。build.writeType:booleanDefault:true设为false可禁用将 bundle 写入磁盘。这主要用于 programmaticbuild()调用场景当需要在写盘前对产物做进一步后处理时关闭写盘、在内存中操作再自行落盘。4. CSS 处理cssCodeSplit、cssTarget 与 cssMinifybuild.cssCodeSplitType:booleanDefault:true启用/禁用 CSS 代码分割。启用时异步 JS chunk 中导入的 CSS 会被保留为独立 chunk并随 JS chunk 一起被加载。禁用时整个项目的所有 CSS 会被提取到单个CSS 文件中。注意指定build.lib后build.cssCodeSplit默认值为false。build.cssTargetType: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.cssMinifyType:boolean | lightningcss | esbuildDefault:lightningcss但如果build.minify对 client build 被禁用则为false该选项允许单独覆盖 CSS 压缩行为而不受build.minify默认影响从而为 JS 和 CSS 分别配置压缩。Vite 默认使用 Lightning CSS 压缩 CSS可通过css.lightningcss配置设为esbuild则改用 esbuild。设为esbuild时 esbuild 必须已安装npm add -D esbuild5. build.sourcemapType:boolean | inline | hiddenDefault:false生成生产环境 sourcemap。true表示生成独立的 sourcemap 文件inline表示以 data URI 形式追加到产物文件末尾hidden与true相同但会抑制 bundle 文件中的 sourcemap 注释即文件存在、浏览器 DevTools 不提示、但可手动加载。源码默认值对象中同样为sourcemap: false见 build.ts。6. build.chunkImportMapType:booleanDefault:falseExperimental是否使用 import map 特性优化 chunk 缓存效率详见 Chunk Import Map 优化。该特性要求浏览器支持import.meta.resolve如需兼容旧浏览器可查看仓库内的 plugin-legacy 包。7. 透传打包器选项build.rolldownOptions 与 build.rollupOptionsbuild.rolldownOptionsType:RolldownOptions直接自定义底层的 Rolldown bundle。它与 Rolldown 配置文件中可导出的选项一致会与 Vite 内部选项合并。一个推荐做法不要使用build.rolldownOptions.input设置入口而应使用顶层input选项因为它在 dev 中同样生效如果设置了build.rolldownOptions.input它只在 build 时覆盖顶层input。build.rollupOptions已废弃Type:RolldownOptionsDeprecated它是build.rolldownOptions的别名请使用build.rolldownOptions。8. build.dynamicImportVarsOptionsType:{ include?: string | RegExp | (string | RegExp)[], exclude?: string | RegExp | (string | RegExp)[] }控制是否转换携带变量的动态 importimport(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.entryname是暴露的全局变量名当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.manifestType:boolean | stringDefault:false是否生成 manifest 文件其中包含非哈希资产文件名到其哈希版本的映射供服务端框架渲染正确的资源链接使用详见 Backend Integration。值为字符串时作为相对outDir的 manifest 文件路径设为true时路径为.vite/manifest.json。如果正在编写插件需要在 build 中检查每个输出 chunk 或资产的关联 CSS 与静态资源也可以使用viteMetadataoutput bundle 元数据 API。build.ssrManifestType:boolean | stringDefault:false是否生成 SSR manifest 文件用于在生产环境决定样式链接与资源预加载指令详见 SSR。字符串值作为相对outDir的路径设为true时路径为.vite/ssr-manifest.json。build.ssrType:boolean | stringDefault: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.terserOptionsbuild.minifyType:boolean | oxc | terser | esbuildDefault:client build 为oxcSSR 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 terserbuild.terserOptionsType:TerserOptions传递给 Terser 的额外 minify 选项。此外还支持maxWorkers: number指定生成的 worker 最大数量默认值为主板 CPU 数减 1。13. build.watch 与构建过程调优build.watchType:WatcherOptions | nullDefault:null设为{}即可启用 Rolldown watcher。这主要用于涉及 build-only 插件或集成构建流程的场景。在 WSL2 上使用 Vite 时文件监听存在失效的可能可参考server.watch的说明。build.reportCompressedSizeType:booleanDefault:true启用/禁用 gzip 压缩体积报告。压缩大产物文件可能较慢大型项目禁用此项可以提升构建性能。build.chunkSizeWarningLimitType:numberDefault:500chunk 体积警告阈值单位 kB比较对象是未压缩的 chunk 体积——因为 JS 体积本身与执行时间相关。14. 默认值速查与源码对照汇总文档声明的全部 build 选项默认值未列出的无默认值/按需启用选项默认值说明targetbaseline-widely-available等价于[chrome111,edge111,firefox114,safari16.4,ios16.4]modulePreload{ polyfill: true }自动注入 modulepreload polyfillpolyfillModulePreloadtrue已废弃改用modulePreload.polyfilloutDirdist相对项目根目录assetsDirassets相对outDirassetsInlineLimit40964 KiB 内联阈值cssCodeSplittruelib 模式下默认falsecssTarget同build.targetCSS 压缩目标cssMinifylightningcssbuild.minify禁用时为falsesourcemapfalsechunkImportMapfalse实验性lib无库模式licensefalsemanifestfalsessrManifestfalsessrfalseemitAssetsfalsessrEmitAssetsfalse将被emitAssets取代minifyoxcclient/falseSSRwritetrueemptyOutDiroutDir在 root 内时truecopyPublicDirtruereportCompressedSizetruechunkSizeWarningLimit500kBwatchnull这些默认值在源码中的落点是 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. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考