1. 项目画像先搞清楚优化前到底差在哪1.1 我接手的是一个什么样的Vue3项目先交代背景。我维护的项目是一个典型的中后台管理系统技术栈是Vue3.2 Vite5 Element Plus ECharts Pinia页面数量大概25个真实路由另外还挂了一个数据大屏模块。这个项目不是从零搭的是从一个老团队手里接过来的接手时整个项目已经处于半上线状态线上反馈的主要问题就一个字慢。这个“慢”体现在两个层面。第一个层面是开发环境同事反馈改一行代码有时候要等好几秒才能看到热更新严重的时候直接卡死。第二个层面是生产构建每次发版跑npm run build都在四十秒以上遇到CI高峰期甚至能拖到一分钟。你可能会说四十秒也不算离谱但我们的发布节奏是一天至少三次这个时间成本累积下来非常恐怖。接手之后我没有急着优化也没有直接找所谓的“最佳实践”往上套。我先干了三件事记录构建耗时、统计产物体积、用浏览器DevTools的Performance面板采集线上首屏数据。为什么要先干这些因为打包优化最忌讳的就是凭感觉你觉得是某个库的问题优化了半天结果发现真正的瓶颈在别处这种无用功我做过太多次了。1.2 优化前的基线数据长什么样我把当时的基线数据记录如下后来所有的优化动作都以这份数据作为对照指标优化前数值说明生产构建耗时约42秒首次冷构建无缓存dist目录总大小约2.4MB未压缩gzip压缩后大小约680KBnginx开启了gzip首屏白屏时间约2.8秒浏览器Performance面板测量首屏最大JS chunk约890KB单个vendor包开发热更新平均耗时约1.5秒编辑一个Vue组件到页面刷新说实话这个数据放在2024年来说是相当难看的。尤其是那个890KB的单chunk意味着用户打开页面必须先下载将近1MB的JS而且这1MB里面很多是我们根本用不到的代码。1.3 优化目标不是“越快越好”而是定一个可复用的指标这里我想多说一句很多人做优化上来就说“我要把构建时间干到5秒以内”这个目标本身没有错但它缺乏可度量性。更合理的方式是先问自己三个问题哪些优化能同时改善开发体验和生产体验哪些优化是在牺牲代码可维护性的前提下换来的优化效果上线后用户真的能感知到吗我最终定下的优化目标只有三个第一生产构建时间从42秒压到15秒以内第二首屏最大JS chunk降到300KB以下第三白屏时间压到1.5秒左右。后面所有动作都围绕这三个目标展开能达成的留下达不成的就放弃。整个优化过程我按主题拆成几块下面逐一讲。2. 构建速度优化开发与生产的双重提速链路2.1 依赖预构建让Vite少做无用功Vite之所以快核心在于它利用ESModule原生能力绕过了打包开发时只做转换不做打包。但这不代表它什么都不用做。当你第一次启动开发服务器时Vite需要先把node_modules里的CommonJS模块转换成ESM这个过程叫预构建默认产物缓存在node_modules/.vite目录下。这个预构建过程非常耗时。我当时第一次跑npm run dev光预构建就花了将近10秒而且只要依赖有变更又会触发重新预构建。解决方案是在vite.config.ts里显式声明optimizeDeps.include和optimizeDeps.exclude// vite.config.ts export default defineConfig({ optimizeDeps: { include: [ vue, vue-router, pinia, axios, echarts/core ], exclude: [vueuse/core] } })include的作用是告诉Vite这些依赖需要预构建提前把它们扫描并转成ESM。exclude则相反当某个库原生就支持ESM且没有CJS依赖时可以把它排除掉减少预构建的负担。这个配置做完了开发服务器的首次启动时间从10秒降到了3秒左右热更新的响应也更快了。很多人忽略这个配置觉得Vite默认足够聪明但实际情况是Vite的依赖扫描器在遇到某些深层嵌套的依赖时会漏掉或者误判手动指定include其实是给Vite画了一张更准确的地图。2.2 压缩方式从Terser切换到esbuild这是我做得最轻松但收益最大的一项调整。Vite4之后的构建流程默认就是Rollup打包 esbuild压缩但早期版本的Vite默认用Terser做压缩。Terser的压缩效果确实更好一些但它的压缩速度大概是esbuild的十分之一。如果你还在用Terser只需要在构建配置里切换// vite.config.ts build: { minify: esbuild, // 如果代码里有console.log要保留可以在这里配置 esbuild: { pure: [console.log], drop: [debugger] } }这里有个细节值得注意pure: [console.log]是告诉esbuild把这些调用当作无副作用的表达式构建时可以直接删掉。drop: [debugger]同理。但我不建议无脑删除所有console.log因为线上环境出了bug你还需要日志来排查删得太干净反而踩坑。比较稳妥的做法是保留console.warn和console.error只删纯console.log。2.3 并行化构建让CPU的全部核芯都动起来Vite的构建默认是单进程的Rollup在打包时虽然有部分并行能力但整体上对CPU的利用率并不高。我当时的机器是8核16线程但构建时CPU占用率大概只有30%左右。后来我用了vite-plugin-parallel来解决并行构建问题。它的原理是把多个入口的构建任务拆成多个worker同时执行对于多入口项目收益非常明显。如果你的项目也是多入口架构可以这样配import { parallelPlugin } from vite-plugin-parallel export default defineConfig({ plugins: [ parallelPlugin({ parallel: 4 // 根据CPU核心数调整 }) ] })不过这里我要提醒一句这个插件适合多入口项目如果你的项目是单入口SPA用了反而可能因为worker通信开销拖慢速度。2.4 实测结果构建耗时到底降了多少做完前面三步我重新跑了一次冷构建耗时从42秒降到了16秒左右。虽然没达到“5秒以内”这种激进目标但已经实现了我的第一个优化目标。更关键的是开发环境的体感改善非常明显热更新从1.5秒降到了500毫秒以内同事的反馈是“终于不用等得想去冲咖啡了”。这一轮优化没有改任何业务代码纯粹是调整构建配置。它验证了一个判断对一个成熟项目来说构建瓶颈往往不在业务代码本身而在于工具的默认配置没有针对项目特点做专门调优。3. 产物体积控制300KB以内的拆包实战3.1 manualChunks把大象关进该关的笼子里前面提到优化前有一个890KB的大vendor包这是最直接的问题。Vite默认会把所有node_modules依赖打成一个独立的chunk这在依赖少的小项目里没问题但像我们这种ECharts、Element Plus、Axios全上的项目vendor包体积直接爆炸。Rollup的manualChunks可以手动控制chunk的划分。我最终采用的拆分策略是这样// vite.config.ts build: { rollupOptions: { output: { manualChunks(id) { if (id.includes(node_modules)) { if (id.includes(echarts) || id.includes(zrender)) { return echarts } if (id.includes(element-plus) || id.includes(element-plus)) { return element-plus } if (id.includes(vue) || id.includes(pinia) || id.includes(vue-router)) { return vue-vendor } if (id.includes(axios)) { return axios } return vendor } } } } }这个配置的逻辑很直观把体积最大且相对独立的库拆成单独chunk比如ECharts一个大包、Element Plus一个大包Vue生态相关的工具放一起。这样做有两个好处一是各chunk可以并行下载二是当某个库升级时其他库的chunk不会因为hash变化而重新下载。拆完之后最大的chunk从890KB降到了380KB左右效果立竿见影。但离我300KB的目标还差一点于是继续做了第二件事。3.2 按需引入让Element Plus和ECharts瘦身Element Plus全量引入是体积失控的最大元凶。一个后台管理系统里你真正用到的组件可能只有表单、表格、弹窗、消息提示这几个但全量引入会把一百多个组件全部打进包里。我用了unplugin-vue-components和unplugin-auto-import这两个插件来解决import AutoImport from unplugin-auto-import/vite import Components from unplugin-vue-components/vite import { ElementPlusResolver } from unplugin-vue-components/resolvers export default defineConfig({ plugins: [ AutoImport({ resolvers: [ElementPlusResolver()] }), Components({ resolvers: [ElementPlusResolver()] }) ] })配置之后你在模板里直接写el-button就行插件会在编译阶段自动按需导入对应的组件和样式不用再手动import。这个方案比用babel-plugin-import的方式更优雅因为它是编译时处理的不依赖额外的Babel插件。ECharts的按需引入稍微麻烦一点。ECharts的包结构非常庞大如果你的项目是用import * as echarts from echarts这种方式引入的那构建出来的ECharts chunk会非常大。正确的做法是用echarts/core配合按需注册// src/utils/echarts.ts import * as echarts from echarts/core import { BarChart, LineChart, PieChart } from echarts/charts import { TitleComponent, TooltipComponent, GridComponent, LegendComponent, DataZoomComponent } from echarts/components import { CanvasRenderer } from echarts/renderers echarts.use([ BarChart, LineChart, PieChart, TitleComponent, TooltipComponent, GridComponent, LegendComponent, DataZoomComponent, CanvasRenderer ]) export default echarts这样只注册了项目里实际用到的图表类型和组件ECharts的chunk从200多KB直接降到80KB左右。这是一个程序员不愿意逐模块注册、想要全部导入的经典诱惑但对一个上线项目来说80KB和200KB的差距就是用户一秒钟的等待时间。3.3 dayjs替换moment用对库比优化配置更有效这个改动严格说不算Vite的配置优化但它是整个体积优化中收益最大的一步。项目里有一个老模块还在用moment.js处理日期而moment.js本身将近70KB而且它是CommonJS模块不利于Tree Shaking。我把所有moment相关代码替换成了dayjs。dayjs的API和moment几乎一致迁移成本极低但体积只有2KB左右。替换完顺手把moment从package.json里移除了这一步直接让项目体积又瘦了近70KB。替换过程中唯一需要注意的坑是moment的时区和语言包处理dayjs需要手动引入对应的语言包和插件import dayjs from dayjs import dayjs/locale/zh-cn import customParseFormat from dayjs/plugin/customParseFormat dayjs.locale(zh-cn) dayjs.extend(customParseFormat)3.4 gzip压缩与nginx联动让传输体积再降一截产物体积优化到一定程度后顺带做了gzip压缩。Vite有现成的插件vite-plugin-compression我配置的是生产环境生成gzip文件不删除源文件import viteCompression from vite-plugin-compression export default defineConfig({ plugins: [ viteCompression({ verbose: true, disable: false, threshold: 10240, // 只压缩大于10KB的文件 algorithm: gzip, ext: .gz }) ] })这里有个容易被忽略的点如果前端只生成了.gz文件但nginx没有开启gzip_static服务器还是会原样返回未压缩的文件。所以必须保证nginx配置里加一行gzip_static on; gzip on; gzip_types text/plain text/css application/json application/javascript application/xml text/xml application/xmlrss image/svgxml;nginx开启后服务器会优先返回.gz文件客户端拿到的是压缩后的内容传输体积再降60%左右。在经过manualChunks拆包和按需引入之后gzip后整体产物大小从680KB降到了280KB左右这个数字已经相当健康了。4. 多环境打包mode与env文件不是你想的那样4.1 深入理解Vite的mode和NODE_ENV很多人在多环境打包时踩坑根本原因是没有搞清楚mode、NODE_ENV和.env文件这三者之间的关系。先说结论vite build默认的mode是productionvite dev默认的mode是development。mode决定了Vite会加载哪个.env文件mode为production时加载.env.productionmode为test时加载.env.test以此类推。但NODE_ENV是另一回事。Vite构建时会把import.meta.env.MODE设成当前的mode但这并不代表process.env.NODE_ENV会自动变成对应的值。如果你在代码里用process.env.NODE_ENV判断环境可能拿到的一直是production。这个问题非常经典我见过不止一个项目在vite build --mode test之后打包出来的代码走的是生产环境逻辑但又在.env.test里配置了测试环境的API地址导致请求域名和生产混在一起功能直接挂掉。4.2 env文件加载规则与优先级Vite加载env文件的规则是有明确优先级的从高到低排列如下文件加载时机.env.local所有场景优先级最高.env.[mode]指定mode时加载.env所有场景优先级最低.env.local看起来像是个常用选项但需要注意如果它是被提交到仓库里的那它就不应该叫.env.local了。Vite有一个隐藏约定.env.local用来到本机覆盖配置用的它不应该进git仓库rear本地调试非常有用。4.3 实战vite build --mode test的正确打开方式我们项目的环境分为本地、测试和生产三套。在package.json里的脚本是这样写的{ scripts: { dev: vite, build:test: vite build --mode test, build:prod: vite build --mode production } }对应的env文件是这样# .env.test VITE_APP_BASE_URL/api/test VITE_APP_ENVtest # 这里可以显式设置NODE_ENV NODE_ENVproduction注意.env.test里我显式写了NODE_ENVproduction。这一步是优化过程中总结出来的经验因为某些第三方库在process.env.NODE_ENV ! production时会把警告信息打进生产包显式设成production可以让这些库在构建时自动把警告代码剔除。如果你在.env.test里不写这一行Vite会自己把NODE_ENV固定为production吗答案是在vite build时Vite会强制将NODE_ENV设为production除非你在env文件里显式覆盖。这正好解释了为什么有人能在.env.test里配置NODE_ENVdevelopment构建时依然会报生产模式的行为。这个行为大多数场景是合理的但如果你真的需要测试环境走开发构建逻辑就需要更复杂的配置了。4.4 最容易翻车的三个细节第一个坑是变量命名。只有以VITE_前缀开头的变量才会被Vite暴露到import.meta.env里其它变量即使写在.env文件里前端代码也拿不到。如果你在.env.test里写了一个API_BASE_URLxxx前端用import.meta.env.API_BASE_URL访问到的一定是undefined。第二个坑是.env.test文件里配置的地址必须是测试环境能访问的。我见过有同事把.env.test里的API地址写成本地localhost打包完成后测试人员一打开页面全部请求404。这个不是技术问题但真的很常见。第三个坑是路由的base路径。如果你的项目部署在子目录下比如https://example.com/admin/在env文件里配置VITE_PUBLIC_PATH/admin/然后在vite.config.ts里读取export default defineConfig({ base: process.env.VITE_PUBLIC_PATH || / })这样测试环境和生产环境可以用同一个构建脚本只是env文件不同部署路径也跟着动态变化。5. 构建报错排查实录三个绕不过去的坎5.1 内存溢出max-old-space-size不是改个数字那么简单项目依赖多了之后我们第一次遇到构建报错是这种情况--- Last few GCs --- [18840:0x1029a8000] 60424 ms: Mark-sweep 2032.4 - 2026.7 (2059.4) MB, 601.6 / 0.0 ms...这就是典型的JavaScript heap out of memory。绝大多数人的第一反应是在package.json里这样改{ scripts: { build: node --max-old-space-size4096 node_modules/vite/bin/vite.js build } }但要注意这个方案在Windows的cmd或者PowerShell下有个经典问题如果你直接在命令行里设置环境变量比如NODE_OPTIONS--max-old-space-size4096 vite buildWindows下会提示node_options 不是内部或外部命令。这就是热搜词里那个错误的全过程。正确且跨平台的做法是使用cross-envnpm install -D cross-env{ scripts: { build: cross-env NODE_OPTIONS--max-old-space-size4096 vite build } }但我想说的是依赖加大内存来解决内存溢出只是治标不治本。内存溢出的深层原因通常是某个库在构建时被大规模转换或者某个chunk太大导致Rollup需要消耗大量内存来处理。我们项目的根本原因是有一个组件库的ESM版本在全量打包时生成了海量的中间代码。后来把那个组件库换成按需引入之后同样的构建脚本不再溢出内存占用反而只有1.5GB左右。5.2 动态导入语法报错Invalid or unexpected token的完整排查链路另一个高频报错是在构建时突然出现[ERROR] Invalid or unexpected token file: /src/views/dashboard/index.vue:12:8这个报错乍一看很懵JS源码里根本看不出来哪里token不对。我当时的排查链路是这样走的第一步先确认报错发生在哪个构建阶段。在构建命令后面加--debug可以看到详细信息确认是Rollup解析阶段报错还是esbuild压缩阶段报错。第二步定位到具体文件后检查第12行附近是否有特殊字符。我们那次的问题是一个Vue组件的script setup里混入了从Word文档复制过来的中文引号导致模板编译器解析失败。第三步如果确认语法没问题那就考虑是不是构建target设置太低导致某些新语法没有被esbuild识别。Vite的build.target默认是modules它对应的浏览器版本比较新。如果你的目标浏览器偏旧有些语法就需要降级。但如果你把target设置成es2015而代码里用了?.和??esbuild会把它们转成兼容代码但偶尔也会因为第三方库对ESM的处理不当而报错。最终这个报错的根因其实是vite.config.ts里一段manualChunks函数中不小心写了一个全角逗号。排查过程花了将近一个小时但根因就是一个标点符号。这件事给我的教训是打包报错先别急着怀疑框架先用最小化复现的方式定位到具体文件和具体行把可疑的标点、字符先换掉试试。5.3 pxtorem对ECharts没起到效果样式转换的优先级冲突ECharts和pxtorem在同一个项目里总是会出现神奇的问题。我们使用了postcss-pxtorem来做移动端适配配置是这样// postcss.config.js module.exports { plugins: { postcss-pxtorem: { rootValue: 16, propList: [*], selectorBlackList: [ignore] } } }但页面里的ECharts图表在大屏上总是文字偏小图表的数量和尺寸也对不上屏。排查后发现ECharts内部生成的canvas是动态计算像素的不走CSS的px转换逻辑但它的容器div被postcss-pxtorem从width: 800px转成了width: 50rem导致图表初始化时的容器宽度被错误计算。解决方案是在postcss-pxtorem的配置里针对图表容器加白名单排除module.exports { plugins: { postcss-pxtorem: { rootValue: 16, propList: [*], selectorBlackList: [ignore, .echarts-container, .chart-] } } }这样ECharts容器内部的px就不会被转成rem图表才能拿到准确的像素宽度。注意这里面有个优先级问题selectorBlackList的规则是只要class名命中就会被排除所以类名设计要足够特殊避免误伤业务样式。5.4 路由懒加载失效后看起来是白屏还有一个场景是路由懒加载写了但首屏依然白屏。我们有一个模块是这样写的const Home () import(/views/Home.vue)这在Vue3 Vite下理论上没有任何问题但如果归纳出的代码中import(/views/Home.vue)的路径包含了某种动态变量比如const view Home const Home () import(/views/${view}.vue)Vite在build时无法预知这个变量会取什么值它只能选择把整个/views目录下的所有文件都打成chunk而不是拆成独立的小chunk。这样做的结果是产物里会出现大量的异步chunk并且加载时机变晚白屏时间反而拉长。正确做法是使用import.meta.glob来显式声明const viewModules import.meta.glob(/views/*.vue) const Home viewModules[/src/views/Home.vue]这样Vite能准确知道当前模块的依赖路径才能正确地生成按需加载的代码也能让打包结果里的chunk划分更精确。6. 持续优化构建趋势监控与团队规范沉淀6.1 把构建优化变成一件可以被监控的事优化做完之后如果不去管它三个月后项目又会重新变回臃肿的状态。我写了一个简单的构建监控脚本每次跑完build之后自动读取dist目录的大小和chunk数量输出到终端// scripts/check-build-size.js import { readdirSync, statSync } from fs import { join } from path const dir ./dist/assets const files readdirSync(dir) let totalSize 0 let totalGzip 0 files.forEach(file { const filePath join(dir, file) const stats statSync(filePath) totalSize stats.size }) console.log([build-size] 构建产物总量: ${(totalSize / 1024).toFixed(1)} KB)并且在CI里加了一条判断如果gzip后的总大小超过500KB构建失败并提示优化产物体积。这样每个开发者在提交代码时都能第一时间感知到自己的改动对包体积的影响而不是等发上线了才发现页面变慢了。6.2 团队规范在代码评审阶段就把问题拦住优化类的改进最怕的不是技术难而是难以持续。我在团队内部推了一些简单的约定实施效果很好新增依赖前先检查包里是否有替代方案体积更小且API兼容的优先任何组件不得在入口文件全局import统一走按需引入路由统一使用import.meta.glob的方式声明避免动态变量导致chunk切割失效每周看一次构建监控脚本的输出发现异常尽早处理这些约定不是硬性制度而是配合代码评审流程来执行的。评审人在review的时候如果看到全量引入的代码完全可以打回并要求改成按需引入理由是“会影响首屏加载体验”。最后聊聊我个人实践中的额外体会优化做到这一步项目规模和生产体验都有了明显的提升。我最大的感受是Vue3 Vite这套组合的上限非常高但前提是你要理解它底层的工作机制。很多人把“优化”等同于“上网找一个配置模板抄下来”但这在工程领域是不够的。每个项目的依赖结构、访问场景、浏览器兼容目标都不一样抄来的配置很可能不但没有效果还会引入新的问题。我建议每一个刚接手Vue3项目的同学第一周不要急着写业务先花点时间把构建配置和产物结构摸透。把vite build的--debug输出看一遍把dist目录里的每个文件打开看看内容你就能对项目的家底一清二楚。知道自己的项目有多少依赖、多少代码是真正会用到的优化方向自然就清晰了。这篇经验我会持续更新后续如果踩到新的构建相关的坑或者发现了更优的配置方案会继续补充进来。如果你在自己的项目里也遇到过有意思的构建问题欢迎一起讨论。