在 Python 开发中，
AssertionError 是非常常见的异常类型，它是断言语句（assert） 失败后抛出的错误。很多新手遇到这个错误会一头雾水，不知道是代码逻辑错了还是数据出了问题。这篇文章会用通俗易懂的方式，带你彻底搞懂
AssertionError 是什么、为什么会出现，以及最快、最实用的排查方法，帮你轻松搞定这个常见问题。一、先搞懂：什么是 assert（断言）？
assert 是 Python 内置的调试工具，作用是检查某个条件必须为真，如果条件不满足，就直接抛出 AssertionError，中断程序运行。它的语法非常简单：
python
运行
# 基础语法
assert 条件判断, 可选的错误提示信息
工作原理：
- 条件为
True→ 程序正常运行，无任何提示； - 条件为
False→ 直接抛出AssertionError，程序停止。
简单示例：
python
运行
# 正确：条件成立，无报错
assert 1 + 1 == 2, "数学计算错误"
# 错误：条件不成立，抛出 AssertionError
assert 1 + 1 == 3, "数学计算错误"
运行后报错：
plaintext
AssertionError: 数学计算错误
二、AssertionError 到底是什么？
AssertionError 不是代码语法错误，而是 **「预期和实际结果不匹配」** 的调试错误。简单说：你用 assert 设定了一个必须满足的规则，结果数据 / 逻辑打破了这个规则，Python 就报错提醒你。
它的常见用途：
- 检查函数入参是否合法（比如不能为负数、不能为空）
- 检查计算结果是否符合预期
- 调试时快速定位逻辑漏洞
- 验证数据格式是否正确
三、最常见的 4 种 AssertionError 场景
先看高频错误场景，你遇到的问题大概率在这：
场景 1：函数参数不符合预期（最常见）
python
运行
def calculate_price(price):
# 约定：价格必须大于 0
assert price > 0, "价格不能为负数或 0"
return price * 1.1
# 调用函数传入负数 → 触发断言错误
calculate_price(-50)
报错：
AssertionError: 价格不能为负数或 0场景 2：数据类型不匹配
python
运行
def print_name(name):
assert isinstance(name, str), "姓名必须是字符串类型"
print(f"姓名：{name}")
# 传入数字 → 报错
print_name(123)
场景 3：计算结果不符合预期
python
运行
def add(a, b):
result = a + b
# 预期结果必须小于 100
assert result < 100, "计算结果超出范围"
return result
add(60, 50) # 110 ≥ 100 → 断言错误
场景 4：列表 / 字典为空（业务不允许）
python
运行
def get_first_item(data_list):
assert len(data_list) > 0, "列表不能为空"
return data_list[0]
get_first_item([]) # 空列表 → 报错
四、万能排查步骤：3 步定位 AssertionError
不管断言错误多复杂，按照这 3 步走，100% 能找到问题根源：
第一步：看报错信息，锁定出错代码行
Python 会直接告诉你哪一行代码触发了断言，示例：
plaintext
AssertionError: 价格不能为负数或 0
直接定位到对应行，查看断言条件。
第二步：打印断言相关变量，查看实际值
断言的核心是「条件不成立」，所以一定要打印变量的实际值，这是最关键的一步！
修改代码，打印变量：
python
运行
def calculate_price(price):
# 打印实际传入的值
print(f"实际传入的价格：{price}")
assert price > 0, "价格不能为负数或 0"
return price * 1.1
calculate_price(-50)
运行后一目了然：
实际传入的价格：-50，问题直接暴露。第三步：判断「预期」和「实际」是否一致
- 你的断言条件（预期）：
price > 0 - 实际值：
-50 - 结论：不一致 → 断言失败
排查完成：要么是传入的参数错误，要么是断言条件写得不合理。
五、进阶排查技巧（解决复杂场景）
1. 自定义清晰的错误提示
不要写空断言！一定要加中文提示，直接告诉你错在哪：
python
运行
# 不推荐（报错无信息）
assert price > 0
# 推荐（报错直接定位原因）
assert price > 0, f"传入的价格 {price} 无效，必须大于 0"
2. 用 try-except 捕获 AssertionError
生产环境不想程序直接崩溃，可以捕获异常：
python
运行
try:
assert 1 + 1 == 3
except AssertionError as e:
print(f"捕获到断言错误：{e}")
# 做容错处理
3. 区分「断言错误」和「业务错误」
重要提醒：
assert仅用于开发调试，关闭调试模式后会失效；- 正式业务的参数校验，推荐用
if + ValueError替代：
python
运行
# 生产环境推荐写法
def calculate_price(price):
if price <= 0:
raise ValueError("价格不能为负数或 0")
return price * 1.1
4. 关闭断言（临时绕过错误）
调试时如果想临时跳过断言，运行 Python 时加
-O 参数：bash
运行
python -O your_script.py
⚠️ 仅用于调试，不要在正式代码中依赖这个功能。
六、避坑指南：新手最容易犯的 3 个错
- 把断言当业务校验：assert 会被优化掉，正式环境不要用；
- 断言条件写反：比如写成
assert a < 0，实际需要a > 0； - 不写错误信息：空断言报错后，完全不知道错因。
七、总结
AssertionError 本质是 **「预期≠实际」** 的调试提醒，排查核心就一件事：
查看断言条件 + 打印变量实际值，对比两者是否一致。
快速排查口诀：
一看报错行，二打变量值，三对预期差，问题全解决。
总结
AssertionError是assert条件不满足触发的调试错误；- 排查三步法：定位代码行 → 打印实际值 → 对比预期值；
- 断言仅用于调试，生产环境用异常处理做参数校验；
- 写断言一定要加清晰的中文错误提示，大幅提升排错效率。
