Webpack 在每次执行打包时都会通过控制台输出一份构建报告，这份报告的内容形态、详细程度完全由 stats 配置项决定。很多团队在调试打包体积突增或依赖重复问题时，第一反应是加参数重跑，却忽略了 stats 本身就能定制输出结构。合理地设置 stats，不仅能让本地终端清爽，还能在持续集成里减少日志存储开销，快速定位模块级问题。
stats 的基础预设值与适用场景
Webpack 为 stats 提供了若干字符串预设，最常用的是 errors-only、minimal、none、normal、verbose。这些预设本质是一组开关的集合，用于在不同环境下平衡信息量与噪音。例如 errors-only 只输出导致编译失败的信息，适合流水线中的构建步骤；minimal 会在成功时输出少量摘要，在失败时补齐错误，适合大多数开发场景。
如果直接在命令行使用，可以通过 --stats 参数指定，例如 webpack --stats minimal。在配置文件里则写成 stats: 'minimal'。需要注意预设之间差异巨大，verbose 会打印全部模块依赖与原因，日志可能上万行，仅在排查隐藏依赖时临时开启。下面是一段简单的配置示例，展示如何在开发和生产环境切换预设。
const isProd = process.env.NODE_ENV === 'production';
module.exports = {
// 其他配置省略
stats: isProd ? 'errors-warnings' : 'minimal'
};
从维护角度看，预设虽然方便，但团队习惯不同会导致本地与服务器日志不一致。建议在仓库根目录固定一份 Webpack 配置中的 stats 策略，并通过注释说明每个环境的选择理由，避免后续被随意改成 verbose 拖慢 CI。
对象形式精细控制输出字段
当预设无法满足需求时，可以把 stats 写成对象，逐字段开关。核心字段包括 colors（终端着色）、modules（是否输出模块信息）、children（子编译器日志）、assets（资源清单）、chunks（代码块信息）、timings（耗时）。例如只想看资源大小和错误，可关闭 modules 与 children。
下面示例展示了一个偏精简但又保留资源体积的对象配置。其中 assetsSort 可按大小排序，帮助发现异常大的文件；warningsFilter 能屏蔽已知无害警告，例如特定 loader 的提示。这种写法比预设更直观，也更容易在代码评审中确认日志范围。
module.exports = {
stats: {
colors: true,
modules: false,
children: false,
assets: true,
chunks: false,
timings: true,
version: false,
warningsFilter: [/Failed to parse source map/]
}
};
在生产构建中，我们常配合 performance 字段使用 stats 的对象配置。比如关闭 entrypoints 以减少冗余，但打开 assets 配合 assetModules 观察图片与字体的内联情况。对象配置没有数量限制，但字段越多越难阅读，推荐仅保留当前阶段真正要观测的几项。
在 CI 与插件中定制 stats 输出
除了直接配置，Webpack 还允许通过 stats.toJson() 拿到结构化数据，交给自定义插件或上报系统。在 CI 脚本里，可以只提取 errors 与 warnings 数组，生成简洁的 Markdown 评论，而不必粘贴整段日志。这种方式比单纯改 stats 字符串更灵活，也便于和内部平台打通。
另一个常见做法是使用 webpack-stats-plugin 或自行编写插件，在 done 钩子中读取 stats.toJson({ all: false, assets: true })，把资源清单写入文件供体积监控使用。下面代码演示了如何在插件里获取精简数据，避免把整个编译对象序列化。
class ReportPlugin {
apply(compiler) {
compiler.hooks.done.tap('ReportPlugin', (stats) => {
const json = stats.toJson({
all: false,
assets: true,
errors: true,
warnings: true
});
// 此处可将 json 发送到日志系统或写文件
console.log('资源数量:', json.assets.length);
});
}
}
对于使用 webpack-dev-server 的团队，devServer 自身也有 stats 配置，优先级高于顶层 stats。若发现本地热更新时日志格式与构建脚本不一致，应检查 devServer 是否覆盖了设置。统一两者能减少环境差异带来的误解，也让新成员更容易读懂终端信息。