---
name: debug-investigation
type: procedure
when: '调试, 排障, 排查问题, bug定位, 问题排查, 线上排查, 异常排查, 错误定位, 日志排查, 缺陷修复, Bug修复, 问题修复, 异常修复, 错误修复, bug fix, 缺陷处理'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-procedure-调试排查流程
asset_kind: procedure
lifecycle_status: active
authority: supporting
owner_mechanism_id: mc-verifier
routes:
  - code_change
primary_triggers:
  - 调试排查流程
secondary_triggers: []
negative_triggers: []
priority: P1
specificity: 5
consumes:
  - mc-verifier
emits:
  - debugging_report
  - root_cause_analysis
  - minimal_fix
required_evidence:
  - execution_evidence
version: 1.1.0
last_reviewed: '2026-06-01'
stages: ["编码与单元测试", "联调验证"]
---

## 适用场景
功能异常、性能问题、线上报错等需要定位根因的场景。遵循「先观察后假设再验证」的原则。

## 四阶段调试法
1. **观察阶段**：获取具体操作步骤、输入数据、环境信息，确认可复现
2. **假设阶段**：根据观察提出一个假设，不要同时提出多个假设
3. **验证阶段**：设计最小实验验证假设，记录结果（包括被否定的假设）
4. **修复阶段**：确认根因后编写最小修复 + 回归测试

## 步骤
1. 复现问题：获取具体操作步骤、输入数据、环境信息
2. 确定影响范围：是全部用户还是特定条件？是偶发还是必现？
3. 查看日志：根据时间窗口搜索 traceId，查看完整请求链路日志
4. 查看监控：接口响应时间、错误率、资源使用（CPU/内存/磁盘）
5. 定位代码：根据日志中的异常堆栈定位到具体文件和方法
6. 分析根因：区分是代码 Bug、配置错误、数据异常还是环境问题
7. 验证假设：在本地或测试环境复现并验证根因（一次只验证一个假设）
8. 编写最小修复：修复范围只覆盖确认的根因，禁止顺手改其他代码
9. 使用 RED-GREEN 验证：回退修复 → 确认失败 → 恢复修复 → 确认通过
10. 添加回归测试（防止同类问题再发生）

## 检查点
- [ ] 问题可稳定复现（或记录了偶现条件）
- [ ] 日志中有 traceId 可追踪完整链路
- [ ] 调试过程有假设-验证记录
- [ ] 根因已确认而非停留在表象
- [ ] 修复范围仅限确认的根因
- [ ] 修复包含回归测试

## 注意事项
- 不要在没有复现的情况下直接修改代码
- 日志排查优先使用 traceId，避免大海捞针
- 性能问题优先看慢查询日志和接口耗时
- 同一现象修复失败 3 次后停止猜测，重新审视假设，考虑是否为架构问题
- 禁止通过删除断言、增加 sleep、降低覆盖率、增加 mock 来制造通过
