每次运行 webpack，控制台都会打印一串构建结果，但真正能帮我们定位问题的信息往往隐藏得很深。Webpack 5 对日志输出和分析能力做了系统性调整，不再让所有内容混在一起，而是通过分级和结构化配置把构建过程透明化。理解这套机制之后，开发者可以按需获取构建细节，而不必在噪音中翻找线索。
基础设施日志与模块日志的区分
Webpack 5 把日志拆成两个层级：基础设施日志（infrastructure logging）和统计日志（stats logging）。基础设施日志主要来自 webpack 自身的启动、编译、文件监听、缓存读写等环节，默认输出到控制台，受 infrastructureLogging 配置控制。统计日志则记录模块解析、loader 执行、插件调用等具体构建细节，由 stats.logging 决定是否展示以及展示到哪个详细程度。这样区分的最大好处是：当你只想看构建框架的运行状况时，不需要被每个 loader 的处理过程刷屏；反过来，排查某个 loader 的问题时，也不用担心基础设施日志混入干扰。
下面是一份典型的配置示例，把基础设施日志设为 info，同时开启统计日志的普通级别输出。
module.exports = {
infrastructureLogging: {
level: 'info', // none | error | warn | info | log | verbose
debug: false,
console: console, // 可传入自定义输出对象
},
stats: {
logging: 'info', // 显示 loader 与插件的日志
loggingDebug: false,
},
};
level 支持 none、error、warn、info、log、verbose 六个级别。一般开发环境用 info 足够看到关键步骤，生产构建可以用 warn 或 error 减少输出。如果需要更多上下文，再临时调整到 log 或 verbose。不建议长期保持 verbose，因为日志体量会迅速膨胀，反而降低可读性。
用 loggingDebug 精准调试插件与 loader
大型项目中，开启 verbose 级别虽然能拿到完整日志，但输出量往往大到无法快速定位问题。Webpack 5 提供的 stats.loggingDebug 选项就是为了解决这个矛盾。它允许你只对特定插件、loader 或日志名称输出调试信息，其余部分仍保持较低日志级别。这个选项可以接收布尔值、字符串、正则表达式、函数，也可以是一个数组，组合多种匹配条件。
假设你怀疑 MyPlugin 或 babel-loader 的行为异常，可以这样配置：
module.exports = {
stats: {
logging: 'verbose',
loggingDebug: [
'MyPlugin',
/babel-loader/,
(name) => name.includes('cache'),
],
},
};
上面的配置会开启整体日志的 verbose 级别，但只有名称匹配 MyPlugin、包含 babel-loader 或者包含 cache 的日志才会真正输出调试内容。其余 verbose 级别的普通日志仍会显示，但调试细节被过滤掉。这样可以把注意力集中在出问题的组件上，避免其他无关模块的信息淹没关键线索。
在命令行里也可以快速启用调试，而不必修改配置文件。例如执行：
webpack --stats logging --stats loggingDebug MyPlugin
这种临时开启的方式很适合在 CI 环境或本地快速排查问题，改动不会留在项目配置中。需要注意的是，如果 loggingDebug 使用了正则或函数，命令行传参无法直接表达，还是需要写在配置文件里。
将构建结果导出为可分析数据
日志只是构建过程的即时输出，而真正的分析往往需要把数据导出后做量化统计。Webpack 5 的 stats 对象可以序列化为 JSON，结合 --profile 参数还能拿到每个模块的构建耗时、依赖关系、chunk 大小等信息。导出命令如下：
webpack --json --profile > stats.json
生成出来的 stats.json 是一个完整的构建统计文件，包含了模块列表、chunk 组成、资源大小、错误与警告、模块依赖图以及每个阶段的时间消耗。你可以用这个文件配合分析工具生成可视化报告，例如使用 webpack-bundle-analyzer 读取 stats.json 后展示各模块体积占比，快速发现体积异常大的依赖。也可以自己写脚本读取 JSON，做定制化统计，比如过滤出耗时最长的前十个 loader 或插件。
如果觉得 stats.json 体积太大，可以在配置中缩小输出范围。下面这个配置只保留模块和 chunk 相关信息，去掉 assets 等不必要的内容，从而降低分析文件的大小。
module.exports = {
stats: {
all: false,
modules: true,
chunkModules: true,
chunks: true,
assets: false,
errors: true,
warnings: true,
},
};
通过有选择地导出 stats 字段，可以让分析过程更轻量，也更容易聚焦到当前要解决的问题上。例如排查 chunk 拆分策略时，只关注 chunks 和 modules；排查资源体积时，再把 assets 加回来。
常见误区与调优建议
很多人在终端里只关注 errors 和 warnings，习惯性忽略 info 与 log 级别的日志。但 Webpack 5 的 info 日志常常包含很有价值的性能建议，例如模块体积过大、chunk 数量过多、缓存失效原因等。忽视这些提示，可能错过优化构建速度的机会。
另一个常见误区是为了排查问题直接把所有日志都开到 verbose，结果日志量大到难以阅读。更合理的做法是先通过 stats.logging 观察整体概况，锁定可疑的插件或 loader 后，再用 loggingDebug 精确打开调试输出。这样既能拿到细节，又不会影响整体可读性。
还可以结合性能预算配置，让构建过程在超过阈值时自动给出警告。下面的配置设置了入口和资源的大小上限，超过后会在 stats 输出中显示性能警告，帮助开发者在问题扩大前及时处理。
module.exports = {
performance: {
hints: 'warning',
maxEntrypointSize: 512000,
maxAssetSize: 512000,
},
stats: {
performance: true,
logging: 'info',
},
};
把日志分级、精准调试、性能预算和 stats 数据导出组合起来，就能形成一套完整的构建分析流程：先看整体 info 日志，发现性能警告后用 --json --profile 导出数据，再借助分析工具定位具体模块，最后用 loggingDebug 深入排查对应 loader 或插件的执行细节。这样每一步都有据可依，不必反复尝试或猜测。