debugging-and-error-recovery

调试与错误恢复

概览

用结构化 triage 进行系统化调试。当某事出错时，停止添加功能，保存证据，并遵循结构化流程来找到并修复根因。猜测会浪费时间。Triage checklist 适用于测试失败、构建错误、运行时 bug 和生产事故。

何时使用

• 代码改动后测试失败
• 构建中断
• 运行时行为不符合预期
• 收到 bug report
• 日志或 console 中出现错误
• 某件过去能工作的事突然停止工作

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

不要越过失败测试或破损构建去做下一个功能。 错误会叠加。Step 3 中未修复的 bug 会让 Steps 4-10 都变错。

Triage Checklist

按顺序执行这些步骤。不要跳步。

第 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