Python 常见的 15 个错误与修复方法
SyntaxError、IndentationError、NameError、TypeError……本文收集 Python 开发中常见的 15 个错误，逐一给出原因分析与修复方法，新手排障速查。
直接回答：Python 报错不可怕，可怕的是看不懂。本文把 15 个常见错误按"报错长什么样 → 为什么发生 → 怎么修"讲解，供日常排障定位参考；这不是错误频率统计。
1. SyntaxError：语法错误
解释器连代码都读不懂。高频原因：字符串没闭合、括号不配对、语句末尾多了冒号少了冒号。报错行号往往是"发现问题的地方"，真正的漏写可能在上一行——往前看一行是排查口诀。
2. IndentationError：缩进错误
Python 用缩进表达层级，混用 Tab 与空格、if 下面忘了缩进都会触发。编辑器统一设为空格缩进（4 格），可减少混用问题；代码块的层级和缺失的缩进仍需逐处修正。
3. NameError：名字不存在
print(user_name) # NameError: name 'user_name' is not defined
拼写错误、变量定义在使用之后、忘了 import。检查三连：拼对了吗？定义了吗？导入了吗？
4. ValueError：值不对
int("abc") # ValueError
类型对但值非法。用户输入先校验再转换，或 try/except 接住给友好提示。
5. UnboundLocalError：局部变量未赋值就用
def f():
print(count) # UnboundLocalError
count = 1
函数内对变量赋值会让 Python 把它当局部变量，赋值前的读取直接炸。想用外层变量：读取没问题，修改需 nonlocal/global 声明。
6. TypeError：类型用错
"1" + 1、把 None 当下标、函数参数个数不对。看清报错里说的两个类型，检查数据来源（用户输入、接口返回值都是字符串重灾区）。
7. UnicodeError：编码错误
读文件没指定编码、GBK 文件用 UTF-8 打开。文本文件应显式指定与文件实际内容一致的编码，例如 UTF-8 文件使用 encoding="utf-8"。二进制模式不传 encoding；来源不明时优先确认生产方约定，编码探测只能提供推测。
8. ZeroDivisionError：除零
除法与取模前检查除数；用户输入场景用 try/except 或默认值兜底。
9. FileNotFoundError：文件不存在
相对路径是头号陷阱——脚本的工作目录不是文件所在目录。用 pathlib.Path(__file__).parent / "data.csv" 构造锚定路径。
10. ModuleNotFoundError：找不到模块
没安装（pip install）、装到了别的环境（pip -V 核对路径）、文件名与库冲突（自己的文件叫 json.py 把标准库挡了）。
11. MemoryError：内存耗尽
一次性读入大文件、无限增长的列表。改生成器流式处理、分块读取；真需要大数据集上 DuckDB/分片。
12. PermissionError：权限不足
写系统目录、文件被占用（Windows 常见）、端口需要特权。换用户目录、关闭占用程序、换高位端口。
13. IndexError：下标越界
items[5] # 列表只有 3 个
循环用 for x in items 而非下标；必须下标时先判 len。
14. KeyError：字典键不存在
data["email"] # KeyError
改用 data.get("email", "默认值")；或 if "email" in data 先判。JSON 接口数据字段缺失是常客。
15. AttributeError：对象没这个属性
None.xxx 是最常见形态（上游函数返回了 None）；其次是拼写与类型误判（字符串调了列表方法）。加判空、看类型注解、print(type(x)) 三连定位。
生产环境怎么办
开发期报错有堆栈，生产期要靠体系：结构化日志带 request_id、未捕获异常进错误监控、告警到人。观测云 APM 需先接入兼容的 Python 探针；框架支持范围、异常是否落在被追踪操作内及采样策略会影响可见性。日志关联要求实际采集并统一 request_id 或 trace_id，异常率告警需要配置相应监控规则，不能保证覆盖所有报错或先于用户发现。 参考 1 参考 2
常见问题（FAQ）
Q：报错堆栈怎么看？
A：从下往上读——最底部是错误类型与信息，往上是你代码触发的位置，再往上是调用链。先看最后一行定类型，再找第一个"自己写的文件"定位现场。
Q：try/except 该包多大范围？
A：越小越好，只包会出错的那一行，并且只捕获具体异常类型。裸 except: 会把 KeyboardInterrupt 都吞掉，是公认的反模式。
Q：有些错误 intermittent（偶发）怎么办？
A：多半是并发竞态或外部依赖抖动。加日志记录上下文快照，提高重试与超时防御，观察规律后再对症下药。
官方参考
本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。
