如果你在一个模块数量早就过千的前端项目里待过应该很熟悉这种节奏Webpack开发服务器冷启动要等上几十秒改一行公共代码保存之后还要盯着进度条慢慢走完。我第一次切换到Vite时最大的冲击不是“命令输出好看”而是冷启动几乎在几秒内完成改完文件保存的瞬间页面就更新了。Vite开发环境能做到这一点靠的正是“按需编译”。所谓按需编译从字面上理解就是“不再把整个项目全部编译好而是浏览器请求到哪一个模块就现场编译哪一个模块”。这句话听起来简单但要让编译结果不出错、不丢缓存、不重复计算、还能配合热更新背后是一整套设计。这篇文章我会从原理到实践把Vite开发环境按需编译的完整机制拆开来看顺便给出一份我在实际项目里一直在用的调优配置。1. 从“全量编译”到“按需编译”Vite的取舍逻辑1.1 开发环境全量编译的时间大部分花在了你没打开的模块上传统打包器开发的冷启动为什么慢并不完全是因为JS解析慢而是被“提前编译了大量本次会话根本不会用到的模块”拖累。一个业务项目里有几十个路由、几百个组件但开发时通常只打开其中一个页面。Webpack仍然会从入口开始递归扫描所有import语句把整个依赖图中的模块全部交给loader处理生成一份浏览器能运行的bundle。模块越多这个过程就越沉重。有人会说“Webpack不是也有增量编译吗第一次慢一点后面就快了”。增量确实缓解了重复编译但它的构建工作仍然是以“依赖图更新”为单位的。改了一个被几十个模块引用的公共函数所有引用它的模块都有可能重新编译。这就导致越到项目后期改代码后等待的时间反而越长。问题不在工具本身而在于把“编译”这个动作提前到了“用户真正需要这个模块之前”。按需编译的思路完全不同不在启动时扫描并编译所有模块而是把编译推迟到浏览器发出请求的那一刻。浏览器需要main.ts就编译main.ts需要某个路由组件就编译那个组件。没有请求就没有编译自然不会有“为一个用不到的模块买单”的成本。1.2 浏览器原生ESM给了“按需编译”一张入场券这个思路能成立前提是现代浏览器已经原生支持ES Module。浏览器在加载script typemodule时会自行解析import语句并在需要时向服务器发起新的模块请求。换句话说模块依赖图的构建工作可以由浏览器在运行时完成不再需要打包器预先做一次全量聚合。Vite正是把这个特性用到了极致。开发服务器启动后并不急着给你一个bundle而是返回一份正常的HTML里面挂着/src/main.ts这类入口。浏览器加载入口后会沿着import语句一路请求下去Vite只需要在这些请求到达时做“即时加工”。启动时间因此从“取决于整个项目规模”变成“取决于服务器启动和依赖预构建”后者几乎不受业务代码量影响。但原生ESM也不是万能的。浏览器能直接运行的ESM要求模块路径必须是合法的相对路径或URL且文件内容本身就是标准JS。裸模块导入、路径别名、TypeScript、Vue单文件组件、CSS文件这些都不在浏览器原生能力范围内。所以Vite不能真的“什么都不做”它只是换了一种更聪明的做法把一次性的大规模打包拆成颗粒度到模块的即时编译。1.3 按需编译不是不编译而是把编译推迟到请求那一刻很多朋友第一次接触Vite时会有一个误解按需编译就是“不编译原样返回”。实际不是原样返回的代码浏览器根本跑不起来。Vite做的事情分成两条线面向node_modules里的第三方依赖启动时用esbuild做一次预构建把它们转换成浏览器能用的ESM并合并压缩面向项目源码启动时不处理等浏览器请求到了再逐个做转换、重写、返回。这两条线合在一起才构成完整的“按需编译”体验。第三方依赖一般不会频繁变动非常适合启动时一次性消化源码则恰恰相反改得非常频繁按请求即时编译更合理。把这两类模块分开处理是Vite在开发环境设计上最核心的取舍。2. 依赖预构建按需编译前的那道必答题2.1 预构建一口气解决三个问题先说为什么在“按需”的大前提下仍需对第三方依赖做一次预构建。第一个问题是格式大量npm包发布的仍是CommonJS或UMD浏览器不认识require和module.exports必须转成ESM才能被import语句加载。第二个问题是请求数很多库为了摇树优化把源码拆得非常细直接让浏览器按原始模块逐个加载会产生成千上万个HTTP请求首屏体验会非常差。第三个问题是重复版本同一个依赖如果被不同包引用而导致版本分裂会在运行时出现重复实例预构建也有版本去重的职责。预构建的产物是若干“合并后的大文件”。还是拿lodash-es举例它真实模块可能有两三百个预构建后会合并成少量几个chunk放到.vite/deps目录下。浏览器运行时实际请求的是这些合并后的文件而不是lodash内部的几百个文件。这样既保留了按需编译的即时性又不至于在node_modules层面爆发大量请求。2.2 esbuild做预构建为什么能这么快很多人第一次启动Vite时都会惊叹预构建怎么这么快这里面的功臣是esbuild。esbuild用Go语言编写内部直接使用并行和原生代码解析在处理“把CJS转成ESM再合并”这类机械劳动上速度比Babel快一到两个量级。它并不是完全替代Babel而是因为Vite开发环境对语法兼容要求不高默认目标是现代浏览器所以esbuild的“浅转换”已经够用。这里必须强调一个常见误解Vite用esbuild处理TypeScript和JSX时只做“语法转译”不做“类型检查”。tsc在Vite开发流程里的定位从“编译工具”变成了“IDE和独立命令行的检查工具”。所以你不能说Vite编译TS比Webpack快是因为“优化了tsc”准确说法是它压根没在编译阶段做类型检查从而省掉了最耗时的一部分。类型检查放在编辑器或提交前脚本里通常更合理。2.3 预构建缓存在哪里什么时候会失效预构建产物默认放在node_modules/.vite目录里。正常情况下项目没动这个缓存会一直复用Vite启动时只需校验几个关键文件的hash。hash的输入包括package.json、lockfile、Vite配置里与依赖相关的字段以及部分依赖的元信息。依赖链一旦改变缓存放失效启动时会重新预构建。这个机制本身很可靠但在一些CI或Docker环境里容易踩坑如果node_modules每次都是全新安装.vite缓存自然也不存在每次启动都要重新预构建。虽然速度比旧方案快得多但一次预构建几百个依赖还是需要几十秒所以CI里想加速可以单独用cacheDir配置把缓存指到持久化目录避免每次都被清掉。依赖的预构建结果是比较“整块”的它会根据预构建目标批量更新。如果一个依赖的小版本变了整个预构建缓存往往会失效导致所有依赖重新预构建。这是正常现象不是bug。对于特别大的依赖集合你可以提前用optimizeDeps.include列出核心依赖能减少一些反复扫描和重新构建时的波动。2.4 漏掉预构建的代价二次预构建与页面刷新预构建的扫描发生在启动阶段它从HTML入口开始沿静态import语句收集依赖列表。如果某个依赖是通过动态拼接路径引入的比如import(\./locale/${lang}.js)扫描器很难确定它到底引用了哪些包就可能在预构建列表里漏掉它。一旦浏览器请求到了一个没被预构建的裸模块Vite不会直接报错而是会当场用esbuild把这个依赖补进预构建产物然后通知前端刷新页面。这其实就是你在开发过程中偶尔遇到的“页面突然自己刷一下又重新加载”的原因之一。终端里如果看到类似new dependencies optimized的日志基本就是触发了一次二次预构建。这种体验在演示或调试复杂状态时挺打断人的所以最好在配置里把可能动态出现的依赖提前声明。典型的做法是把那些路由懒加载组件里引用的重库、polyfill、工具函数等加进optimizeDeps.include。让“启动时预构建”把所有可能需要的东西都备好按需编译的体验才够顺滑。3. 源码按需编译管道一个模块请求进来后发生了什么3.1 请求进来会依次经过哪些中间件假设浏览器请求/src/App.vue这个请求并不会像普通静态文件服务器那样直接查磁盘返回而是会走一遍Vite的中间件链。简化来看核心顺序是先查静态资源目录public没命中再进入模块解析解析拿到文件真实路径和是否该走哪种处理流程后进入转换阶段转换完成后还有一步专门的import路径分析对代码里的模块标识符做重写。最后响应内容才会返回给浏览器。静态资源检查放在最前面目的是让public目录下的图片、favicon、静态文件能原样返回不经过编译。而/src下的文件几乎都要走完整链路解析路径、读取内容、按文件类型选择编译器、转换、重写。这个“请求时处理”的模型决定了启动速度基本固定不会因为你后续又加了几百个组件变慢。3.2 transform阶段每种文件到了这里都有对应的“加工方式”Vite内置了对很多文件类型的处理能力同时允许插件自定义处理方式。比如普通.ts文件直接用esbuild做类型剥离.scss会经过sass预处理再交给CSS逻辑.vue文件则交给官方Vue插件调用Vue SFC编译器做一次整体解析把它拆分成更细的子请求。Vue SFC的拆分过程本身也是按需编译的调度杰作。当浏览器请求/src/App.vue时插件不会直接返回一份包含全部逻辑的巨型JS而是返回一段JS代码里面用带query的URL继续请求/src/App.vue?vuetypescript...和/src/App.vue?vuetypetemplate...。每个子请求都会再次走一遍解析和转换。这样设计的好处是模板、脚本、样式可以各自独立更新为HMR的精细粒度做铺垫。CSS文件则会被处理成“能注入style标签的JS模块”给HMR提供局部更新接口。3.3 import analysis把裸导入改写成浏览器看得懂的URL转换后的代码里可能还残留着大量浏览器无法理解的东西最典型的就是import { createApp } from vue。浏览器加载这个模块时只认相对路径或完整的URL看到vue这种裸模块标识符会直接抛出错误。所以Vite内置了一个“import analysis”阶段专门负责把所有模块标识符重写成浏览器能请求的路径。它做的事情大致有这几类把vue、react等裸导入重写成预构建后的URL比如/node_modules/.vite/deps/vue.js?v...把/components/Foo这种别名路径解析成真实文件路径对动态import语句做同样的处理和校验把import.meta.env等Vite注入的运行时信息替换成实际对象。这个阶段还会做一次存在性校验。如果你导入的模块路径写错了Vite会直接返回一段错误信息给浏览器页面上通常能看到一个明确的报错而不是等到打包时才暴露问题。3.4 缓存与URL参数按需编译的“版本号”是怎么工作的如果你打开浏览器Network面板会发现Vite返回的模块URL很长一串里面经常带?t169...之类的参数。这是Vite用来规避浏览器强缓存的手段模块内容变化后URL参数跟着变浏览器就不会拿到旧版本。对浏览器来说带query的URL是不同资源对Vite来说这个query也是它识别模块处理方式的重要依据。服务器内部还会保存一份已经转换过的模块结果缓存。同一个模块在短时间内被多次请求不会重复执行编译器而是直接返回缓存结果。只有文件mtime变化或相关依赖链变化时缓存才会失效。这也是为什么你改完文件保存后Vite能快速重新转换那个模块而不是全量重建。整体来看按需编译的“按需”不仅体现在请求驱动编译还体现在缓存驱动的“不重复编译”。4. 从打开首页到切路由看按需编译的现场表现4.1 第一次打开首页只有链路上的模块被编译为了把上面的机制串起来我描述一次常见的开发过程。你启动项目后第一次访问首页浏览器拿到HTML里面写着script typemodule src/src/main.ts。于是浏览器请求/src/main.tsVite把它转成JS返回。这个模块里的import语句继续触发新的请求vue已经被预构建所以直接走预构建产物App.vue则开始走SFC编译管道App.vue内部又引入了若干业务组件它们同样逐个被请求、逐个被转换。最终你会发现浏览器Network面板里出现的模块清单恰好就是你这条页面访问链路真正涉及的模块集合。那些没被路由适配到的历史页面、不再使用的组件、没被引用的工具函数一概不会出现在请求列表里。这就是按需编译最直观的表现首屏加载的成本和“当前这条链路”成正比而不是和“项目总规模”成正比。4.2 点击路由没被请求过的页面永远不会被编译现在的业务项目几乎都会做路由懒加载常见写法是() import(./views/About.vue)。由于这是动态import浏览器在解析到这个语句时才会向服务器发起对应模块请求。也就是说一个几十个页面的大项目你如果只点开了首页和详情页那其余几十个页面的代码在这个开发会话里可能一次编译都不会发生。这种体验用一句话概括就是“访问推进到哪里编译就进行到哪里”。用户切到关于页才编译关于页切到设置页才编译设置页。开发服务器不会提前替你做任何多余的工作。需要注意的是这里的“按需”其实是两层浏览器按需加载模块Vite按需编译模块。两者叠加开发期的编译负载才会降得这么低。4.3 新引入一个npm包时的现场反应按需编译虽然顺滑但也不是完全没有波折。假设你在某个组件里新加了一个import x from some-tool这个包从未出现在启动扫描的依赖列表里。保存后浏览器请求该包的预构建URL发现不存在Vite会触发一次现场预构建把some-tool也合并到.vite/deps里然后给页面发一条刷新指令。很多时候你会看到页面“闪一下”后重新加载状态丢失。如果是普通调试问题不大但在做联调或者需要保留某些临时状态时就会比较讨厌。避免方案就是我前面反复提到的把所有可能的动态依赖提前写进optimizeDeps.include里让它在启动阶段就被预构建好。这不是配置洁癖而是实实在在地省去每次“看到页面闪一下再重新等编译”的麻烦。4.4 为什么不总是“秒开”瀑布请求与预热方案按需编译并不等于“一定快得离谱”。某些场景下首次访问反而可能变慢一是某个第三方包特别大比如3D渲染库首次请求它时仍需要现场转换即使有预构建esbuild处理这个包内部成百上千个模块也需要时间二是浏览器需要层层解析import形成一串串瀑布请求如果首屏模块嵌套很深往返次数会明显增加。对这种场景我的处理顺序是先用optimizeDeps.include把重依赖提前备好再把首屏核心模块用server.warmup预热让开发服务器主动提前转换它们最后检查首屏模块树的深度减少不必要的深链嵌套。做完这三步绝大多数“首次访问明显慢”的情况都能得到很大改善而不用改动任何业务代码。5. HMR为什么能这么快它和按需编译是怎么配合的5.1 HMR不是独立服务它复用按需编译的管道Vite的热更新体验很多人觉得“快得不像话”其实它的底座正是按需编译。每次文件保存后开发服务器会从模块图里找出受影响的模块然后通过WebSocket向浏览器发送一条更新通知。浏览器收到通知后不会整页刷新而是针对相关模块重新发起请求。这些请求的响应路径和正常首次请求完全一样仍然走“解析转换重写”的管道。因为更新范围被精确控制在受影响的那几个模块上服务器不需要重新处理那些没变化的模块转换量自然很小响应也就极快。换句话说HMR并没有额外引入一套复杂的独立机制它只是按需编译管道上多了几个“更新信号”让浏览器知道“你该去重新拉取某几个模块了”。5.2 更新粒度由谁决定Vue组件的三种更新方式以Vue SFC为例Vite能判断出你改的是SFC的哪个部分然后选择不同的更新方式。改模板时它会发送vue-rerender意思是“这个组件的渲染函数需要换一份但组件实例不用重建”所以页面状态得以保留改脚本时它会发送vue-reload整个组件模块需要重新加载组件实例通常会被销毁重建改样式时它会发送style-update只更新对应的CSS片段连组件重新渲染都可以省掉。这三种粒度对应了Vue组件不同的更新需求。模板更新是最理想的情况因为它最贴近“改界面不动状态”的日常体验。这也是为什么你在写Vue组件时优先让模板改动独立减少对脚本逻辑的连带影响HMR的体验会更好。框架内部对SFC拆分得越细这种精细化热更新越容易实现。5.3 没有accept边界时HMR会怎么兜底并不是每个模块改动都能局部热替换。对于普通JS模块如果代码里没有显式调用import.meta.hot.acceptVite就不能确定这个模块被更新后引用它的位置是否还能安全运行。此时Vite会沿着模块引用关系向上找看哪个父模块声明了接受热更新。如果找到了就从那个位置重新加载如果一路找到根模块都没有声明就退化成一整次页面刷新。这个回退策略是保守但正确的。它不会为了追求“局部不刷新”而冒险留下不一致状态。实际开发中你会发现越是底层的工具模块越难局部热更新因为它被很多模块依赖而组件边界通常比较容易因为框架插件已经帮你处理了accept逻辑。这也是为什么我在写业务代码时会尽量把可热更新的边界划在组件层面让HMR的体验保持稳定。5.4 状态丢失和HMR失效的排查方向很多人遇到HMR失效时容易一头雾水其实常见的坑就那么几个。第一组件或工具模块在建立时挂了全局事件或定时器却在dispose回调里没有清理热更新后老事件还在新事件又挂一份表现就是页面行为变得怪异。第二某个模块没有被任何父模块正确acceptVite只能选择全量刷新表现是“明明改了一个小组件整个页面却重新加载了”。第三某些动态生成组件或使用了特殊语法的模块插件分析不出明确的边界也会退化为刷新。排查时建议先看浏览器的ConsoleHMR相关信息通常会打印出来再配合DEBUGvite:hmr这类日志观察服务器端对更新类型的判断。实在定位不了可以暂时忽略把重点放在“找边界的代码块”上让更新点收敛在组件或独立函数内HMR的命中率会高很多。6. 按需编译的天花板边界、坑与一套能照抄的调优配置6.1 生产环境为什么必须回到“打包”这条路按需编译是开发环境的专属策略生产构建仍然需要回到打包。原因并不复杂生产环境追求的不是“只编译当前用到的模块”而是“把整个应用优化到极致”。这包括代码压缩、Tree Shaking、更老浏览器的语法降级、CSS抽取、长效缓存和代码分割。这些都是跨模块的全局优化必须在拿到完整依赖图之后才能做。Vite把开发时的按需编译和生产时的Rollup构建分开正是为了“开发体验和生产性能不必互相妥协”。开发时你可以接受请求瀑布和未压缩代码换来极低的启动成本生产时则用一次性的静态分析换取最优产物。理解了这一点你就不必觉得“为什么开发不打包、生产要打包”是割裂的设计它恰恰是合理的分工。6.2 老浏览器原生ESM的门槛按需编译依赖浏览器原生ESM加载器老浏览器没有这个能力。所以如果你的用户群体里还有远古浏览器开发模式的按需编译帮不了忙得靠构建产物兼容。Vite官方提供了vitejs/plugin-legacy但它主要作用于生产构建先用现代模块构建一版再用SystemJS和语法兼容层生成另一版让老浏览器也能运行。这里不要误解成“装了legacy插件开发环境就能在老浏览器上跑到按需编译”。开发模式下Vite依然默认使用原生ESM。如果你真的有老浏览器调试需求那就需要额外的兼容方案而不是指望按需编译本身解决所有兼容问题。这也是我在选型时特别强调的一件事按需编译能换来的极致开发体验默认服务对象是支持ESM的现代浏览器。6.3 Monorepo与大依赖按需编译的常见摩擦点在Monorepo或多包项目中业务包之间往往通过workspace链接彼此引用。这些源码包并不在node_modules的普通依赖列表里Vite的预构建扫描经常不覆盖它们。结果就是某个工作区包首次被引用时会以源码形式进入按需编译管道速度和稳定性都可能比预构建版本差一些。处理这种场景通常要配合两步一是放宽开发服务器的文件访问范围配置server.fs.allow让它可以读取工作区根目录二是把工作区包的核心ESM入口加入optimizeDeps.include让它们经过预构建合并。如果包之间互相引用的关系很乱还可以用resolve.dedupe强制同一框架只保留一份实例。这些配置本质上都是在帮按需编译减小阻力让它能准确预判“哪些模块该提前备好”。大依赖同样值得专门处理。一个很大的库如果只在少数页面使用可以考虑路由懒加载和optimizeDeps.include组合。前者保证没访问到时不加载后者保证访问到时不用现场等编译。两件事的目的不同但组合起来按需编译的体验就能保持在稳定水平。6.4 一套可以直接抄的调优配置把前面讨论过的配置集中到一份示例里结合注释使用// vite.config.ts import { defineConfig } from vite export default defineConfig({ optimizeDeps: { // 把动态依赖或重量级依赖提前预构建避免首次请求时二次预构建 include: [ date-helper, some-heavy-3d-lib ], // 一般不建议排除依赖除非确认它是纯ESM且希望走源码级按需编译 exclude: [], }, resolve: { // 强制同版本框架去重防止重复实例 dedupe: [vue], }, server: { fs: { // Monorepo/多包仓库需要允许访问项目根之外的目录 allow: [..], }, warmup: { // 预热首屏核心模块减少第一次请求链路的等待 clientFiles: [ ./src/main.ts, ./src/App.vue, ], }, }, })这里最值得注意的配置是optimizeDeps.include和server.warmup。前者解决的是“依赖层面的按需预构建漏网”问题后者解决的是“源码层面的首次请求慢”问题。两个配置都是按需编译机制的补充而不是替代。把这两条用好了很多开发期莫名其妙的“卡一下”都能消失。6.5 用Debug日志审计按需编译的真实耗时最后给一个我每次排查性能问题都会用的手段打开Vite的Debug日志。用DEBUGvite:*启动开发服务器能看到服务器在处理每个请求时的内部细节包括模块解析、转换、依赖预构建等环节。如果只想看某一块比如模块转换就把日志筛选到vite:transform想看依赖预构建就筛选到依赖相关命名空间。通过日志你能清楚看到哪个模块的transform耗时不正常哪些依赖在请求时被临时预构建哪些缓存没有命中。有真实数据之后再做配置调整比我空口说“哪个依赖慢”靠谱得多。调试的目的不是追求日志里所有请求耗时都为零而是要找出真正拖后腿的那几个异常点按需处理。我自己的习惯是接到一个“Vite开发环境变卡”的反馈后先打开Debug日志确认是依赖预构建问题还是源码转换问题再决定是加include还是调warmup。按需编译本身不是银弹它只是把编译成本从“全量、提前”变成了“按需、即时”而这份成本仍需要你用正确配置来控制边界。