Webpack 5 事后分析怎么做？Post Mortem Analysis 新特性详解

升级到 Webpack 5 之后，不少团队都遇到过类似的情况：明明按照官方迁移指南操作，构建却还是出问题了，或者是构建速度突然下降，或者是产物体积膨胀，又或者是某些模块被重复打包。这类问题的排查往往零散而低效，今天我们就来系统地聊一聊如何围绕 Webpack 5 做一次完整的 Post Mortem Analysis（事后分析），把构建事故变成一份可执行的改进清单。

一、什么是构建层面的事后分析

Post Mortem Analysis 这个词更多出现在稳定性工程领域，指的是故障发生后的复盘流程。把它搬到前端构建场景，核心思路是一样的：构建出现了非预期结果，我们需要回答三个问题——发生了什么、为什么发生、如何避免再次发生。与线上故障不同的是，构建问题往往是确定性的，这为复盘提供了便利，只要能保留足够的现场信息，就可以反复重演问题。

Webpack 5 在这方面的最大改进是引入了文件系统缓存（File System Cache）。在 Webpack 4 及之前，每次构建都是全量执行，问题复现相对简单；而 Webpack 5 默认可能命中缓存，一旦缓存被污染或者意外失效，就会出现“上次构建好好的，这次怎么就不对了”的经典场景。因此，做事后分析的第一步，永远是固定现场：保留 node_modules、锁文件、node_modules/.cache 目录以及当时的完整配置。

实际操作中建议在 CI 环境里对出问题的构建任务保留工作目录快照，至少保留触发构建的 commit hash 与缓存目录的对应关系。没有这些现场信息，后续所有分析都是在猜测。

二、固定现场后如何定位问题源头

有了现场，接下来要区分问题的类别。构建问题大体可以分成三类：构建速度问题、产物体积问题、正确性问题（模块丢失、重复打包、运行时报错）。三类的分析路径完全不同，混在一起排查只会浪费时间。

速度问题的首选工具是 stats 中的 timing 信息。Webpack 5 的 stats: 'detailed' 会输出各阶段的耗时，配合 speed-measure-webpack-plugin 可以拿到每个 loader 和插件的具体耗时。需要注意的是，speed-measure 在测量时会禁用缓存，所以它反映的是冷构建性能，这恰好是分析缓存收益的对照数据。一个常见的复盘结论是：某个自定义 loader 没有正确声明缓存依赖，导致缓存频繁失效，表现为整体构建变慢。这时可以检查 loader 是否通过 this.addDependency 声明了外部文件依赖。

// webpack.config.js 中开启详细统计
module.exports = {
  stats: {
    all: false,
    timing: true,
    modules: true,
    moduleTrace: true,
    errors: true,
    warnings: true,
  },
  cache: {
    type: 'filesystem',
    buildDependencies: {
      // 把配置文件纳入缓存依赖，配置变更时自动使缓存失效
      config: [__filename],
    },
  },
};

正确性问题则要依赖 moduleTrace 和模块图信息。比如产物中出现了重复模块，通常是多个入口或者多个异步 chunk 引用了同一模块但 splitChunks 配置不当。此时用 bundle 分析工具（如 webpack-bundle-analyzer）可视化产物，重复模块会以多个同名块的形式出现，一目了然。Webpack 5 移除了 Node.js polyfill 的自动注入，这也是升级后大量运行时报错的元凶，复盘时要重点检查报错模块是否依赖了 process、Buffer 等全局对象。

三、把复盘结论沉淀为防护措施

一次合格的事后分析不能止步于“找到原因”，更重要的是建立防护，让同类问题在发生之前就被拦截。针对构建性能，可以在 CI 中加入构建耗时基线对比，每次合并请求自动对比冷构建与热构建耗时，超出阈值就告警。针对产物体积，可以接入 size-limit 一类的工具，对关键 chunk 设置体积预算，防止体积悄悄膨胀。

针对缓存相关的问题，要善用 cache.version 与 cache.buildDependencies。凡是影响构建输出的外部输入，都应该声明为构建依赖，包括 babel 配置、postcss 配置、tsconfig 等。很多人只声明了 webpack 配置本身，导致修改 babel 插件后缓存没有失效，产物里还是旧逻辑，这种问题排查起来非常隐蔽，值得写进团队的复盘文档里作为典型案例。

const path = require('path');

module.exports = {
  cache: {
    type: 'filesystem',
    // 版本号变化会使全部缓存失效，用于重大变更后强制重建
    version: process.env.CACHE_VERSION || '1',
    buildDependencies: {
      config: [__filename],
      // 把影响编译结果的配置都纳入依赖
      babel: [path.resolve(__dirname, 'babel.config.js')],
    },
    cacheDirectory: path.resolve(__dirname, '.webpack_cache'),
  },
};

最后一点是文档化。每次复盘产出的结论应该包含四个要素：问题现象、根因、修复方案、防护措施。用 git 记录配置变更与构建异常的关联，久而久之团队就能积累出一份属于自己的构建问题知识库。Module Federation 场景下还要额外记录远程容器的版本对应关系，因为共享依赖版本不匹配导致的问题，往往需要跨团队协作才能彻底解决。构建系统是前端工程的地基，把事后分析做成习惯，比每次出问题再临时抱佛脚要划算得多。

Webpack 5Post Mortem Analysis构建优化修改时间：2026-09-13 02:52:27