栈追踪(Stack Trace / Traceback)

栈追踪记录异常传播经过的调用位置;结合异常类型、消息与异常链,可以从报错现场追溯更早的原因。

一句话定义

栈追踪记录异常传播经过的调用位置;结合异常类型、消息与异常链,可以从报错现场追溯更早的原因。

为什么重要

  • 它是最重要的调试线索,而且是免费的——不用加任何代码就有。
  • 看懂它能省下大量时间:很多新手看到一大片红字就慌,其实答案常常就写在最后一行。
  • 也是向别人(或 AI)求助时最该附上的信息。

使用边界

最后一行是当前异常的摘要,不一定是整个故障的根因。库帧、异常链和异步设备错误都可能包含关键线索,应结合输入与调用上下文阅读。

原理 / 图解

每次函数调用会在调用栈上压入一个“栈帧”(记录函数名、文件、行号、局部变量)。出错时,Python 从栈底到栈顶打印这些帧:

图 1

阅读顺序口诀:

  1. 先看最后一行:异常类型 + 消息(RuntimeError: 配置文件格式错误)。
  2. 往上找你自己的代码:自己的代码是常见检查入口,但库帧和错误输入也可能揭示根因。
  3. 看异常链:“The above exception was the direct cause of the following exception” 表示前一个异常是后一个异常的直接原因(用了 raise ... from e);若写的是 “During handling of the above exception, another exception occurred”,则表示在处理异常时又出了新错。

Python 3.11 起,traceback 用 ~~~^^^ 精确标出出错的表达式位置(PEP 657):https://peps.python.org/pep-0657/ ;traceback 模块文档:https://docs.python.org/3/library/traceback.html

可运行示例

一个“配置文件多了个逗号”的错误,经过两层包装后的完整栈追踪,以及用 traceback 模块程序化地分析它(Python 3.15.0 一稿运行记录):

# 文件:examples/15_stack_trace.py
# 读懂 Stack Trace:从下往上读;以及异常链 (raise ... from ...)
import traceback, json

def parse_config(text):
    return json.loads(text)

def load_settings(text):
    try:
        cfg = parse_config(text)
    except json.JSONDecodeError as e:
        raise RuntimeError("配置文件格式错误") from e   # 保留原始原因
    return cfg["model"]

def main():
    return load_settings('{"model": "deepseek",}')     # 多了一个逗号

try:
    main()
except RuntimeError:
    tb = traceback.format_exc()
    print(tb.replace(__file__, "15_stack_trace.py"))

# 程序化地获取栈帧信息(日志/监控系统就是这样提取"出错位置"的)
try:
    main()
except RuntimeError as e:
    frames = traceback.extract_tb(e.__traceback__)
    last = frames[-1]
    print("最内层帧:", last.name, "第", last.lineno, "行")
    print("根因类型:", type(e.__cause__).__name__)

一稿留存输出(Python 解释器路径已简写为 <python3.15>):

Traceback (most recent call last):
  File "15_stack_trace.py", line 9, in load_settings
    cfg = parse_config(text)
  File "15_stack_trace.py", line 5, in parse_config
    return json.loads(text)
           ~~~~~~~~~~^^^^^^
  File "<python3.15>/lib/python3.15/json/__init__.py", line 371, in loads
    return _default_decoder.decode(s)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^
  File "<python3.15>/lib/python3.15/json/decoder.py", line 358, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
  File "<python3.15>/lib/python3.15/json/decoder.py", line 374, in raw_decode
    obj, end = self.scan_once(s, idx)
               ~~~~~~~~~~~~~~^^^^^^^^
json.decoder.JSONDecodeError: Illegal trailing comma before end of object: line 1 column 21 (char 20)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "15_stack_trace.py", line 18, in <module>
    main()
    ~~~~^^
  File "15_stack_trace.py", line 15, in main
    return load_settings('{"model": "deepseek",}')     # 多了一个逗号
  File "15_stack_trace.py", line 11, in load_settings
    raise RuntimeError("配置文件格式错误") from e   # 保留原始原因
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
RuntimeError: 配置文件格式错误

最内层帧: load_settings 第 11 行
根因类型: JSONDecodeError

几个细节:

  • ~~~~~~~~~~^^^^^^ 指出了具体是哪个子表达式出错。
  • JSONDecodeError 的行列位置帮助定位非法逗号;消息措辞会随 Python 版本变化。
  • 因为用了 from e,原始的 JSONDecodeError 被完整保留,没有丢失根因。

常见误区

  • 只看第一行或中间某行:最后一行概括当前异常,结合异常链及相关调用帧继续追查根因。
  • 截图发给别人:应复制文本,方便搜索和让 AI 解析。
  • raise NewError(...) 不加 from e:在 except 块中直接抛新异常时 Python 仍会保留上下文(显示为“During handling…”),但用 from e 能更明确地表达因果;from None 则会刻意隐藏原始异常,只在原始异常确实无用时使用。
  • 用 print(e) 代替完整栈:只打印消息会丢失位置信息。记录日志时应使用 logger.exception(...)(见 k1.prog.logging)。

与 AI 开发的关系

  • 深度学习的栈追踪很长:PyTorch 报错常穿过几十层框架代码。重点找你自己的 forward/训练循环那一帧,以及最后的形状/设备信息(如 mat1 and mat2 shapes cannot be multiplied)。
  • CUDA 错误是异步报告的:GPU 报错时栈追踪指向的行可能不是真正出错的地方。PyTorch 文档建议设置 CUDA_LAUNCH_BLOCKING=1 同步执行以定位:https://docs.pytorch.org/docs/stable/notes/cuda.html
  • 把栈追踪交给 AI 时:贴完整文本、说明你的代码是哪几帧、附上相关代码片段;注意先删除栈追踪中可能出现的密钥、内网路径、用户数据。

延伸阅读

理解检查

出现“direct cause”时,应只看最下面的异常吗?

参考答案:应同时看显式原因链;外层异常描述业务失败,内层异常可能解释具体触发原因。

核验与复现

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

配套代码与核验资料

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