debugging-and-error-recovery

调试与错误恢复

概览

用结构化分诊来进行系统化调试。当某个地方坏掉时，先停止加功能，保留证据，然后按固定流程找出并修复根因。靠猜只会浪费时间。这套分诊清单适用于测试失败、构建错误、运行时 bug 以及生产事故。

何时使用

• 代码改完后测试失败
• 构建损坏
• 运行时行为与预期不符
• 收到 bug 报告
• 日志或控制台里出现错误
• 某个本来能工作的东西突然不能用了

Stop-the-Line 规则

当任何不符合预期的事情发生时：

1. STOP adding features or making changes
2. PRESERVE evidence (error output, logs, repro steps)
3. DIAGNOSE using the triage checklist
4. FIX the root cause
5. GUARD against recurrence
6. RESUME only after verification passes

不要一边顶着失败测试或损坏构建，一边继续做下一个功能。 错误会叠加。第 3 步里的 bug 如果没修，就会让第 4-10 步全都建立在错误基础上。

分诊清单

按顺序完成这些步骤，不要跳步骤。

步骤 1：复现

让失败稳定地发生。如果无法稳定复现，你就无法有把握地修好它。

Can you reproduce the failure?
├── YES → Proceed to Step 2
└── NO
    ├── Gather more context (logs, environment details)
    ├── Try reproducing in a minimal environment
    └── If truly non-reproducible, document conditions and monitor

当 bug 无法稳定复现时：

Cannot reproduce on demand:
├── Timing-dependent?
│   ├── Add timestamps to logs around the suspected area
│   ├── Try with artificial delays (setTimeout, sleep) to widen race windows
│   └── Run under load or concurrency to increase collision probability
├── Environment-dependent?
│   ├── Compare Node/browser versions, OS, environment variables
│   ├── Check for differences in data (empty vs populated database)
│   └── Try reproducing in CI where the environment is clean
├── State-dependent?
│   ├── Check for leaked state between tests or requests
│   ├── Look for global variables, singletons, or shared caches
│   └── Run the failing scenario in isolation vs after other operations
└── Truly random?
    ├── Add defensive logging at the suspected location
    ├── Set up an alert for the specific error signature
    └── Document the conditions observed and revisit when it recurs

对于测试失败：

# Run the specific failing test
npm test -- --grep "test name"

# Run with verbose output
npm test -- --verbose

# Run in isolation (rules out test pollution)
npm test -- --testPathPattern="specific-file" --runInBand