Webpack 5 发布以来，大部分讨论集中在 Module Federation、持久化缓存这些重量级特性上，但有一类改进经常被忽视，那就是构建输出的清晰度（Clarity）。所谓清晰度，指的是 Webpack 在 stats 输出、模块路径展示、依赖诊断等方面提供的信息质量。当项目规模膨胀到几百个模块之后，如果构建工具给出的信息含糊不清，排查体积问题和依赖冲突会变成一场噩梦。本文从 stats 配置、模块路径与命名、诊断能力三个角度，详细聊聊 Webpack 5 在这方面的改进。
一、stats 输出的结构化改进
Webpack 4 的 stats 输出更像是一份"尽力而为"的文本报告，默认信息量有限，开启详细模式后又容易淹没在海量日志里。Webpack 5 对 stats 做了整体重构，引入了更细粒度的预设和字段控制。最直观的变化是支持按对象形式精确声明你想看的内容，比如只关心模块体积和警告信息，而不需要把错误堆栈一起打出来。
下面是一个典型的配置示例，只展示警告、错误以及各模块的体积信息：
// webpack.config.js
module.exports = {
// ...其他配置
stats: {
all: false, // 关闭所有默认输出
assets: true, // 展示产物资源
errors: true, // 展示错误
warnings: true, // 展示警告
modules: true, // 展示模块列表
moduleAssets: true, // 展示模块引入的资源
reasons: true, // 展示模块被引入的原因链
colors: true // 彩色输出
}
};
其中 reasons 字段特别值得注意。它会告诉你某个模块是被哪个文件、通过什么方式引入的。在排查"这个库为什么被打进来了"这类问题时，这条引入链路往往能直接给出答案，而不需要你手动在代码里全局搜索。此外，Webpack 5 的 stats 还支持 'errors-warnings'、'minimal'、'detailed' 等预设值，可以先用预设再按需覆盖个别字段，配置成本比 Webpack 4 低不少。
另一个容易被忽略的改进是 JSON 输出的稳定性。Webpack 5 的 stats.toJson() 返回的结构更加规范，版本间的字段变动有明确的迁移说明，这让基于 stats 做二次分析的工具（比如 webpack-bundle-analyzer）可靠性大幅提升。如果你在公司内部维护构建报表，这一点会明显减少适配工作。
二、模块 ID 与路径展示的确定性
Webpack 4 在开发模式下默认使用模块路径作为模块 ID，而生产构建则使用数字 ID，且数字是根据模块的遍历顺序分配的。这意味着你只是新增或删除了一个文件，其他模块的 ID 也会随之变化，导致长效缓存命中率下降，同时让不同构建之间的对比分析变得困难。
Webpack 5 引入了确定性的模块 ID 与 Chunk ID 算法，并提供 optimization.moduleIds 配置项来控制策略。常见取值如下：
module.exports = {
optimization: {
// 'deterministic': 按模块路径生成稳定的短数字 ID，生产推荐
// 'size': 按模块体积排序分配 ID
// 'named': 使用可读的路径名，开发模式推荐
moduleIds: 'deterministic',
chunkIds: 'deterministic'
}
};
deterministic 是默认值，它会根据模块的相对路径生成哈希后的短数字 ID，保证同样的代码结构在多次构建之间 ID 稳定。这在两个层面提升了清晰度：一是浏览器端的长效缓存不会因为无关文件的增删而失效；二是当你对比两次构建产物时，ID 的含义是一致的，可以直接定位到哪些模块发生了变化。
在开发模式下，建议切换到 named，此时模块 ID 直接是相对路径，配合 HMR 的报错信息，你能一眼看出是哪个文件出了问题。而在 Webpack 4 时代，开发者经常需要面对一堆无意义的数字 ID，再配合 NamedModulesPlugin 手动修正，过程比较繁琐。
三、Tree Shaking 与依赖诊断的透明化
清晰度的另一个重要维度是诊断信息。Webpack 5 内置了对未使用导出的标记能力，配合 stats.usedExports 和 stats.providedExports，可以清楚地看到每个模块导出了什么、实际用到了什么。这在评估 tree shaking 效果时非常关键。
module.exports = {
stats: {
usedExports: true, // 展示模块中被实际使用的导出
providedExports: true, // 展示模块提供的所有导出
}
};
举个例子，如果你引入了 lodash 的某个工具函数，但打包报告里发现整个 lodash 都进了产物，通过这些字段可以确认是引入方式的问题（import _ from 'lodash' 与 import debounce from 'lodash/debounce' 的差异），还是库本身没有提供 ESM 版本导致 tree shaking 失效。Webpack 5 对 CommonJS 模块的 sideEffects 分析也比之前更完善，配合 sideEffects 字段声明的校验提示，很多潜在的摇树失败问题在构建阶段就能暴露出来。
此外，Webpack 5 的日志系统基于分级日志（infrastructureLogging），可以为特定插件或 loader 单独设置日志级别。调试某个 loader 行为时，你不再需要翻找混杂在一起的完整输出，而是精准获取目标组件的日志。这种"按需取用"的信息呈现方式，本质上就是构建工具清晰度的核心：让你在需要的时候，快速拿到准确的信息。
四、配合分析工具构建完整的观测链路
stats 输出的改进最终要服务于分析工具。Webpack 5 生态里常用的组合是 webpack-bundle-analyzer 配合 --json 输出。先生成分析数据，再用可视化工具打开：
# 生成 stats.json npx webpack --profile --json > stats.json # 启动可视化分析 npx webpack-bundle-analyzer stats.json dist
在分析界面中，你可以按模块路径逐层展开，观察每个依赖的体积占比。结合前面提到的 deterministic ID 与 usedExports 信息，可以回答三个关键问题：产物里有什么、它们为什么在里面、哪些部分没有被真正使用。这三个问题回答清楚了，优化方向自然就浮现出来了——要么换成支持摇树的按需引入，要么拆分异步 Chunk，要么直接移除无用依赖。
总结来看，Webpack 5 的清晰度改进不是某个单一的大功能，而是一组围绕可观测性的细节优化：结构化 stats、确定性 ID、透明的导出标记、分级日志。这些改进单独看都不起眼，但在维护大型项目时，它们能显著降低排查构建问题的成本。如果你还在沿用 Webpack 4 时代的配置习惯，不妨先从调整 stats 和 moduleIds 入手，体验一下构建信息从模糊到清晰的差别。