去年这个时候我在elpis-core项目里推进里程碑1把基础框架跑通之后心里还挺美。结果里程碑2的需求一出来我就有点笑不出来了要在同一套代码仓库里同时维护十几个相对独立的页面每个页面都要能单独开发、单独构建、单独部署而且公共代码还要尽量复用——这不就是要做一趟正经的webpack多页工程化么。当时我花了好几个晚上研究配置踩了不少坑也把网上能搜到的资料翻了个遍最后才把这些页面顺利纳入同一个构建体系。这篇总结就是把我当时在做elpis-core里程碑2时关于webpack多页工程化的完整思考和实践记录下来从选型、核心配置到排查踩坑写给同样在搞多页工程化或者准备把老项目改造成多页构建体系的朋友作参考。我默认看这篇文章的你已经对webpack的基础概念比如entry、output、loader、plugin有基本了解但还没有真正把多页应用MPA的构建体系完整搭过一遍。文章里的所有配置和思路都是基于elpis-core这个真实项目具体参数和目录结构可能和你的项目不完全一样但方法论和排查方向是通用的。1. 十几张页面塞进一个构建体系的起点——为什么选择webpack多页方案1.1 elpis-core里程碑2到底要解决什么问题先交代一下背景。elpis-core在里程碑1阶段其实只做了一个单页的demo工程当时的构建配置非常简单入口就是一个main.js配合一个HtmlWebpackPlugin构建产物也就一个index.html加一堆静态资源。但到了里程碑2业务方要求把运营活动页、落地页、独立的信息展示页都整合进这个项目里页面数量迅速膨胀到十几个而且这些页面之间有共同的视觉规范和工具函数却属于不同的业务线需要独立排期、独立上线。如果继续沿用单页应用的思路把这些页面全塞进一个SPA里问题立刻就来了路由由前端控制任何一次上线都会影响到所有页面各自业务方的代码在同一个运行时里互相耦合边界很容易模糊构建产物只有一个入口首屏加载的冗余代码会越来越多。所以对于elpis-core的诉求多页应用MPA几乎是必然的选择——在构建层面保证页面隔离在运行时层面让每个页面各走各的入口公共依赖再通过打包配置抽离出来。1.2 多页应用MPA与单页应用SPA的取舍逻辑技术选型最忌讳只看概念不看场景。我把elpis-core当时的情况和SPA、MPA两种方案做了一遍对比维度单页应用SPA多页应用MPA路由归属前端Router控制每个页面一个独立HTML由服务端或静态部署控制页面隔离性弱所有页面共享运行时强页面间天然隔离一个崩了不影响其他页面上线部署一次构建整体上线任何页面改动都触发全量发布每个页面独立构建独立发布改动只影响目标页面首屏性能依赖路由级拆包懒加载不到位容易冗余天然只有当前页面代码首屏体积更容易控制开发成本前期成本低后期复杂度随页面规模上升前期需要配置好工程化后期维护成本可控团队协作多人改同一个入口合代码压力大页面间代码相互独立协作边界清晰从表格能看出SPA的优势在于交互连续性页面之间是无刷新跳转而MPA的优势在于隔离性和部署灵活性。elpis-core的页面大多是从外部落地页跳转进来的用户根本不需要在页面内部做路由级的连续跳转甚至不少页面是访问完就关这种场景。这种情况下SPA的核心优势完全用不上反而要忍受它的隔离性问题。1.3 在一堆构建工具里为什么选webpack而不是vite现在提到构建工具绕不开vite尤其是热词里带着vue3 vite 和webpack的对比。我自己也在小项目里深度用过vite开发期那种秒级启动和HMR体验确实爽如果elpis-core是一个全新的纯前端SPA项目我大概率会直接选vite。但多页工程化这个场景我最终选择了webpack原因有几个。第一多页工程化要处理的核心问题其实是怎么管理多个HTML入口、怎么抽公共代码、怎么控制各页面的chunk引用。这套事情webpack经过社区十年沉淀生态已经非常成熟不管是HtmlWebpackPlugin的灵活配置还是splitChunks的各种边界场景都有大量现成实践和踩坑文档。vite的插件机制也很优秀但在多页这种偏传统服务端输出HTML的场景里webpack的历史包袱反而成了优势——它把该遇到的问题都暴露过了解法也都被大家验证过了。第二elpis-core项目里有一部分老代码是通过loader方式引用的比如一些直接引入静态资源的第三方库webpack的loader机制对这种改造场景兼容性最好迁移成本低。vite基于原生ESM在老代码的依赖处理上经常要额外配置optimizeDeps或者写插件去兼容反而增加工作量。第三也是比较现实的一点项目团队成员对webpack的配置体系更熟悉遇到问题时排查路径更短。多页工程化本身就比单页多了一层复杂性如果构建工具的调试还得从头学这个成本在里程碑2的时间压力下是无法接受的。当然如果你是一个全新项目团队又都是vite熟手选vite做多页完全没有问题。我这里不是踩一捧一只是把elpis-core当时的决策逻辑摊开方便你在自己的项目里做判断。2. 多入口配置与HtmlWebpackPlugin动态化——把工程化落到实处2.1 多入口配置从写死一个entry到扫描目录生成entrywebpack多页工程化的第一个硬骨头就是把原本写死的单入口改成多入口。最直白的做法是在entry里手动把每个页面的入口路径写出来比如// webpack.config.js module.exports { entry: { pages/login/index: ./src/pages/login/index.js, pages/home/index: ./src/pages/home/index.js, pages/detail/index: ./src/pages/detail/index.js } };但这种方式一旦页面数量超过十个就会变得很难维护。新增一个页面要改配置文件删除一个页面要改配置文件而且手写路径还容易因为大小写、目录层级问题找半天。elpis-core有十几个页面后续可能还会继续增加我需要一个能自动发现页面的方案。我当时的做法是约定目录结构然后通过glob模块扫描入口文件。约定比配置更重要我规定每个页面的代码都放在src/pages/页面名/index.js模板放在同目录下的index.html这样扫描逻辑就可以统一处理// build/utils.js const glob require(glob); const path require(path); const PAGE_ROOT path.resolve(__dirname, ../src/pages); // 找到所有包含 index.js 的页面目录 function getPageEntries() { const files glob.sync(${PAGE_ROOT}/*/index.js); const entries {}; files.forEach((file) { const pageName file.match(/pages[/\\]([^/\\])[/\\]index\.js$/)[1]; entries[pageName] file; }); return entries; }这样做之后新增页面就变成了创建一个目录放上index.js和index.html这么简单不需要再碰webpack配置。这种动态化的思路在多页工程化里是核心中的核心——不是让工程去适配每个页面而是让统一约定去驱动工程的一键生成。2.2 HtmlWebpackPlugin动态生成每个页面带走自己需要的chunks多页配置的第二个关键动作是HtmlWebpackPlugin的实例化。很多刚接触多页的同学会把每个页面的HtmlWebpackPlugin写成一个单独的对象页面一多配置冗长得没法看。正确做法是根据扫描到的页面入口动态生成插件实例// build/webpack.common.js const HtmlWebpackPlugin require(html-webpack-plugin); const { getPageEntries } require(./utils); const entries getPageEntries(); const htmlPlugins Object.keys(entries).map((pageName) { return new HtmlWebpackPlugin({ template: path.resolve(__dirname, ../src/pages/${pageName}/index.html), filename: ${pageName}.html, chunks: [common, pageName], // 动态设置页面的 title title: pageName, // 把页面需要的参数传回模板 templateParameters: { pageName } }); });这里的chunks字段是重中之重。webpack默认会往每个html注入所有入口的chunk但多页场景下每个页面只需要自己的业务代码加上公共依赖。我把common这个chunk和当前页面名的chunk一起注入保证公共代码只加载一次页面代码按需加载。要注意一点在早期版本的HtmlWebpackPlugin里chunks的写法是数组如果你映射了splitChunks抽出来的vendor还要把vendor加进去。在elpis-core里我的common是专门给多页面共享的业务逻辑和组件抽的chunkvendors则是给第三方库抽的chunk这两个我会在下一节详细展开。2.3 公共依赖抽取splitChunks怎么配才不算过度优化多页应用如果不做公共代码抽取每个页面的bundle都会包含自己引用的第三方库和公共组件最后的结果是每打开一个新页面浏览器都要重新下载一遍相同的vue/react和工具函数体积和缓存体验都非常糟糕。elpis-core项目里有十几个页面如果每个页面的vendor都打一遍构建产物体积会膨胀好几倍。我用splitChunks把公共依赖拆成几个层次的chunk。配置大致如下// build/webpack.common.js module.exports { optimization: { splitChunks: { chunks: all, cacheGroups: { // 第三方依赖单独打成一个vendor vendors: { test: /[\\/]node_modules[\\/]/, name: vendors, priority: -10 }, // 项目内的公共代码单独打成一个common common: { name: common, minChunks: 2, priority: -20, test: /src[\\/]/ } } } } };这里的核心参数是minChunks它控制的不是最少被引用几次而是被几个不同入口引用。在elpis-core里我把common的minChunks设为2也就是说一个模块只要被两个页面都引用了就把它抽到commonchunk里。这样既保证了公共代码的复用又不会因为抽得太细导致首屏无谓加载公共文件。但是这里有个教训splitChunks不是分组越多越好。刚开始我想把公共组件和公共工具函数分开抽于是又加了一个utils缓存组结果构建完成后发现一个还不到1KB的工具文件被单独抽成了chunk每个页面加载时都多了一次HTTP请求。后来自查才发现这种过度拆分反而让页面性能变差了。对于几个K的小文件合并到common里远比重启一个请求要好。多页工程化的第一原则应该是按体积和复用度合理分层而不是像搞收藏一样把chunk分得越细越好看。3. 开发体验与构建速度之间找平衡——devServer、持久化缓存与打包优化3.1 devServer在多页模式下怎么配才不用F5到吐多页应用的devServer配置和SPA有一个很大的区别SPA只需要配置historyApiFallback就能把所有路由指向index.html但多页应用每个页面都是独立的HTML如果直接访问http://localhost:8080/pages/home/index.htmldevServer默认不一定能正确返回对应模板。elpis-core里的处理方式是在webpack-dev-server的配置里明确设置devServer.static指向工程根目录并且确保HtmlWebpackPlugin输出的filename和真实访问路径是一致的// build/webpack.dev.js const devServer { static: { directory: path.resolve(__dirname, ../dist), publicPath: / }, port: 8080, hot: true, open: /pages/home/index.html, historyApiFallback: false };这里historyApiFallback必须设为false。很多从SPA转过来的同学会习惯性把它开着结果就是不管访问哪个页面都给你返回第一个HTML模板页面内容全部串了。多页应用在开发期是靠真实HTML路径去访问页面的不需要也没有意义去做前端路由回退。另外多页模式下open可以直接指向一个具体的页面入口比如我配了open: /pages/home/index.html这样npm run dev一启动就能直接看到主页省得每次手动拼接路径。3.2 持久化缓存把构建时间从四十多秒压到个位数webpack的构建速度在多页场景下是绕不开的痛点一开始elpis-core的构建时间大概在41秒这个速度在里程碑1只有一个页面的时候还能接受但页面多了以后每次改一行代码都要等半分钟才能看到效果开发效率断崖式下降。我做的第一个优化就是引入webpack的持久化缓存// build/webpack.common.js module.exports { cache: { type: filesystem, buildDependencies: { config: [__filename] }, cacheDirectory: path.resolve(__dirname, ../node_modules/.cache/webpack) } };这是webpack 5原生提供的能力配置完成后相同的构建输入直接走缓存不再重复执行loader和插件解析逻辑。实测下来第二次及之后的冷启动构建从41秒降到8.3秒日常热更新的变化就更明显了。这里要注意buildDependencies参数它告诉webpack哪些文件发生变化时需要让缓存失效。在elpis-core里我把__filename即webpack配置文件本身加了进去只要配置改动缓存自动作废。如果不小心改了配置却没有配置这个字段很容易出现改了配置但效果不生效的诡异问题。3.3 打包优化线程、压缩、gzip到底先做哪个打包优化的优先级我觉得应该按投入产出比来排。elpis-core的优化顺序是这样的第一优先是cache持久化因为它是开发期效率提升最快的前面已经说过构建时间的变化。第二优先是loader的include精确范围比如babel-loader只处理src目录不对node_modules做转译// build/webpack.common.js module.exports { module: { rules: [ { test: /\.js$/, use: babel-loader, exclude: /node_modules/ } ] } };这里exclude比include更省事一些但效果一样。elpis-core里因为src总共也没多少文件所以收益有限如果你项目里src文件数量很多建议用include: [path.resolve(__dirname, ../src)]加exclude双保险。第三优先是TerserPlugin的并行压缩和CssMinimizerPlugin。webpack 5生产模式默认会调用TerserPlugin做压缩但多页场景下chunk数量多压缩过程会明显拉长构建时间所以我在生产配置里显式开启了并行// build/webpack.prod.js const TerserPlugin require(terser-webpack-plugin); const CssMinimizerPlugin require(css-minimizer-webpack-plugin); module.exports { optimization: { minimize: true, minimizer: [ new TerserPlugin({ parallel: true }), new CssMinimizerPlugin() ] } };parallel: true会让TerserPlugin利用操作系统的多核并行压缩JS多页项目chunk多到一定量级后这个配置带来的时间收益非常明显。至于thread-loader我在elpis-core里没有用它因为项目的babel转译量不大多线程的启动和通信成本反而可能抵消收益。这个要根据团队实际项目的文件数量和转译压力来评估不要盲目堆配置。4. 真实打包过程中踩过的坑——从翻车到修复的完整记录4.1 部署上线后资源全部404publicPath这个坑我记一辈子elpis-core里程碑2第一次测试部署的时候构建完把文件扔到服务器子目录结果首页能打开但JS和CSS全部报了404。当时第一反应是服务器配错了排查了半天nginx配置也没有发现问题后来打开浏览器开发者工具一看script标签里的src路径是/assets/js/chunk-xxx.js根路径而实际部署的目录是/elpis/xxx/两级目录没对上。问题根源就是webpack的output.publicPath。默认情况下publicPath是/代表所有静态资源都从域名根路径加载但这是针对部署在域名根目录的场景。elpis-core实际部署在子目录下必须把publicPath改成相对路径或者明确指定为子目录// build/webpack.prod.js module.exports { output: { publicPath: /elpis/xxx/ } };后来我用的是相对路径方案也就是publicPath: ./这样构建出来的HTML里资源路径会基于当前HTML所在的目录去解析部署到任意子目录都不会出问题。当然相对路径方案有一些需要注意的地方比如html文件如果放在CDN上和静态资源不在同一个域名相对路径就会失效。所以在elpis-core里我的处理是区分场景静态部署在服务端子目录走相对路径走CDN的时候再环境变量注入完整域名。这里要提醒大家排查资源404的时候第一步不是看服务器而是先看构建产物里的HTML资源引用路径对不对。多页应用页面多一个页面资源路径错了还不像SPA那样会全局暴露很难一次性发现。4.2 splitChunks抽出了公共代码但页面引用了不存在的chunk第二个印象深刻的问题是配置好splitChunks之后生产构建报了一个警告某个页面的HTML引用了commonchunk但这个chunk没有构建出来。这个问题的出现非常隐蔽。当时我的HtmlWebpackPlugin里给每个页面都传了chunks: [common, pageName]但由于某个页面的入口文件内容非常简单它没有引用任何公共模块而splitChunks的common缓存组要求至少被2个入口引用最终webpack就不会生成common这个chunk。可我的HTML模板还是硬编码了要引入common于是构建出来的HTML引用了一个不存在的chunk。排查链路是这样的先看构建日志发现那个warning指向的是html-webpack-plugin的chunk引用再检查dist目录确实这个页面目录下没有common.js回头看这个页面的源码果然它没有任何公共依赖。解决方案也不复杂在HtmlWebpackPlugin里先判断一下这个页面是否需要commonchunk如果需要就传给chunks不需要就不传const chunkList [vendors, pageName]; // 如果该页面引用了公共代码再把common加进去 if (shouldIncludeCommon(entries[pageName])) { chunkList.unshift(common); }这个坑告诉我多页工程化里不同页面的依赖结构差异非常非常大不能想当然地认为所有页面都长一个样子。4.3 CSS抽离后样式顺序错乱一排低了半天elpis-core里页面虽然相互独立但都引用了公共的样式文件。我把CSS统一用MiniCssExtractPlugin抽离结果上线后发现某个页面按钮样式被覆盖了边框、圆角全都对不上。一步步排查到最后发现是公共样式和页面样式的引入顺序在某些页面里颠倒了。原因是抽离CSS之后多个页面共享同一个common.css而webpack对CSS顺序的保证是基于每个模块的依赖顺序的一旦某个页面在没有引用公共样式的情况下先加载了页面自己的样式后续公共样式又被加载进来覆盖顺序就不好控制了。解决办法是在CSS的cacheGroup里明确把公共样式的优先级控制住并且在页面入口JavaScript里严格按先公共后业务的顺序import样式文件。这里有一个很实用的经验多页项目的公共CSS最好单独拆出来不要和业务CSS混在一个chunk里这样既能稳定顺序也能让多个页面真正共享同一个样式缓存文件。4.4 tree shaking失效一个工具函数把整个文件带进了最终产物最后一个坑出现在做体积优化的时候。elpis-core里有个工具文件utils/format.js里面导出了好几个工具函数但某个页面只用了其中一个formatPrice我本以为tree shaking会把其他没用的函数摇掉结果一查构建产物整个format.js的内容全打进去了体积白白多出十几KB。排查过程比较曲折一开始怀疑babel配置问题查了半天preset-env有没有开着modules: false。后来发现问题出在package.json里的sideEffects字段上。elpis-core的package.json一直没配sideEffects默认情况下webpack会认为所有模块都有副作用因此不敢摇树。虽然babel-loader会转译ES模块但只要sideEffects: false没配上tree shaking就是摆设。我的处理方式是在package.json里明确声明{ sideEffects: [ *.css, *.scss ] }这里把CSS文件排除在tree shaking之外因为CSS是典型的副作用模块不能被摇掉。配好之后再构建体积明显下降。这个坑的教训是多页工程化里公共工具函数的按需引入依赖tree shaking而tree shaking生效的前提不是用了ES Module而是sideEffects要配置正确。很多项目迁移webpack 5之后tree shaking不生效十有八九是这个字段没设置。5. 里程碑2复盘当前成果、遗留问题与后续扩展方向里程碑2收尾的时候我拉了一版数据和里程碑1刚做完单页demo时做对比指标里程碑1单页demo里程碑2多页工程化页面数量113构建产物总量约980KB约4.2MB去掉vendors后各页面平均体积约980KB约36KB/页冷启动构建时间约14秒约41秒开启持久化缓存后二次构建约11秒约8.3秒单页面独立部署不支持支持看了这个表我觉得里程碑2的核心目标算是达成了页面隔离性有了、独立部署能力有了、公共代码也抽出来了。但我不打算把话说得太满因为过程中暴露出来的问题也很明确。第一个遗留问题是懒加载还不够彻底。虽然每个页面本身是独立的入口但页面内部的模块加载还是全量同步的比如运营活动页里有些炸屏动画和埋点统计的代码完全可以用动态import()拆成异步模块。这个问题我计划在里程碑3来解决动态import配合魔法注释可以给webpack明确的chunk命名进一步细化页面内部的加载粒度。第二个遗留问题是公共样式的拆分还不够细致。目前elpis-core是把所有公共样式打成一个common.css随着业务方增多这个文件会越来越臃肿。后续可以考虑按业务线拆或者用css modules来做局部作用域避免样式互相污染。这块涉及的业务约定比较多需要和前端团队再对一轮。第三个遗留问题是构建日志的友好度。现在13个页面构建输出还比较简洁如果后面页面继续增长到几十个webpack默认的构建输出会非常轰炸视觉。我当时已经计划配置friendly-errors-webpack-plugin但因为优先级不够高没有在里程碑2里做。说回这段工程化实践我个人最大的感受是所谓多页工程化不只是一份webpack配置文件的事更是一套关于目录约定、公共依赖边界、团队协作规则的体系。配置写得好只是第一步真正让工程变得可持续的是后续每一次新增页面时能否做到零配置接入以及每次页面异常时能否快速定位问题。如果你也在做类似的多页项目建议先把目录结构和公共代码边界想清楚再回头细化webpack配置否则很容易陷入今天加个loader明天调个splitChunks的无限被动中。我把这套配置和踩坑记录从自己的项目笔记里重新整理了一遍发布出来希望能让正在走同一条路的人少踩几个我踩过的坑。如果真的帮到你那这趟里程碑2的折腾就值了。
