前端诊断框架
核心方法论（5 步法）
所有前端问题诊断遵循统一流程：
Step 1: 分类（Classify）
识别问题类型和影响范围：
| 类型 | 判断依据 | 诊断入口 | | ------- | ---------------------------- | -------------- | | build | 命令退出非零、stderr 有错误 | → Build 模块 | | runtime | 控制台异常、白屏、功能不可用 | → Runtime 模块 | | ui | 视觉偏差、交互不符预期 | → UI 模块 | | api | 请求状态码异常、数据不一致 | → API 模块 |
跨类型问题（如 API 失败导致 UI 异常）从最表层症状入手，逐层深入。
Step 2: 收集（Collect）
按类型收集证据（各模块有具体策略，见下方）。
Step 3: 假设（Hypothesize）
基于证据提出可能根因，按可能性排序：
- 每个假设必须可测试（有明确的验证方法）
- 最多保留 3 个假设，避免发散
- 格式：「因为 X，导致 Y，可通过 Z 验证」
Step 4: 验证（Verify）
逐一测试假设：
- 从最可能的假设开始
- 每次只改一个变量
- 验证结果记录：证实 / 证伪 / 待定
- 假设全部证伪时回到 Step 2 重新收集
Step 5: 修复与确认（Fix & Validate）
- 应用最小修复
- 运行受影响验证命令
- 确认无回归
- 输出修复报告
诊断模块
Build 模块
收集：运行最小失败命令，捕获完整 stderr/stdout 假设：按错误类型分组（类型错误、导入失败、配置解析、依赖缺失），匹配已知模式 验证：修一类根因 → 重跑命令 → 确认错误减少 特殊处理：
- 依赖升级/peer dependency/ESM/CJS 问题同时参考「依赖升级」skill
- CI 专属失败检查 Node 版本、包管理器、环境变量差异
Runtime 模块
收集：
- 复现路径（用户操作序列）
- 控制台错误和堆栈
- 组件渲染树状态（检查关键组件是否正确挂载）
- 相关 store/state 快照
假设：
- 堆栈反向追踪：从异常位置回溯到触发源
- 状态流分析：检查 state 变化是否符合预期
- 生命周期分析：是否在错误的时机访问了未初始化的数据
验证：
- 添加临时日志确认状态值
- 在可疑路径添加断言
- 复现路径验证修复
UI 模块
收集：
- 当前截图 vs 期望效果
- DOM 结构检查（元素是否存在、层级是否正确）
- 计算样式检查（实际应用的 CSS 值）
- 响应式断点测试
假设：
- CSS 特异性冲突（选择器权重不够被覆盖）
- 组件状态不匹配（props/state 未正确传递）
- 布局模型问题（flex/grid 配置错误）
- 响应式断点遗漏
验证：
- 浏览器 DevTools 实时调整验证
- 隔离组件测试（排除外部样式干扰）
- 多断点逐一验证
API 模块
收集：
- 请求 URL、method、headers、body
- 响应 status、headers、body
- 网络瀑布时序
- 相关 store/state 中的缓存数据
假设：
- 请求链路逐跳检查（URL → 中间件 → 拦截器 → 服务端）
- 数据转换检查（响应解析、类型映射）
- 缓存策略检查（过期、失效、竞态）
- 并发请求竞态（race condition）
验证：
- curl 独立复现（排除前端干扰）
- 逐层 mock 定位问题层级
- 端到端请求验证修复
报告格式
保存至 reports/debug-YYYY-MM-DD-HHmmss.md：
诊断报告
| 项目 | 内容 | | ---------- | -------------------------- | | 问题类型 | build / runtime / ui / api | | 问题描述 | 用户报告的现象 | | 收集的证据 | 关键日志、截图、请求记录 | | 假设与验证 | 每个假设的验证结果 | | 根因 | 最终确认的根本原因 | | 修复内容 | 修改的文件和具体改动 | | 验证结果 | 修复后的验证命令和结果 | | 剩余风险 | 未覆盖的边界或潜在回归 |
强约束
- 不在缺少证据时猜测根因
- 不通过关闭规则、删除测试或降低类型安全来「修复」
- 每次只改一个变量来验证假设
- 不在验证前扩大改动范围
- 同一假设连续 3 次验证失败，停止并报告阻塞