构建故障复盘该留下哪些工程资产
构建故障恢复以后，如果只留下一篇“某配置写错了”的总结，下次遇到相似问题仍然要从头排查。真正能被复用的资产，应让后来的人重新构建、比较产物、识别风险，并在发布前阻断同类问题。
前端构建故障常表现为资源 404、运行时加载失败、缓存未更新或包体突然变化。这些现象可能来自构建配置，也可能来自 CDN 清理、HTML 缓存、部署顺序和回滚策略。复盘先还原证据，再决定把修复落进测试、配置还是发布流程，不要把所有问题都归给 Webpack。
先保存能够重现构建的输入
最基本的资产是失败版本的提交标识、锁文件、Node.js 与包管理器版本、构建命令、公开环境配置和构建日志。若流水线使用基础镜像或远端缓存，还要记录其版本和缓存命中状态。不要把完整环境变量或访问凭据打进附件。
构建产物本身也值得保留一段时间，包括资源清单、Chunk 名称与哈希、HTML 中的引用关系和构建统计。遇到ChunkLoadError时，需要对照浏览器请求的地址、CDN 实际文件和该版本资源清单。只保存一张报错截图，无法判断文件从未上传、被提前清理，还是旧 HTML 仍在引用它。
Source Map 含有源码信息，应按访问权限和保存期限管理，不要公开放在静态目录。需要线上错误定位时，可以上传到受控错误平台，并确保发布版本能与 Map 对应。
时间线把构建与发布分开
时间线至少包含构建开始、产物上传、HTML 或服务发布、缓存刷新、首次异常、停止放量和恢复。这样可以判断异常是在新产物生成后出现，还是部署顺序让新 HTML 提前引用了尚未可用的资源。
每个操作都记录对象和版本。比如“已回滚”要说明回滚了应用服务、HTML 还是 CDN 资源；只回滚入口而旧哈希文件已经被删除，用户仍可能看到 404。复盘中将观察到的事实、当时的假设和最终确认原因分开，避免事后把试错过程改写成一条过于顺利的故事。
影响范围也要基于证据。列出受影响路由、浏览器或发布批次，以及如何判断用户已经恢复。没有可靠统计时就明确写“范围尚未完全确认”，不要用精确数字填补空白。
构建配置要形成可审查基线
分包规则一旦变化，应随代码评审保留构建统计和理由。硬编码把每个依赖分进固定 Vendor Chunk，不一定能改善缓存，反而可能生成过大的公共包。minSize、初始请求数量和缓存组边界都应根据当前应用入口和真实产物评估。
下面是一份克制的 Webpack 配置示例。它使用内容哈希和确定性标识，把运行时代码单独输出，但没有假定某组依赖必须永久放在同一个 Chunk。具体拆分规则应通过构建统计补充。
const path = require('node:path'); module.exports = { mode: 'production', entry: { main: './src/index.tsx' }, output: { path: path.resolve(__dirname, 'dist'), filename: 'assets/[name].[contenthash:8].js', chunkFilename: 'assets/[name].[contenthash:8].chunk.js', clean: true, }, optimization: { moduleIds: 'deterministic', chunkIds: 'deterministic', runtimeChunk: 'single', splitChunks: { chunks: 'all', cacheGroups: { defaultVendors: { test: /[\\/]node_modules[\\/]/, priority: -10, reuseExistingChunk: true, }, }, }, }, };多入口应用使用单一 runtime 是否合适，需要检查入口是否在同一页面运行。Webpack 生产模式已有一些默认优化，显式配置的价值在于表达项目约定，不是保证任何项目都获得相同结果。
构建统计最好输出机器可读 JSON，再由脚本生成体积、重复模块和入口依赖报告。HTML 分析页适合人工查看，不便直接做稳定门禁。报告保留基线与本次差异，让评审者知道增加的是哪个入口、哪个依赖，而不是只看到总包超过一个固定数字。
把根因转成回归用例
如果故障来自旧 HTML 引用了已删除 Chunk，回归应覆盖发布顺序和资源保留，不只是 Webpack 单元测试。若来自错误的公共路径，就在目标子路径部署一个最小页面并请求实际资源。若分包规则导致某依赖缺失，则建立最小消费者页面，完成加载与一次关键交互。
验证哈希稳定性时，可以用相同输入做两次干净构建，确认产物清单一致；再只改一个局部模块，观察无关资源是否保持稳定。测试环境必须固定工具链和公开配置，否则时间戳、路径或版本注入本身就会改变内容。哈希变化并非一律是故障，关键是它能否由输入变化解释。
包体检查也不要见到重复版本就自动失败。不同主版本可能是兼容需求，强行合并会引入运行错误。报告应列出依赖路径、进入哪些 Chunk 和体积影响，再由维护者决定升级、别名或保留。
回滚与缓存策略也要变成资产
构建故障经常暴露的是发布策略。带哈希资源应允许新旧版本并存一段时间，HTML 更新前确认新资源已经可用，清理任务则根据实际缓存窗口延后。回滚演练要从旧 HTML 发起请求，确认对应资源仍在，而不是只看部署平台显示旧版本已启动。
形成一份短小的处置说明：如何找到当前资源清单，如何确认 CDN 文件，何时停止放量，回滚哪些对象，恢复后用什么页面验收。说明中的命令使用占位域名和只读操作，敏感凭据仍由既有权限系统提供。
最后给修复动作分配负责人和验收条件。新增构建报告、消费者测试、资源保留策略或告警规则，都应能独立验证。复盘留下的工程资产不在数量，而在于它们能否让同类错误更早暴露，并让故障发生时的人快速还原当前版本到底发布了哪些文件。
