我要评论引言
python 以“简洁易读”著称，但即便是经验丰富的开发者，也常被各种错误搞得焦头烂额。这些错误不仅影响开发效率，还可能潜伏在生产环境中引发严重故障。
本文系统梳理了 python 中最常见的错误类型，并特别深入解析了 json 相关错误——这是 web 开发、api 调用和数据处理中最频繁出现的问题之一。每类错误都配有 真实示例 + 原理解释 + 解决方案，助你快速排错、写出健壮代码。
一、错误分类概览
python 错误主要分为三类：
- 语法错误（syntaxerror） ：代码不符合 python 语法规则，解释器直接拒绝运行。
- 运行时异常（exceptions） ：程序能启动，但在执行过程中因逻辑或环境问题崩溃。
- 逻辑错误（logic errors） ：代码能运行且不报错，但结果不符合预期（最难调试）。
我们重点讨论前两类，并加入 json 专项章节。
二、语法错误（syntaxerror）
这类错误在保存或运行脚本时立即暴露。
常见场景：
- 缺少冒号
:（if,for,def后必须加） - 括号/引号不匹配
- 错误缩进（混用空格与 tab）
# ❌ 典型错误
if x > 0
print("positive") # syntaxerror: invalid syntax
# ✅ 正确写法
if x > 0:
print("positive")
建议：使用支持语法高亮和括号匹配的编辑器（如 vs code、pycharm）。
三、运行时异常（exceptions）
1. nameerror：变量未定义
print(username) # nameerror: name 'username' is not defined
解决：确保变量已赋值，注意作用域。
2. attributeerror：对象无此属性
[].push(1) # attributeerror: 'list' object has no attribute 'push'
解决：查官方文档，确认方法名（如 list.append()）。
3. indexerror / keyerror：越界访问
d = {"name": "alice"}
print(d["age"]) # keyerror: 'age'
安全访问：
d.get("age", "未知") # 推荐
# 或
if "age" in d: ...
4. typeerror：类型不匹配
"5" + 3 # typeerror: can only concatenate str (not "int") to str
解决：显式转换类型，如 int("5") + 3。
5. valueerror：值合法但不符合要求
int("abc") # valueerror: invalid literal for int()
防御性编程：
try:
num = int(user_input)
except valueerror:
print("请输入有效数字")
6. zerodivisionerror：除零错误
10 / 0 # zerodivisionerror
检查分母：
if denominator != 0:
result = numerator / denominator
7. filenotfounderror：文件不存在
open("missing.txt") # filenotfounderror
安全打开：
import os
if os.path.exists("file.txt"):
with open("file.txt") as f: ...
8. modulenotfounderror：模块未安装
import requests # modulenotfounderror（若未安装）
解决：
pip install requests
四、经典逻辑陷阱
可变默认参数（mutable default argument）
# ❌ 危险！
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
import json
data = "{'name': 'alice'}" # 注意：用了单引号！
json.loads(data) # jsondecodeerror: expecting property name enclosed in double quotes
原因：json 标准要求 键和字符串必须用双引号 " ，单引号无效。
解决：
- 确保数据源输出标准 json（如后端用
json.dumps()） - 若必须解析非标准字符串，可先替换：
data = data.replace("'", '"')
场景 2：末尾多余逗号
data = '{"name": "alice", "age": 30,}' # 末尾逗号
json.loads(data) # jsondecodeerror
解决：使用在线 json 校验工具（如 jsonlint.com）验证。
场景 3：响应体为空或 html
# 模拟请求返回 404 页面（html） response_text = "<html>not found</html>" json.loads(response_text) # jsondecodeerror
防御性处理：
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 支持的类型 序列化时发生：
import json
from datetime import datetime
data = {"time": datetime.now()}
json.dumps(data) # typeerror: object of type datetime is not json serializable
解决方法：
方法 1：自定义default函数
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：提前转换
data = {"time": datetime.now().isoformat()}
json.dumps(data) # ok
方法 3：使用第三方库（如orjson、ujson）支持更多类型
3. 中文乱码问题（编码错误）
# 写入文件
with open("config.json", "w") as f:
json.dump({"消息": "你好"}, f)
# 读取时可能乱码（尤其在 windows）
解决：显式指定 utf-8 编码
# 写入
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精准捕获
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
def parse_user(data: str) -> dict:
return json.loads(data) # mypy 可检查返回类型
3. 单元测试覆盖异常路径
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开发中最常见的错误大全及解决方法的详细内容，更多关于python最常见的错误大全的资料请关注代码网其它相关文章！
发表评论