Python 开发中最常见的错误大全（含 JSON 专项解析）

副标题：从 SyntaxError 到 JSONDecodeError，一文帮你避开 90% 的坑

Python 以"简洁易读"著称，但即便是经验丰富的开发者，也常被各种错误搞得焦头烂额。这些错误不仅影响开发效率，还可能潜伏在生产环境中引发严重故障。

本文系统梳理了 Python 中最常见的错误类型 ，并特别深入解析了 JSON 相关错误 ------这是 Web 开发、API 调用和数据处理中最频繁出现的问题之一。每类错误都配有 真实示例 + 原理解释 + 解决方案，助你快速排错、写出健壮代码。

一、错误分类概览

Python 错误主要分为三类：

语法错误（SyntaxError） ：代码不符合 Python 语法规则，解释器直接拒绝运行。
运行时异常（Exceptions） ：程序能启动，但在执行过程中因逻辑或环境问题崩溃。
逻辑错误（Logic Errors） ：代码能运行且不报错，但结果不符合预期（最难调试）。

我们重点讨论前两类，并加入 JSON 专项章节。

二、语法错误（SyntaxError）

这类错误在保存或运行脚本时立即暴露。

常见场景：

缺少冒号 :（if, for, def 后必须加）
括号/引号不匹配
错误缩进（混用空格与 Tab）

bash 复制代码

# ❌ 典型错误
if x > 0
    print("positive")  # SyntaxError: invalid syntax

# ✅ 正确写法
if x > 0:
    print("positive")

💡 建议：使用支持语法高亮和括号匹配的编辑器（如 VS Code、PyCharm）。

三、运行时异常（Exceptions）

1. NameError：变量未定义

scss 复制代码

print(username)  # NameError: name 'username' is not defined

✅ 解决：确保变量已赋值，注意作用域。

2. AttributeError：对象无此属性

scss 复制代码

[].push(1)  # AttributeError: 'list' object has no attribute 'push'

✅ 解决：查官方文档，确认方法名（如 list.append()）。

3. IndexError / KeyError：越界访问

ini 复制代码

d = {"name": "Alice"}
print(d["age"])  # KeyError: 'age'

✅ 安全访问：

csharp 复制代码

d.get("age", "未知")  # 推荐
# 或
if "age" in d: ...

4. TypeError：类型不匹配

bash 复制代码

"5" + 3  # TypeError: can only concatenate str (not "int") to str

✅ 解决：显式转换类型，如 int("5") + 3。

5. ValueError：值合法但不符合要求

perl 复制代码

int("abc")  # ValueError: invalid literal for int()

✅ 防御性编程：

python 复制代码

try:
    num = int(user_input)
except ValueError:
    print("请输入有效数字")

6. ZeroDivisionError：除零错误

bash 复制代码

10 / 0  # ZeroDivisionError

✅ 检查分母：

ini 复制代码

if denominator != 0:
    result = numerator / denominator

7. FileNotFoundError：文件不存在

perl 复制代码

open("missing.txt")  # FileNotFoundError

✅ 安全打开：

lua 复制代码

import os
if os.path.exists("file.txt"):
    with open("file.txt") as f: ...

8. ModuleNotFoundError：模块未安装

python 复制代码

import requests  # ModuleNotFoundError（若未安装）

✅ 解决：

复制代码

pip install requests

四、经典逻辑陷阱

可变默认参数（Mutable Default Argument）

python 复制代码

# ❌ 危险！
def add(item, lst=[]):
    lst.append(item)
    return lst

print(add(1))  # [1]
print(add(2))  # [1, 2] ← 意外共享！

# ✅ 正确
def add(item, lst=None):
    if lst is None:
        lst = []
    lst.append(item)
    return lst

📌 黄金法则 ：永远不要用 list、dict、set 等可变对象作为函数默认参数！

五、JSON 专项：最常被忽视的错误源

在 API 开发、配置文件读取、前后端通信中，JSON 是数据交换的通用语言。但处理不当极易出错。

1. `json.JSONDecodeError`：JSON 格式非法

这是 最常见 的 JSON 错误，通常由以下原因引起：

❌ 场景 1：字符串不是合法 JSON

ini 复制代码

import json

data = "{'name': 'Alice'}"  # 注意：用了单引号！
json.loads(data)  # JSONDecodeError: Expecting property name enclosed in double quotes

✅ 原因：JSON 标准要求 键和字符串必须用双引号 " ，单引号无效。

✅ 解决：

确保数据源输出标准 JSON（如后端用 json.dumps()）
若必须解析非标准字符串，可先替换：
ini 复制代码
```
data = data.replace("'", '"')
```

❌ 场景 2：末尾多余逗号

makefile 复制代码

data = '{"name": "Alice", "age": 30,}'  # 末尾逗号
json.loads(data)  # JSONDecodeError

✅ 解决：使用在线 JSON 校验工具（如 jsonlint.com）验证。

❌ 场景 3：响应体为空或 HTML

ini 复制代码

# 模拟请求返回 404 页面（HTML）
response_text = "<html>Not Found</html>"
json.loads(response_text)  # JSONDecodeError

✅ 防御性处理：

python 复制代码

