示例项目三：性能预算看板

这是一份示例内容，用于演示项目详情页的结构，不代表真实项目、真实成果或真实指标。所有数字字段均留空。

背景与目标#

性能预算写在文档里通常没人看，写在 CI 里才会被遵守。示例项目的目标是：构建完成后读取产物体积，与预算表逐项比对，超出时在报告里指出具体文件。

• 预算以配置文件维护，不写死在脚本里
• 每次构建产出一份对比结果，而不是只输出一句通过或失败
• 失败信息包含文件路径与超出量，方便直接定位

方案与实现#

整体分成三步：采集产物、比对预算、生成报告。三步彼此独立，任何一步都可以单独替换。

采集产物#

遍历输出目录，记录每个文件的原始体积与 gzip 体积。gzip 体积才是首屏真实的下载量，只看原始体积会高估收益。

const files = await collect(outputDir);
const report = files.map((file) => ({
  path: file.path,
  raw: file.size,
  gzip: gzipSize.sync(file.content),
}));

比对预算#

预算按路由分组：首屏脚本、共享运行时、样式。分组比单文件上限更贴近体验，因为它约束的是同类资源的总和。

难点与取舍#

1. 体积统计的口径：不同工具对 gzip 的计算方式略有差异，换工具时历史数据不可比，因此报告里固定记录工具版本。
2. 报告的可读性：表格比日志更容易被真正查看，但表格需要稳定的列宽，长路径要截断并保留完整信息。
3. 失败的门槛：阈值定得太紧会频繁误报，太松又失去意义，示例里只做提示不做阻断，是否需要阻断由项目自己决定。

原则：预算的价值在于每次构建都能看到趋势，而不是等到上线前才做一次体检。

结果与复盘#

示例项目不提供任何测量结果，指标字段保持为空。流程上的收获是把「发现问题」与「判断是否阻断」拆成两个决定，前者交给脚本，后者留给人。