debug

系统化调试

概述

随机修复浪费时间，还会引入新 Bug。快速打补丁会掩盖根本问题。

核心原则： 务必先找到根本原因，再尝试修复。只修复症状注定失败。

违背流程的字面要求，就是违背调试的本意。

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

如果尚未完成阶段 1，就不能提出修复方案。

适用场景

任何技术问题都适用：

• 测试失败
• 生产环境中的 Bug
• 行为异常
• 性能问题
• 构建失败
• 集成问题

以下情况尤其要使用：

• 时间紧迫时（紧急情况容易让人忍不住猜测）
• “只要快速修一下”看起来显而易见时
• 已经尝试过多种修复方案时
• 之前的修复无效时
• 尚未完全理解问题时

以下情况也不要跳过：

• 问题看起来很简单时（简单的 Bug 也有根本原因）
• 赶时间时（仓促行事必然导致返工）
• 经理要求立即修复时（系统化处理比反复折腾更快）

四个阶段

必须完成当前阶段后才能进入下一阶段。

阶段 1：调查根本原因

尝试任何修复之前：

1. 仔细阅读错误消息

   • 不要略过错误或警告
   • 它们通常包含确切的解决方案
   • 完整阅读堆栈跟踪
   • 记下行号、文件路径和错误代码

2. 稳定复现问题

   • 能否可靠地触发问题？
   • 确切的步骤是什么？
   • 每次都会发生吗？
   • 如果无法复现 → 收集更多数据，不要猜测

3. 检查近期变更

   • 哪些变更可能导致此问题？
   • Git diff、近期提交
   • 新依赖项、配置变更
   • 环境差异

4. 在多组件系统中收集证据

   当系统包含多个组件时（CI → 构建 → 签名、API → 服务 → 数据库）：

   提出修复方案之前，先添加诊断检测代码：

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   示例（多层系统）：

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   这可以揭示： 哪一层出现故障（secrets → workflow ✓，workflow → build ✗）

5. 追踪数据流

   当错误出现在调用栈深处时：

   使用内置的反向追踪方法：

   • 错误值从哪里产生？
   • 谁在传入错误值的情况下调用了此代码？
   • 持续向上追踪，直到找到来源
   • 在源头修复，而不是只修复症状

内置的深层调用栈追踪

当 Bug 的触发点与实际故障点相距很远时，使用此方法。

常见迹象：

• 错误发生在执行过程深处，而非入口点
• 堆栈跟踪很长
• 能看到故障位置，却不知道错误值来自哪里
• 诱人的修复方案就在症状出现的位置

追踪流程：

1. 观察症状。
2. 找出直接原因。
3. 询问是谁调用了它。
4. 持续向上追踪，直到找到第一个错误输入、无效假设或错误触发条件。
5. 在此处修复；如有帮助，再在较低层添加纵深防御。

简短示例：

await execFileAsync("git", ["init"], { cwd: projectDir });

• 直接原因：git init 在错误的目录中运行
• 接下来要问：是谁传入了 projectDir？
• 再接着问：错误的 projectDir 是从哪里来的？
• 根本原因可能远在故障行的上游

手动追踪陷入停滞时，在危险操作之前添加检测代码：

async function gitInit(directory: string) {
  const stack = new Error().stack;
  console.error("DEBUG git init:", {
    directory,
    cwd: process.cwd(),
    nodeEnv: process.env.NODE_ENV,
    stack,
  });

  await execFileAsync("git", ["init"], { cwd: directory });
}

追踪规则： 绝不要止步于“这一行崩溃了”。继续追踪，直到能指出是哪个调用方、输入或状态转换产生了错误值。

阶段 2：模式分析

修复前先找出模式：

1. 查找可用示例

   • 在同一代码库中查找类似的可用代码
   • 类似的代码中，哪些部分有效？哪些部分与出问题的代码相似？

2. 对照参考实现

   • 如果要实现某种模式，请完整阅读参考实现
   • 不要略读——逐行阅读
   • 在应用模式前，先充分理解它

3. 找出差异

   • 可用代码与出问题的代码有什么不同？
   • 列出所有差异，无论多么细微
   • 不要假设“这不可能有影响”

4. 理解依赖项

   • 还需要哪些组件？
   • 需要哪些设置、配置和环境？
   • 它有哪些假设？

阶段 3：假设与测试

运用科学方法：

1. 提出单一假设

   • 明确陈述：“我认为 X 是根本原因，因为 Y”
   • 把它写下来
   • 具体明确，不要含糊

2. 进行最小化测试

   • 做出尽可能小的改动来验证假设
   • 一次只改变一个变量
   • 不要一次修复多个问题

3. 确认后再继续

   • 有效吗？是 → 阶段 4
   • 无效？提出新假设
   • 不要在已有修复上继续叠加修复

4. 遇到不懂的地方

   • 说“我不理解 X”
   • 不要假装自己知道
   • 寻求帮助
   • 继续研究

阶段 4：实施

修复根本原因，而非表面症状：

