webpack5前端工程化实战：从构建原理到性能优化

我一直觉得，前端工程化这件事，90%的团队其实卡在了同一个地方：不是不会装依赖，而是搞不清楚手里的构建工具每一步到底在干什么。你问他webpack怎么配置，他能从网上粘一份几百行的配置下来；你问他为什么这么配、删掉哪段会出问题、改个参数能带来什么影响，他大概率答不上来。这种状态在面对webpack5的时候尤其危险，因为webpack5不是简单的版本号升级，它的缓存机制、资源模块、模块合并策略全部重做了，老一套“网上复制配置”的打法已经不太好使。

这篇文章不会给你一个“复制粘贴就能跑”的脚手架Demo，那没有任何意义。我想做的是把webpack5搭建前端工程化的底层逻辑拆开讲透，从项目骨架一步步建起来，到开发阶段的体验优化，再到生产构建的体积和速度调优，最后再聊几个我自己和团队在迁移过程中踩过的坑。全程有配置、有原理、有实测数据，适合那种被脚手架保护得太久、想真正搞懂构建工具的前端同学，也适合正在准备从webpack4往webpack5迁移的团队。

1. 为什么是webpack5：它解决的不只是“能打包”的问题

先说一个很多人没意识到的事实：webpack4当时真正让人头疼的不是配置复杂，而是构建速度和缓存策略实在太拉胯。一个中等规模的项目，冷启动构建跑个三四十秒是常态，热更新稍微改个组件都要等好几秒，团队十几个人一起开发的时候，每天浪费在等构建上的时间折算下来非常夸张。webpack5这次升级，最核心的改进恰恰就打在两个痛点上：持久化缓存和更聪明的模块处理。这也是我建议新项目直接上webpack5的最大理由。

1.1 持久化缓存：二次构建速度的量变到质变

webpack4时代我们做缓存怎么做？用cache-loader、hard-source-webpack-plugin，或者干脆不用。这些方案多少都有些问题，比如hard-source-webpack-plugin在webpack4后期基本处于半维护状态，遇到webpack小版本更新就容易报错，环境一变缓存就失效，好几个同事被它坑过之后直接在团队里禁用。

webpack5直接把文件系统缓存做进了内核，配置文件里开启方式特别简单：

javascript复制module.exports = {
  cache: {
    type: 'filesystem', // 还支持 'memory'，但生产环境建议用 filesystem
    buildDependencies: {
      config: [__filename], // 配置文件本身变化时，缓存自动失效
    },
  },
};

这个配置对开发体验的影响非常大。我实测过一个包含了大概80个业务页面的中后台项目，webpack4冷启动构建耗时在42秒上下，迁移到webpack5并开启文件系统缓存之后，第二次构建直接掉到了9秒，前后差不多有五倍的差距。而且webpack5的缓存不是那种“缓存了就不管对错”的简单方案，它会自动监听文件内容变化，模块内容变了就重建对应部分，别的模块直接走缓存，粒度做得非常细。经历过webpack4时代“缓存一旦出错就得清空node_modules/.cache再重构”的同学，应该能理解这种改进有多宝贵。

1.2 资源模块：少装一整套文件处理loader

webpack4时代处理图片、字体、文本文件，需要分别配置file-loader、url-loader、raw-loader，还要注意loader之间的优先级和配置顺序，很容易出问题。webpack5直接内置了Asset Modules，取代了这三个loader的位置。现在的配置长这样：

javascript复制module: {
  rules: [
    {
      test: /\.(png|jpe?g|gif|webp|svg)$/,
      type: 'asset',
      parser: {
        dataUrlCondition: {
          maxSize: 8 * 1024, // 小于8KB的图片转成base64内联，大于8KB的走单独文件
        },
      },
    },
    {
      test: /\.(woff2?|eot|ttf|otf)$/,
      type: 'asset/resource',
      generator: {
        filename: 'fonts/[name].[hash:8][ext]',
      },
    },
  ],
},

