systematic-debugging

# 系统化调试 ## 概述 随意修复既浪费时间又会引入新 bug。草率的补丁只会掩盖深层问题。 **核心原则：** 在尝试修复之前，务必先找到根本原因。只修症状就是失败。 **敷衍走流程等于违背调试的精神。** ## 铁律 ``` 不做根因调查，不许提修复方案 ``` 如果你还没完成第一阶段，就不能提出修复方案。 ## 何时使用 用于任何技术问题： - 测试失败 - 生产环境 bug - 异常行为 - 性能问题 - 构建失败 - 集成问题 **尤其在以下情况必须使用：** - 时间紧迫（紧急情况最容易让人猜测式修复） - 觉得"一个小修改"就能搞定 - 已经尝试了多种修复 - 上一次修复没有生效 - 你没有完全理解问题 **以下情况也不要跳过：** - 问题看起来很简单（简单的 bug 也有根本原因） - 你很赶时间（越急越容易返工） - 领导要求立刻修好（系统化调试比反复尝试更快） ## 四个阶段 你必须完成每个阶段后才能进入下一个。 ### 第一阶段：根因调查 **在尝试任何修复之前：** 1. **仔细阅读错误信息** - 不要跳过错误或警告 - 它们往往直接包含解决方案 - 完整阅读堆栈跟踪 - 记下行号、文件路径、错误码 2. **稳定复现** - 你能可靠地触发它吗？ - 具体的复现步骤是什么？ - 每次都能复现吗？ - 如果无法复现 → 收集更多数据，不要猜测 3. **检查近期变更** - 什么变更可能导致了这个问题？ - git diff、最近的提交 - 新依赖、配置变更 - 环境差异 4. **在多组件系统中收集证据** **当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：** **在提出修复方案之前，先添加诊断埋点：** ``` 对每个组件边界： - 记录进入组件的数据 - 记录离开组件的数据 - 验证环境/配置的传递 - 检查每一层的状态 执行一次以收集证据，确定断裂点在哪里 然后分析证据，定位故障组件 然后针对该组件深入调查 ``` **示例（多层系统）：** ```bash # 第 1 层：工作流 echo "=== Secrets available in workflow: ===" echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}" # 第 2 层：构建脚本 echo "=== Env vars in build script: ===" env | grep IDENTITY || echo "IDENTITY not in environment" # 第 3 层：签名脚本 echo "=== Keychain state: ===" security list-keychains security find-identity -v # 第 4 层：实际签名 codesign --sign "$IDENTITY" --verbose=4 "$APP" ``` **由此可以看出：** 哪一层出了问题（secrets → workflow ✓, workflow → build ✗） 5. **跟踪数据流** **当错...