python 错误讯息

February 7, 2026

AI教程

Python 错误讯息详解与排查教程#

本教程面向初学者与中级开发者，帮助你快速定位、理解并解决常见的 Python 错误讯息。
通过阅读错误信息、分析根因、遵循三种分步骤的解决方案，你将能够更高效地调试代码。

1. 错误讯息概览#

Python 在运行时会抛出 异常（Exception），其错误讯息（traceback）由两部分组成：

异常类型（如 SyntaxError、NameError、TypeError 等）
错误描述（具体问题的文字说明）
Traceback（调用堆栈，指明错误发生的位置）

示例：

Traceback (most recent call last):
  File "example.py", line 5, in <module>
    print(unknown_variable)
NameError: name 'unknown_variable' is not defined

2. 常见错误类型与典型原因#

错误类型	典型原因	典型错误讯息
`SyntaxError`	语法错误，例如缺失冒号、括号不匹配	`invalid syntax`
`IndentationError`	缩进不一致（混用空格和制表符）	`unexpected indent`
`NameError`	变量或函数未定义或未导入	`name 'x' is not defined`
`TypeError`	传递了错误类型的参数，例如 `int + str`	`can only concatenate str (not "int") to str`
`AttributeError`	对象没有该属性	`module 'math' has no attribute 'sqrt'`
`IndexError`	列表/元组索引越界	`list index out of range`
`KeyError`	字典键不存在	`key 'abc' not found`
`ValueError`	值不符合预期	`invalid literal for int() with base 10: 'abc'`
`ImportError/ModuleNotFoundError`	模块未安装或路径错误	`No module named 'foo'`
`RuntimeError`	运行时错误，例如递归过深	`maximum recursion depth exceeded`

小贴士：错误类型往往能直接告诉你问题所在。先阅读错误类型，然后再关注具体描述。

3. 解决方案一：逐行检查 Traceback#

定位文件与行号
- Traceback 会列出 File 与 line。先打开对应文件，定位到该行。
检查语法
- 对于 SyntaxError，检查缺失的冒号、括号、引号等。
检查变量/函数
- 对于 NameError，确认变量已被定义或已导入。
打印调试信息
- 在关键位置插入 print() 或 logging，查看变量值是否符合预期。

示例
# 缺失冒号导致 SyntaxError
if x > 5
    print(x)
解决：在 if 语句末尾加冒号 :。

4. 解决方案二：利用 IDE 与 REPL#

使用 IDE 的错误高亮
- VSCode、PyCharm 等会在代码中实时标记错误。
逐步执行（Debug）
- 设置断点，逐行运行，观察变量状态。
使用交互式解释器（REPL）
- 将疑难代码逐行粘贴到 Python shell，快速验证。

示例

>>> a = [1, 2, 3]
>>> a[5]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: list index out of range

通过 REPL 立即发现索引越界。

5. 解决方案三：借助第三方工具#

pylint / flake8
- 代码静态检查，能在运行前捕获大部分错误。
mypy（类型检查）
- 通过类型注解发现 TypeError 的潜在风险。
pytest + pytest-xdist
- 编写单元测试，快速定位失败点。
coverage.py
- 查看哪些代码路径未被执行，帮助发现隐藏错误。

示例
pip install pylint
pylint example.py
结果会给出错误行号与建议。

6. 常见问题解答（FAQ）#

问题	解答
Q1：为什么我的错误讯息只有一行？	这通常是 `ImportError` 或 `ModuleNotFoundError`，检查模块名、路径是否正确。
Q2：`IndentationError` 出现但我只用空格缩进。	可能是文件中混用了空格和制表符，建议统一使用 4 个空格。
Q3：我在 Jupyter Notebook 里遇到 `KeyError`，但在普通脚本里没有。	Notebook 的全局变量可能被多次执行导致状态不一致，使用 `reset` 或 `clear all` 重新执行。
Q4：为什么 `AttributeError` 会出现在标准库模块上？	可能是你误写了模块名（如 `math.sqrtx`），或文件名冲突（例如同名 `.py` 文件遮蔽标准库）。
Q5：如何快速查看错误堆栈的最外层调用？	只保留 `stacklevel=1` 的 `raise`，或使用 `traceback.print_exc()`。
Q6：我使用 `typing` 时遇到 `TypeError`，原因是什么？	`typing` 的类型注解不会在运行时强制检查，必须结合 `mypy` 或 `pyright`。
Q7：`RuntimeError: maximum recursion depth exceeded` 怎么解决？	检查递归函数是否有终止条件，或使用迭代替代。

7. 小结#

先看异常类型 → 了解大致错误种类。
查看 Traceback → 精准定位文件和行号。
逐步调试 → 使用 IDE、REPL、打印信息。
使用工具 → pylint、mypy、单元测试等提前发现错误。

掌握上述思路，你将能在日常开发中快速定位和解决 Python 错误讯息。祝编码愉快 🚀!