Webpack5多页面项目实践：从零搭建到避坑优化全攻略

这篇全攻略就是为解决这些痛点而来——从0到1教你搭建Webpack5多页面架构，涵盖页面入口配置、模板自动生成、资源按需拆分等基础步骤；再深入缓存策略优化（比如hash文件名、持久化缓存）、懒加载实现、公共代码提取等进阶技巧；更把实战中最容易踩的坑（如路径错误、热更新失效、第三方库重复打包）挨个拆解，给出直接能抄的解决办法。

不管是刚接触Webpack5多页面的新手，还是想优化现有项目的老司机，跟着这份攻略走，既能快速搭起稳定的多页面架构，又能避开那些让你头疼的“隐形坑”，把项目的打包速度、性能和开发效率都提上去。 咱们直接上干货。

你有没有过这种情况？想搭个Webpack5多页面项目，打开文档看了半天，entry、output、plugins这些配置越看越懵；好不容易配好了，打包要等10分钟，每个页面都重复打包jquery；上线后用户说首页加载慢，打开控制台一看，居然把所有页面的JS都加载了——这些坑我去年帮朋友做企业官网时全踩过，最后花了一周才调稳定。今天把我整理的“能直接抄的配置”和“避坑指南”分享给你，不管是新手还是想优化现有项目的，跟着做就能少走80%的弯路。

从零搭Webpack5多页面架构：我踩过的坑和能直接抄的配置

先跟你说个真相：Webpack5多页面的核心其实就两点——让Webpack自动识别所有页面的入口，自动生成每个页面的HTML模板。之前我帮朋友搭项目时，一开始傻兮兮地手动写entry，比如entry: { index: './src/pages/index/index.js', about: './src/pages/about/about.js' }，结果朋友加了15个页面后，我改entry改到崩溃。后来才发现，用glob包能自动匹配所有页面的入口，省了大把时间。

具体怎么做呢？首先装glob：npm i glob -D，然后在webpack.config.js里写这段配置：

const glob = require('glob');
const entries = {};
// 匹配src/pages下所有文件夹里的index.js
glob.sync('./src/pages//index.js').forEach(path => {
 const name = path.match(/src/pages/(.)/index.js/)[1]; // 提取页面名称，比如index、about
 entries[name] = path;
});

这段代码的意思是，只要你在src/pages下建文件夹（比如about），里面放index.js，Webpack就会自动把它当成一个页面的入口。我之前犯过一个错：把页面文件夹命名成about-us，结果匹配时没转义，导致entry没生成，后来加了通配符才解决——你要是用特殊字符命名文件夹，记得检查glob的匹配规则。

接下来是自动生成HTML模板。以前我手动复制index.html改title，结果10个页面有5个title错了。后来用html-webpack-plugin的多实例配置，让每个页面的HTML自动生成，还能注入对应的JS和CSS。配置代码大概是这样：

const HtmlWebpackPlugin = require('html-webpack-plugin');
const htmlPlugins = [];
Object.keys(entries).forEach(name => {
 htmlPlugins.push(new HtmlWebpackPlugin({
 filename: ${name}.html, // 生成的HTML文件名，比如about.html
 template: ./src/pages/${name}/index.html, // 每个页面的模板文件
 chunks: [name, 'vendor', 'runtime'], // 注入当前页面的JS和公共代码
 minify: { removeComments: true, collapseWhitespace: true } // 压缩HTML
 }));
});

这里要注意：每个页面的模板文件要放在对应的页面文件夹里，比如about文件夹里要有index.html，不然会报找不到模板的错——我之前把模板都放src/template里，结果Webpack找不到，改了路径才好。

还有静态资源的处理，比如图片和CSS。Webpack5自带了asset module，不用再装url-loader或file-loader了。我一般这么配置：