1. 决定测试策略

   根据复杂程度自动决定：

   • 编写测试的情况：复杂算法、业务逻辑、容易出现错误的数据转换
   • 跳过测试的情况：UI 组件、React hooks、简单的 CRUD、直接明了的映射，以及你 100% 确定正确的任何内容
   • 测试类型：仅使用确定性单元测试——不做集成测试、不进行复杂模拟、不引入异步复杂性

   如果编写测试：

   • 用尽可能简单的方式重现问题
   • 编写修复前会失败的自动化测试
   • 验证逻辑，而非实现细节

   如果跳过测试：

   • 使用类型检查和 lint 验证修复
   • 对 UI 更改进行手动验证
   • 通过代码审查确认修复正确

2. 实施单一修复

   • 解决已确定的根本原因
   • 一次只做一个更改
   • 不要顺便做其他改进
   • 不要打包进行重构

3. 验证修复

   如果编写了测试：

   • 现在测试通过了吗？
   • 其他测试没有被破坏吗？

   如果没有编写测试：

   • 类型检查通过了吗？
   • lint 检查干净吗？
   • 手动验证确认修复有效吗？

   始终检查：

   • 问题是否确实已解决？
   • 相关功能是否没有出现回归？

4. 如果修复无效

   • 停止
   • 统计：你尝试了多少次修复？
   • 如果少于 3 次：返回阶段 1，结合新信息重新分析
   • 如果 ≥ 3 次：停止并审视架构（见下方步骤 5）
   • 未进行架构讨论前，不要尝试修复 #4

5. 如果 3 次或更多修复均失败：审视架构

   表明存在架构问题的模式：

   • 每次修复都会在不同位置暴露新的共享状态、耦合或问题
   • 实施修复需要“大规模重构”
   • 每次修复都会在其他地方引发新的症状

   停止并审视根本问题：

   • 这种模式从根本上是否合理？
   • 我们是否只是“因为惯性而坚持下去”？
   • 我们应该重构架构，还是继续修复表面症状？

   尝试更多修复前，先与人类协作者讨论

   这不是假设失败——这是架构错误。

危险信号——停止并遵循流程

如果你发现自己在想：

• “先快速修复，之后再调查”
• “先试着改一下 X，看看是否有效”
• “做几处改动，然后运行测试”
• “问题大概出在 X，我来修一下”
• “我还没完全弄明白，但这样也许行得通”
• “模式表明应该用 X，但我会换个方式调整”
• “主要问题如下：[列出修复方案，却没有调查]”
• 在追踪数据流之前就提出解决方案
• “再尝试修复一次”（已经尝试过 2 次或更多时）
• 每次修复都会在别处发现新问题
• 确信修复正确，却仍为 UI 组件编写测试

以上任何一种情况都意味着：停止。返回阶段 1。

如果 3 次或更多修复都失败：质疑架构（参见阶段 4.5）

你的人类搭档指出你做错了的信号

留意这些纠正：

• “这不是没发生吗？”——你未经核实就做了假设
• “这样能让我们看到……吗？”——你本该收集证据
• “别猜了”——你还没弄清问题，就提出了修复方案
• “深入思考这个问题”——质疑基本原理，而不只是症状
• “我们卡住了吗？”（沮丧）——你的方法不起作用

看到这些信号时：停止。返回阶段 1。

常见的自我辩解

借口	事实
“问题很简单，不需要走流程”	简单问题也有根本原因。流程能快速处理简单 Bug。
“情况紧急，没时间走流程”	系统性调试比反复猜测和试错更快。
“先试试这个，然后再调查”	第一次修复会定下处理模式。从一开始就做好。
“一次做多处修复能节省时间”	无法确定哪项修复有效，还会引入新 Bug。
“参考内容太长，我会自行调整模式”	理解不完整必然导致 Bug。完整阅读。
“我看到问题了，我来修”	看到症状 ≠ 理解根本原因。
“再尝试修复一次”（失败 2 次或更多后）	失败 3 次或更多说明存在架构问题。质疑模式，不要再次修复。
“UI 修复不需要测试”	没错！UI 组件应通过类型检查/手动测试验证，而不是单元测试。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误信息、复现问题、检查改动、收集证据	理解是什么问题以及为什么会发生
2. 模式	查找可用示例并进行比较	找出差异
3. 假设	提出理论并进行最小化测试	得到确认或提出新假设
4. 实施	创建测试、修复问题、进行验证	Bug 已解决，测试通过

流程未发现“根本原因”时

如果系统性调查表明问题确实由环境、时序或外部因素导致：

1. 你已完成整个流程
2. 记录你调查过的内容
3. 实施适当的处理方式（重试、超时、错误消息）
4. 添加监控/日志，以便未来调查

**但是：**95% 的“没有根本原因”情况，都是调查不充分。

与其他技能集成

测试技能（需要时使用）：

• tdd（如果可用）——修复需要测试覆盖的复杂业务逻辑时使用
• UI 组件、简单的 CRUD，或任何可通过类型检查/手动测试验证的内容，无需使用

实际影响

根据调试经验：

• 系统化方法：15-30 分钟即可修复
• 随机修复方法：反复折腾 2-3 小时
• 首次修复成功率：95% 对比 40%
• 引入的新 Bug：几乎为零，对比常见