systematic-debugging

1# 系统化调试
2 
3## 概述
4 
5**核心原则：** 在尝试修复之前，务必先找到根本原因。只修症状就是失败。
6 
7**敷衍走流程等于违背调试的精神。**
8 
9## 铁律
10 
11```
12不做根因调查，不许提修复方案
13```
14 
15如果你还没完成第一阶段，就不能提出修复方案。
16 
17## 何时使用
18 
19用于任何技术问题：
20- 测试失败
21- 生产环境 bug
22- 异常行为
23- 性能问题
24- 构建失败
25- 集成问题
26 
27**尤其在以下情况必须使用：**
28- 时间紧迫（紧急情况最容易让人猜测式修复）
29- 觉得"一个小修改"就能搞定
30- 已经尝试了多种修复
31- 上一次修复没有生效
32- 你没有完全理解问题
33 
34**以下情况也不要跳过：**
35- 问题看起来很简单（简单的 bug 也有根本原因）
36- 你很赶时间（越急越容易返工）
37- 领导要求立刻修好（系统化调试比反复尝试更快）
38 
39## 四个阶段
40 
41你必须完成每个阶段后才能进入下一个。
42 
43### 第一阶段：根因调查
44 
45**在尝试任何修复之前：**
46 
471. **仔细阅读错误信息**
48   - 不要跳过错误或警告
49   - 它们往往直接包含解决方案
50   - 完整阅读堆栈跟踪
51   - 记下行号、文件路径、错误码
52 
532. **稳定复现**
54   - 你能可靠地触发它吗？
55   - 具体的复现步骤是什么？
56   - 每次都能复现吗？
57   - 如果无法复现 → 收集更多数据，不要猜测
58 
593. **检查近期变更**
60   - 什么变更可能导致了这个问题？
61   - git diff、最近的提交
62   - 新依赖、配置变更
63   - 环境差异
64 
654. **在多组件系统中收集证据**
66 
67   **当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：**
68 
69   **在提出修复方案之前，先添加诊断埋点：**
70   ```
71   对每个组件边界：
72     - 记录进入组件的数据
73     - 记录离开组件的数据
74     - 验证环境/配置的传递
75     - 检查每一层的状态
76 
77   执行一次以收集证据，确定断裂点在哪里
78   然后分析证据，定位故障组件
79   然后针对该组件深入调查
80   ```
81 
82   **示例（多层系统）：**
83   ```bash
84   # 第 1 层：工作流
85   echo "=== Secrets available in workflow: ==="
86   echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
87 
88   # 第 2 层：构建脚本
89   echo "=== Env vars in build script: ==="
90   printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"
91 
92   # 第 3 层：签名脚本
93   echo "=== Keychain state: ==="
94   security list-keychains
95   security find-identity -v
96 
97   # 第 4 层：实际签名
98   codesign --sign "$IDENTITY" --verbose=4 "$APP"
99   ```
100…