type: 'asset'是灵活模式，会按照maxSize的阈值自动决定是内联base64还是输出为独立文件；type: 'asset/resource'则是行为等价于原来的file-loader，直接把文件发射到输出目录；还有type: 'asset/inline'，跟前者的区别是强制所有文件都内联，一般很少单独用。依赖少了，配置也薄了，这一块对于新手来说心智负担减轻了很多。

1.3 模块ID和tree shaking的改进

webpack4的moduleIds默认使用数值ID命名模块，只要模块加载顺序变一下，最终生成的chunk里所有模块ID可能全部错位，导致缓存失效。之前热门项目里经常出现“我只是加了一个import，结果所有文件的hash都变了”的尴尬状况。webpack5把moduleIds和chunkIds的默认值改成了确定性算法，基于模块路径生成相对稳定的ID，这样只要文件内容不变化，构建出的hash就不会随意变化。

另外webpack5也进一步强化了tree shaking的能力。它现在能够更激进地分析ES Module的副作用，把没有用到的导出彻底剔除。比如一个工具函数库文件里导出了十个函数，业务代码只用到其中两个，webpack5配合sideEffects: false可以把剩余八个函数的代码全部从打包结果中移除。这一点从“能跑”到“性能优化”的帮助是实打实的，后面在第4章生产构建优化里我会单独再展开。

1.4 为什么不直接用vite或者rollup

这个问题几乎每次聊webpack都会被问到。我的看法是：vite在开发模式下的ESM按需加载体验确实好，冷启动秒开、热更新也快，但它生产构建用的是rollup，和webpack的生态链路不兼容；而且vite对Node版本、浏览器环境的假设都更“现代”，一些老项目根本跑不起来。rollup则更擅长库级打包，做应用级别的工程化配置链要自己拼很多东西。webpack5在生态成熟度、兼容性、团队协作、周边工具链上依然是最稳的选择，而且它现在有了持久化缓存，开发模式的体验劣势也缩小了一大截。你团队如果全都是老项目的维护任务，那webpack5基本是必须走的路。

2. 骨架先行：从零开始搭一个能跑的webpack5配置

讲完了为什么选webpack5，接下来直接进入实操。我会按照一个典型的中后台项目来做骨架，目录结构、核心配置、loader和plugin的选型都会给到，并且会解释每个配置背后的设计逻辑。

2.1 初始化项目与安装依赖

bash复制mkdir webpack5-engineering
cd webpack5-engineering
npm init -y
npm i -D webpack webpack-cli webpack-dev-server
npm i -D html-webpack-plugin mini-css-extract-plugin
npm i -D babel-loader @babel/core @babel/preset-env @babel/preset-react
npm i -D css-loader style-loader postcss-loader autoprefixer
npm i react react-dom

这里注意几个版本问题。webpack5对Node.js的版本要求是12.16以上，最好直接用14.15以上，我自己在Node 12的老环境上遇到过digital envelope routines::unsupported的报错，那是因为OpenSSL版本与webpack5的哈希计算冲突，后面会专门讲。另外webpack-cli建议装4.x的最新版，webpack-dev-server用4.x，这两个的启动命令在webpack5时代和webpack4时代有一些细节差异，比如webpack-dev-server的--inline参数已经废弃，直接用默认值即可。

package.json的scripts这样配：

json复制{
  "scripts": {
    "dev": "webpack serve --mode development",
    "build": "webpack --mode production"
  }
}

2.2 目录结构与入口输出

text复制src/
  ├── pages/       # 页面级组件
  ├── components/  # 公共组件
  ├── assets/      # 静态资源
  ├── utils/       # 工具函数
  ├── App.jsx
  └── index.js

入口文件src/index.js是webpack查找依赖的起点。我习惯把入口和输出的配置写得尽量显式，不依赖默认值，这样新同事接手的时候扫一眼就知道整个项目从哪进、往哪出：

javascript复制const path = require('path');

module.exports = {
  entry: {
    main: './src/index.js',
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash:8].js',
    clean: true, // 构建前自动清空dist目录，替代clean-webpack-plugin
    publicPath: '/', // 部署到子路径时需要改成'./'，否则资源路径会404
  },
};

entry用对象形式而不用字符串，是因为多页面应用时你需要多个入口，对象语义更清晰。output.clean是webpack5内置的新能力