import json
import requests

resp = requests.get("https://api.example.com/data")
try:
    data = resp.json()  # requests 内部调用 json.loads()
except json.JSONDecodeError:
    print("响应不是 JSON！状态码:", resp.status_code)
    print("原始内容:", resp.text[:200])

2. `TypeError: Object of type xxx is not JSON serializable`

当你尝试把 非 JSON 支持的类型 序列化时发生：

typescript 复制代码

import json
from datetime import datetime

data = {"time": datetime.now()}
json.dumps(data)  # TypeError: Object of type datetime is not JSON serializable

✅ 解决方法：

方法 1：自定义 `default` 函数

python 复制代码

def json_serializer(obj):
    if isinstance(obj, datetime):
        return obj.isoformat()
    raise TypeError(f"Type {type(obj)} not serializable")

json.dumps(data, default=json_serializer)

方法 2：提前转换

css 复制代码

data = {"time": datetime.now().isoformat()}
json.dumps(data)  # OK

方法 3：使用第三方库（如 `orjson`、`ujson`）支持更多类型

3. 中文乱码问题（编码错误）

python 复制代码

# 写入文件
with open("config.json", "w") as f:
    json.dump({"消息": "你好"}, f)

# 读取时可能乱码（尤其在 Windows）

✅ 解决：显式指定 UTF-8 编码

python 复制代码

# 写入
with open("config.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False)  # 关键：ensure_ascii=False

# 读取
with open("config.json", "r", encoding="utf-8") as f:
    data = json.load(f)

🔑 两个关键参数：

encoding="utf-8"：确保文件以 UTF-8 读写

ensure_ascii=False：允许输出中文而非 \u4f60\u597d

六、最佳实践：如何避免和快速定位错误？

1. 使用 `try...except` 精准捕获

python 复制代码

try:
    data = json.loads(api_response)
except json.JSONDecodeError as e:
    logger.error(f"JSON 解析失败: {e.msg} at line {e.lineno}")
except Exception as e:
    logger.error(f"未知错误: {e}")

2. 启用类型提示 + mypy

python 复制代码

def parse_user(data: str) -> dict:
    return json.loads(data)  # mypy 可检查返回类型

3. 单元测试覆盖异常路径

scss 复制代码

def test_invalid_json():
    with pytest.raises(json.JSONDecodeError):
        parse_user("{'invalid': json}")

4. 日志记录原始数据

当 JSON 解析失败时，务必记录原始字符串，便于复现问题。

七、总结

错误类型	高频场景	防御策略
`SyntaxError`	缩进、冒号、括号	使用智能 IDE
`NameError`	变量未定义	检查拼写与作用域
`JSONDecodeError`	非标准 JSON、空响应	校验 + try-except + 记录原始数据
`TypeError`（序列化）	datetime、自定义对象	自定义 `default` 或预转换
可变默认参数	函数默认值为 list/dict	用 `None` 代替

记住：
"错误不是敌人，而是你代码的反馈。"

学会阅读错误信息（尤其是 traceback 和 JSONDecodeError 的 lineno），是成为高效 Python 开发者的关键一步。

延伸阅读：

Python 官方异常文档
JSON 标准 RFC 8259
《Effective Python》第 5 条：了解 Python 的 slice 和异常机制

希望这篇文章能成为你日常开发的"避坑指南"。如果你觉得有用，欢迎点赞、收藏或分享给团队小伙伴！

✍️ 作者：一位踩过无数 JSON 坑的 Python 工程师

📅 更新日期 ：2025 年 12 月

🏷️ 标签：#Python #JSON #错误处理 #开发技巧 #后端开发

Python 开发中最常见的错误大全（含 JSON 专项解析）

一、错误分类概览

二、语法错误（SyntaxError）

常见场景：

三、运行时异常（Exceptions）

1. NameError：变量未定义

2. AttributeError：对象无此属性

3. IndexError / KeyError：越界访问

4. TypeError：类型不匹配

5. ValueError：值合法但不符合要求

6. ZeroDivisionError：除零错误

7. FileNotFoundError：文件不存在

8. ModuleNotFoundError：模块未安装

四、经典逻辑陷阱

可变默认参数（Mutable Default Argument）

五、JSON 专项：最常被忽视的错误源

1. json.JSONDecodeError：JSON 格式非法

❌ 场景 1：字符串不是合法 JSON

❌ 场景 2：末尾多余逗号

❌ 场景 3：响应体为空或 HTML

2. TypeError: Object of type xxx is not JSON serializable

方法 1：自定义 default 函数

方法 2：提前转换

方法 3：使用第三方库（如 orjson、ujson）支持更多类型

3. 中文乱码问题（编码错误）

六、最佳实践：如何避免和快速定位错误？

1. 使用 try...except 精准捕获

2. 启用类型提示 + mypy

3. 单元测试覆盖异常路径

4. 日志记录原始数据

七、总结

1. `json.JSONDecodeError`：JSON 格式非法

2. `TypeError: Object of type xxx is not JSON serializable`

方法 1：自定义 `default` 函数

方法 3：使用第三方库（如 `orjson`、`ujson`）支持更多类型

1. 使用 `try...except` 精准捕获