调试(Debugging)

调试把预期与实际的差异变成可复现的问题,再通过观察、提出假设和实验定位原因,最后修复并验证。

一句话定义

调试把预期与实际的差异变成可复现的问题,再通过观察、提出假设和实验定位原因,最后修复并验证。

为什么重要

  • 程序员相当一部分时间花在调试上。调试能力的差距,往往比写代码速度的差距更大。
  • 调试方法可以学习:高手不是靠直觉,而是靠系统的方法(复现、缩小范围、二分、对比)。
  • AI 代码让调试更常见:AI 生成的代码“看起来对”,问题常藏在边界条件和数据类型里。

使用边界

固定随机种子有助于缩小差异,但不能保证跨设备、依赖版本或非确定算子得到完全相同结果。记录模型输入也不必保存所有原始隐私内容,应保留足以复现的必要信息。

原理 / 图解

图 1

常用技巧:

技巧 说明
最小复现 删掉一切无关代码和数据,直到问题仍然出现的最小版本
二分法 在数据、代码版本(git bisect)、配置上对半缩小范围
打印探针 print(repr(x), type(x))——朴素但有效;Python 3.8+ 可用 f"{x=}"
断点调试 停在现场查看所有变量(见 k1.prog.breakpoint)
读栈追踪 从最后一行异常类型读起,再找自己代码的那一帧(见 k1.prog.stack-trace)
小黄鸭调试 把代码逐行讲给别人(或一只橡皮鸭)听,常常讲着讲着就发现问题
对比法 能跑的版本 vs 不能跑的版本,差异在哪

git bisect 用二分查找定位引入 bug 的提交:https://git-scm.com/docs/git-bisect

可运行示例

一个“平均分算错”的完整调试过程:复现 → 打印类型验证假设 → 二分定位坏数据 → 修复 → 回归测试(Python 3.15.0 一稿运行记录):

# 文件:examples/13_debugging.py
# 调试的科学方法:复现 → 假设 → 验证 → 修复 → 回归测试
def average_scores(records):
    total = 0
    for r in records:
        total += r["score"]
    return total / len(records)

data = [{"name": "a", "score": 90}, {"name": "b", "score": "85"}, {"name": "c", "score": 70}]

# 1) 复现
try:
    average_scores(data)
except TypeError as e:
    print("复现成功:", e)

# 2) 假设:某条记录的 score 不是数字。3) 验证:打印类型(最朴素也最有效的探针)
for r in data:
    print(f"  {r['name']}: {r['score']!r} -> {type(r['score']).__name__}")

# 二分法定位:在大数据里找第一条坏记录
def first_bad(rows):
    lo, hi = 0, len(rows)
    while lo < hi:
        mid = (lo + hi) // 2
        if all(isinstance(r["score"], (int, float)) for r in rows[: mid + 1]):
            lo = mid + 1
        else:
            hi = mid
    return lo
print("二分定位到第一条坏记录下标:", first_bad(data))

# 4) 修复:在边界处做类型规整  5) 回归测试
def average_scores_fixed(records):
    if not records:
        return 0.0
    return sum(float(r["score"]) for r in records) / len(records)
assert average_scores_fixed(data) == (90 + 85 + 70) / 3
assert average_scores_fixed([]) == 0.0
print("修复并通过回归测试:", round(average_scores_fixed(data), 2))

一稿留存输出:

复现成功: unsupported operand type(s) for +=: 'int' and 'str'
  a: 90 -> int
  b: '85' -> str
  c: 70 -> int
二分定位到第一条坏记录下标: 1
修复并通过回归测试: 81.67

根因不是“求平均的算法错了”,而是上游数据把分数存成了字符串 '85'。修复放在数据进入函数的边界处(统一转 float),并顺手处理了空列表除零这一隐藏 bug。

常见误区

  • 不复现就改:看到报错就凭感觉改,改完“好像好了”,其实只是没触发。
  • 修症状不修根因:用 try/except: pass 把异常吞掉,问题会在更远的地方以更怪的方式出现。
  • 一次改多处:同时改三个地方,好了也不知道是哪处起作用。
  • 不写回归测试:同一个 bug 三个月后又回来。
  • 把整段报错丢给 AI 却不给上下文:AI 只能猜。应同时提供最小复现、预期与实际结果、环境版本。

与 AI 开发的关系

  • AI 项目的特殊 bug:张量形状不匹配、dtype 不一致、设备不一致(CPU/GPU)、数据泄漏、随机性导致结果不可复现。调试时先固定随机种子、打印 shape/dtype/device。
  • LLM 应用的“bug”常常不是代码问题:而是提示词、检索结果或模型版本变化。要记录足以复现的输入摘要、模板和模型版本、相关结果与请求标识(见 k1.prog.logging),才能复现。
  • 让 AI 帮你调试的正确姿势:给出最小复现 + 完整栈追踪 + 你已经验证过的假设,请它列出“可能原因及验证方法”,而不是直接要补丁。
  • Python 3.15 新增采样分析器 Tachyon(profiling.sampling),可附加到运行中的进程排查性能问题。https://docs.python.org/3.15/whatsnew/3.15.html

延伸阅读

理解检查

修复后原输入不再报错,是否已经完成验证?

参考答案:还需检查预期输出、相邻边界和错误处理,并为已定位的根因保留回归检查。

核验与复现

核验日期:2026-10-14。示例状态:运行通过。本轮日志:13_debugging.py。

配套代码与核验资料

继续浏览基础 返回知识 →返回顶部 ↑
本篇目录
教程图解100%
教程图解