webpack stats 配置指南：用 "summary" 预设输出精简的构建摘要

本指南围绕 webpack 官方示例 examples/stats-summary 展开，讲解如何通过 stats: "summary" 让构建终端只输出最精简的摘要信息。文章会从配置写法、运行结果出发，深入 DefaultStatsPresetPlugin 与配置归一化链路，说明 summary 预设内部究竟开启了哪些字段、与其他预设（none / minimal / errors-warnings / normal / detailed / verbose）的差异，以及如何在对象模式下做细粒度定制。

stats 输出级别与预设（preset）体系

webpack 在每次编译结束后都会生成一份 stats（统计报告），用于在终端描述本次构建的结果。这份报告的控制项非常多（资产、模块、chunk、错误与警告、日志等），为了便于使用，webpack 用"预设"把这些细粒度开关打包成若干档位。

在配置校验 Schema 中，stats 字段被定义为 StatsValue，它可以是一个字符串预设名、一个布尔值，或一个细粒度选项对象（见 schemas/WebpackOptions.json）：

• 字符串预设名："none"、"summary"、"errors-only"、"errors-warnings"、"minimal"、"normal"、"detailed"、"verbose"；
• 布尔值：true / false；
• 对象：直接传入 StatsOptions 中的任意字段做细粒度控制。

这些预设的完整定义集中在 lib/stats/DefaultStatsPresetPlugin.js 的 NAMED_PRESETS 常量中，下表整理了各档位对应的能力：

预设名	核心语义	典型输出
none	关闭全部输出（all: false）	什么都不打印
summary	只保留版本号与错误/警告计数，关闭全部细节	webpack X.X.X compiled successfully
errors-only	只显示错误与错误堆栈/模块追踪，日志仅 error 级	无错误时几乎无输出，出错时仅呈现错误
errors-warnings	在 errors-only 基础上额外输出警告	干净构建时接近无输出
minimal	显示资产/模块的"计数式"摘要与错误警告	1 asset / 1 module / compiled successfully
normal	默认档，展示资产、模块、编译结果等常规信息	带文件名的资产与模块清单
detailed	在 normal 基础上追加 chunk、模块深度、导出使用、日志等	详细分块输出 + LOG 分组
verbose	全量细节（堆栈、日志 verbose、chunk 关系等）	最完整最啰嗦

关于布尔值：stats: true 等价于 "normal"，stats: false 等价于 "none"，这一映射可以在 lib/config/normalization.js 的 stats 归一化逻辑以及 lib/Compilation.js 的 createStatsOptions 中得到印证——false 会被改写成 { preset: "none" }，true 改写成 { preset: "normal" }，字符串则直接改写成 { preset: <字符串> }。用户不配置 stats 时，输出形态约等于 normal 档（由 DEFAULTS 中各字段在终端展示（forToString）上下文中的默认值决定，见 lib/stats/DefaultStatsPresetPlugin.js）。

最小化配置：启用 summary 输出

examples/stats-summary 展示的就是最简单的一种 stats 自定义方式。入口文件 examples/stats-summary/example.js 内容非常朴素：

console.log("Hello World!");

而其 webpack.config.js 也极其精简——除了输出目录与文件名外，唯一的"额外"配置就是 stats: "summary"：

"use strict";

const path = require("path");

/** @type {import("webpack").Configuration} */
const config = {
	output: {
		path: path.join(__dirname, "dist"),
		filename: "output.js"
	},
	stats: "summary"
};

module.exports = config;

在仓库根目录执行以下命令即可复现该示例（产物会写入 examples/stats-summary/dist，stats 只影响终端报告，不影响产物内容）：

cd examples/stats-summary && npx webpack

README 中该示例的终端输出被归在 "Production mode"（生产模式）之下，呈现为一行状态摘要：

webpack X.X.X compiled successfully

对比同仓库的其余 stats 示例可以看到档位差异：examples/stats-minimal 在摘要之外多出 1 asset / 1 module 两行计数；examples/stats-normal 会列出 asset output.js 28 bytes ... 与 ./example.js 29 bytes ...；examples/stats-detailed 还会输出 chunk、入口点、模块深度以及 LOG from webpack.* 的分组日志；而 examples/stats-none 则完全不输出任何内容。几个示例共享同一份业务代码与几乎相同的输出产物，差别只在 stats 报告——这直观说明了 stats 配置与打包结果彼此独立。

summary 预设的源码语义：它到底打开了什么

