排错优先

排错优先#

先弄清坏在哪一层，再动手改。跳步改代码是排错最常见的浪费。 这个技能不含脚本，不联网；只读用户给的内容，要改文件时按用户的指示做。

顺序不能反#

1. 复现：先确认能稳定重来一次。
2. 读原始错误：从第一行读到最后一行的 caused by。
3. 划边界：是代码、依赖、环境，还是数据。
4. 单变量验证：一次只改一个东西，先证明假设再修。
5. 才动手改：最小改动，修因不修果。

1 复现#

• 记下触发条件：什么输入、什么命令、什么环境、第几次出现。
• 复现不了就先说明复现不了，列出已知条件，请用户补；不要在没复现的情况下声称已修复。
• 偶发问题先看时间规律（并发、缓存、超时、时区、随机种子），不要当必现问题改。

2 读原始错误#

• 读完整堆栈，不要只看最后一行。异常类型和消息常常不是根因。
• 找第一处指向「用户自己代码」的帧，那是排查起点；上面是调用方，下面是库内部。
• 分清 caused by（根因）和 during handling of / re-raised（包装后的次生错误）。
• 报错里的路径、行号、版本号、请求 id 原样记下，不要意译。

3 划边界#

先判断坏在哪一层，四选一：

• 代码：能稳定复现、只在这条路径出错、最近改动过。
• 依赖：升级/降级后出现，或报错来自库内部且参数合法。
• 环境：换机器就变、缺变量、权限、编码、端口占用、版本不一致。
• 数据：同代码不同数据结果不同，空值、超长、非 UTF-8、类型不符。

缩小范围的办法：输入减半、注释掉一半步骤、换最小样例、在中间打点确认走到哪一步。

4 单变量验证#

• 一次只改一处，改完立刻验证，记下结果。
• 先把假设写成一句可验证的话：「因为 X，所以 Y」，再设计能证伪它的最小实验。
• 不要同时改配置和代码；不要靠重装环境碰运气。

5 修#

• 最小改动，能一行解决就不重构。
• 修根因，不修症状：吞异常、加空 try、放宽断言、改测试期望值、加大超时都不算修好。
• 修完给出验证方式：跑哪个命令、看哪个输出、在什么条件下算通过。

常见错#

• 看到报错直接改，改了三处，仍不知道哪处生效。
• 靠加 print 代替读堆栈，输出一堆却仍不知道边界。
• 把「不再报错」当成「修好了」——异常被绕过，行为可能仍然是错的。
• 复现不了就猜，猜完当成结论汇报。
• 只贴最后一行报错就下判断，忽略前面的 warning 和第一条 caused by。

输出方式#

一句话说清坏在哪一层和依据（哪个帧、哪次对比、哪个实验），再给最小修复和验证步骤。 信息不够就直说缺什么，不要用「可能是」「应该是」把不确定糊过去；推断要标成推断。