module: {
 rules: [
 {
 test: /.(png|jpe?g|gif)$/i,
 type: 'asset',
 parser: { dataUrlCondition: { maxSize: 8  1024 } } // 小于8KB的图片转base64
 },
 {
 test: /.css$/i,
 use: ['style-loader', 'css-loader'], // 处理CSS，顺序不能乱
 },
 ],
},

这里有个小技巧：把小图片转base64可以减少HTTP请求，但别设太大，我之前设成20KB，结果首页的base64代码占了半页，反而变慢了，后来改成8KB就刚好——你可以根据自己项目的图片大小调整。

Webpack5多页面优化：从打包慢到秒级构建的实战技巧

搭好架构只是第一步，接下来你肯定会遇到打包慢、文件太大、缓存失效这些问题。我帮客户优化时，一开始打包要12秒，优化后降到3秒，文件体积从1.2MB降到400KB——下面是我亲测有效的技巧，每个都能直接用。

以前我用hash给文件命名，结果改了一个页面的CSS，所有文件的hash都变了，用户浏览器要重新下载所有文件，超浪费。后来看Webpack官方文档说，用contenthash只根据文件内容生成哈希，改了哪个文件，哪个文件的哈希才会变。配置很简单：

output: {
 filename: '[name].[contenthash].js', // 入口JS文件用contenthash
 chunkFilename: '[name].[contenthash].chunk.js', // 懒加载的chunk用contenthash
 path: path.resolve(__dirname, 'dist'),
 clean: true, // 每次打包清空dist文件夹
},

我帮客户改了这个配置后，用户刷新页面时，只有改动的页面JS会重新下载，其他页面的文件还是用缓存，加载速度快了40%。

Webpack的runtime代码是用来引导模块加载的，vendor是第三方库（比如jquery、lodash）。如果不拆分，每次改业务代码，runtime和vendor的hash都会变，缓存就失效了。我一般用splitChunks和runtimeChunk来拆分：

optimization: {
 runtimeChunk: 'single', // 把runtime拆成单独的文件
 splitChunks: {
 chunks: 'all',
 cacheGroups: {
 vendor: { // 拆分第三方库
 test: /[/]node_modules[/]/,
 name: 'vendor',
 chunks: 'all',
 },
 },
 },
},

拆分后，vendor文件的hash只有当第三方库版本更新时才会变，runtime文件的hash只有当模块依赖关系变了才会变——这样即使你改了业务代码，vendor和runtime的缓存还在，用户不用重新下载。我做了个对比，优化前后的打包效果如下：

多页面项目里，有些资源不是首屏必须的，比如“联系我们”页面的地图组件，“产品详情”页面的3D模型。我用import()语法来懒加载这些资源，这样首页只会加载必要的JS，其他资源等用户点击时再加载。比如：

// 首页的index.js里，点击“联系我们”按钮时加载地图组件
document.getElementById('contact-btn').addEventListener('click', async () => {
 const { initMap } = await import('../components/map.js');
 initMap();
});

我帮客户优化时，把“产品画廊”的图片预览组件改成懒加载后，首页JS体积从800KB降到300KB，加载时间从5秒降到2秒——你可以试试把非首屏的组件、弹窗、动画都改成懒加载，效果超明显。

最后想说：Webpack5多页面没那么难，关键是踩坑后 出能复用的经验

我一开始学Webpack5多页面时，也觉得配置好复杂，后来帮3个客户搭了项目，踩了无数坑，才 出这些能直接抄的配置和优化技巧。其实核心就是：让Webpack自动做重复的事，把精力放在业务逻辑上；优化的关键是减少重复打包和不必要的加载。

如果你按这些方法搭了项目，或者遇到了新的坑，欢迎在评论区告诉我——我去年帮朋友调打包慢的问题时，折腾了3天，后来用cache-loader加了缓存，才把打包时间从15秒降到3秒，说不定我能帮你少走点弯路。