从输出看 summary 很"安静"，但在源码层面它并不是简单地"少打印"。查看 NAMED_PRESETS 中 summary 的定义（lib/stats/DefaultStatsPresetPlugin.js）：

summary: {
	all: false,
	version: true,
	errorsCount: true,
	warningsCount: true
}

其展开后的语义如下：

字段	summary 取值	含义
all	false	全局总开关关闭，未显式指定的报告项（资产、模块、chunk、日志等）一律不输出
version	true	报告头部附带 webpack 版本号（终端中的 webpack X.X.X 即由此而来）
errorsCount	true	开启错误计数；本次构建存在错误时，会以计数形式汇总呈现
warningsCount	true	开启警告计数；本次构建存在警告时，会以计数形式汇总呈现

因此，在没有任何错误与警告的干净构建中，summary 的输出收敛为一行 webpack X.X.X compiled successfully；一旦编译出现错误或警告，计数开关会将其以汇总条目的形式呈现在状态行上（源码层面即 errorsCount / warningsCount 为 true 的效果）。需要保留错误/警告的详细堆栈与模块来源时，应改用 errors-only 或 errors-warnings 档位（见 lib/stats/DefaultStatsPresetPlugin.js），两者都会把错误与警告的展示空间（errorsSpace / warningsSpace）置为 Infinity 并开启 moduleTrace。

预设如何被"施加"：statsPreset 钩子与归一化

理解 summary 的含义后，再来看它是在何时、以何种顺序生效的。webpack 对 stats 的处理分两个阶段：

1. 归一化：编译开始时，用户配置中 stats 的值会被归一化为统一的对象结构。字符串/布尔值会被包成 { preset: ... }（见 lib/config/normalization.js）。

2. 施加预设并补齐默认值：当 stats 选项对象存在 preset 时，lib/Compilation.js 的 createStatsOptions 会先触发：

if (options.preset !== undefined) {
	this.hooks.statsPreset.for(options.preset).call(options, context);
}
this.hooks.statsNormalize.call(options, context);

statsPreset 钩子由 lib/stats/DefaultStatsPresetPlugin.js 注册：对于 NAMED_PRESETS 中的每个预设名，插件都通过 compilation.hooks.statsPreset.for(key) 挂载回调，用 applyDefaults 把该预设的字段值填进选项（只有未定义的关键字才会被写入，用户显式给出的字段会覆盖预设值）。紧接着 statsNormalize 钩子再补齐 DEFAULTS 中的其余默认项，例如 colors（终端着色）、输出间距等。

也就是说，stats: "summary" 的完整语义是"summary 预设定义的 4 个字段 + DEFAULTS 中的其余全局默认项"，任何单个字段都可以被后续对象配置覆盖。

对象模式：在 summary 基础上做细粒度定制

stats 同样支持直接传入选项对象。如果希望获得 summary 的效果、同时额外开启终端着色，可以在 webpack.config.js 中写出与预设等价的对象：

"use strict";

const path = require("path");

/** @type {import("webpack").Configuration} */
const config = {
	output: {
		path: path.join(__dirname, "dist"),
		filename: "output.js"
	},
	// 等价于 stats: "summary"，并额外开启终端着色
	stats: {
		all: false,
		version: true,
		errorsCount: true,
		warningsCount: true,
		colors: true
	}
};

module.exports = config;

同理，当 "summary" 不能满足需求时，可以在对象中打开个别字段（如 errors: true、moduleTrace: true、assets: true 等），webpack 会把这些字段与 DEFAULTS 中未显式关闭的默认项合并生效。需要注意：若对象中未设置 all，默认项会按各自规则决定开关，因此"想从一个干净基线上单独打开某一项"时，显式书写 all: false 是最可控的做法。

小结

stats: "summary" 是 webpack stats 输出体系中最内敛的一档预设：通过 all: false 关掉所有细节，仅保留 version、errorsCount、warningsCount 三个信息源，让构建终端只呈现一行最干净的编译结果。它非常适合需要在日志噪音很小的环境下确认构建状态、或在 CI 中只关心"是否编译成功"的场景。若想深入学习这套预设体系，推荐按如下路径在仓库内继续阅读：

• 查看完整预设定义与默认值：lib/stats/DefaultStatsPresetPlugin.js；
• 查看预设施加顺序与归一化入口：lib/Compilation.js、lib/config/normalization.js；
• 查看合法取值与字段校验：schemas/WebpackOptions.json；
• 对照观察各档位差异：stats-none、stats-summary、stats-minimal、stats-normal、stats-detailed。