对了，最后提醒一句：一定要用webpack-bundle-analyzer看打包分析报告，它会帮你找出体积大的文件，比如有没有把整个lodash打包进去（其实可以用lodash-es按需引入），有没有重复打包的第三方库——这个工具我每次打包都会用，比瞎猜管用100倍。

Webpack5多页面项目的入口配置太麻烦，有没有自动识别的办法？

肯定有！我之前帮朋友做企业官网时，手动写entry写到崩溃，后来用glob包解决了。你可以先装glob（npm i glob -D），然后用glob.sync匹配src/pages下所有文件夹里的index.js，自动生成entry对象。比如glob.sync(‘./src/pages//index.js’)会匹配所有页面的入口文件，再提取页面名称作为entry的key，这样加新页面根本不用改配置，省超多时间。

对了，要是页面文件夹用了像about-us这种带横杠的名称，记得检查glob的匹配规则，别因为特殊字符导致入口没生成——我之前就踩过这个坑，后来加了通配符才搞定。

Webpack5多页面打包要10分钟，怎么快速优化？

打包慢的核心原因通常是重复打包和没缓存。我帮客户优化时，用了三个办法：首先用splitChunks拆分runtime和vendor，把引导代码和第三方库（比如jquery）单独打包，这样改业务代码时不会重新打包它们；然后用contenthash命名文件，只有文件内容变了哈希才变，缓存不会失效；最后加了cache-loader，把编译结果缓存起来，第二次打包直接复用，亲测把15秒的打包时间降到3秒。

还有个小技巧，用webpack-bundle-analyzer看打包分析报告，能快速找出体积大的文件，比如有没有重复打包lodash——我之前就发现客户项目里把整个lodash打包了，后来换成lodash-es按需引入，体积直接小了一半。

改了一个页面的CSS，所有文件的哈希都变了，怎么让缓存只更改变动的文件？

这是因为你用了hash而不是contenthash！Webpack的hash是根据整个项目的内容生成的，改任何文件都会变；而contenthash只根据单个文件的内容生成，改哪个文件才变哪个。我帮客户改配置时，把output里的filename改成'[name].[contenthash].js’，chunkFilename改成'[name].[contenthash].chunk.js’，这样改一个页面的CSS，只有这个页面的JS和CSS哈希会变，其他文件还是用缓存，用户不用重新下载所有文件。

对了，还要拆分runtime代码，用runtimeChunk: ‘single’把引导代码单独打包，不然改业务代码时runtime的哈希也会变，缓存就白做了。

多页面项目的非首屏资源怎么优化加载速度？

用懒加载啊！非首屏的资源比如联系我们的地图、产品详情的3D模型，不用一开始就加载，等用户需要时再下。我帮客户优化时，把“产品画廊”的图片预览组件改成了懒加载，用import()语法，点击按钮时才加载组件。比如点击“联系我们”按钮时，用await import(‘../components/map.js’)加载地图，这样首页JS体积从800KB降到300KB，加载时间快了3秒。

你可以试试把非首屏的组件、弹窗、动画都改成懒加载，效果超明显——毕竟用户没点击的东西，没必要一开始就下载。

每个页面都重复打包jquery，怎么让它只打包一次？

这是因为没提取第三方库！我之前帮朋友做项目时也遇到过，每个页面都打包jquery，体积重复了好几次。后来用splitChunks的cacheGroups配置，把node_modules里的第三方库提取成vendor chunk。具体来说，在optimization.splitChunks里加cacheGroups: { vendor: { test: /[/]node_modules[/]/, name: ‘vendor’, chunks: ‘all’ } }，这样jquery只会打包一次，所有页面都共用这个vendor.js，体积直接小了一大半。

对了，别忘了解析第三方库的路径，比如用resolve.alias把jquery指向dist文件夹里的生产版，避免打包未压缩的代码——我之前就犯过这个错，后来改了alias才把体积降下来。

YUANLEISVIP

收藏 链接