ExceptionGroup 是 Python 3.11 引入的并发异常容器,必须用 except 捕获,普通 except 无法匹配因其不继承子异常类型;except 可提取指定类型的子异常组成新 group,未匹配的异常自动冒泡;常见于 asyncio.TaskGroup 或 trio 任务失败场景。

ExceptionGroup 是 Python 3.11 引入的正式机制,专为结构化聚合并发异常设计;它不是“多个异常拼在一起”,而是可遍历、可匹配、可重抛的异常容器,必须用 except* 捕获,普通 except 无法处理。
为什么不能用普通 try/except 捕获 ExceptionGroup?
因为 ExceptionGroup 本身是异常对象,但它的类型不是你期望的子异常(比如 TimeoutError 或 ConnectionError),而是一个包装器。普通 except ValueError: 或 except Exception: 都会跳过它——Python 认为“这不属于你要抓的那类异常”。
-
ExceptionGroup不继承自被包含的异常类型(例如不继承TimeoutError),所以类型检查失败 - 即使写
except Exception:,也只捕获顶层异常,而ExceptionGroup是顶层,其内部异常仍处于“未处理”状态 - 不显式处理会导致未捕获异常终止程序,且 traceback 显示的是整个 group,难以定位具体失败项
必须用 except* 匹配子异常类型
except* 是 Python 3.11 新增语法,专门用于从 ExceptionGroup 中提取匹配的子异常。它不是“捕获一次”,而是“提取所有符合类型的子异常,组成新 group”。
try:
# 假设这是 trio.run 或 asyncio.gather(..., return_exceptions=True) 的结果
raise ExceptionGroup("concurrent tasks failed", [
TimeoutError("task A timeout"),
ConnectionError("task B refused"),
TimeoutError("task C timeout")
])
except* TimeoutError as eg:
print(f"有 {len(eg.exceptions)} 个超时:{[str(e) for e in eg.exceptions]}")
except* ConnectionError as eg:
print(f"连接错误:{eg.exceptions[0]}")
-
except* TimeoutError会匹配 group 中所有TimeoutError实例,打包成新的ExceptionGroup绑定到eg - 未被任何
except*匹配的异常会自动重新抛出(例如上面没写except* ConnectionError,那条就会冒泡) - 一个
except*分支只能匹配一种类型,不能写except* (TimeoutError, OSError)
常见来源:asyncio.gather 和 trio.StrictFork
目前最常触发 ExceptionGroup 的场景是并发任务失败。注意:asyncio.gather 默认“任一失败即取消全部”,要获得 group 必须显式启用 return_exceptions=True;trio 则在 StrictFork 或 nursery.start 出错时直接抛 group。
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
立即学习“Python免费学习笔记(深入)”;
-
asyncio.gather(task1(), task2(), return_exceptions=True):任一任务抛异常,结果列表中对应位置是异常对象;若多个失败,返回的仍是普通 list,不会自动变成 ExceptionGroup - 真正生成
ExceptionGroup的是asyncio.wait_for+gather组合失败,或使用asyncio.TaskGroup(Python 3.11+) -
asyncio.TaskGroup是推荐方式:它内部自动聚合异常,with TaskGroup() as tg:块退出时若多个任务失败,直接 raiseExceptionGroup
别忽略 exceptions 属性和 subgroup() 方法
ExceptionGroup 实例有 .exceptions 属性(tuple of exceptions),但直接遍历它只是拿到原始异常,丢失上下文;更安全的做法是用 .subgroup() 筛选并保留 group 结构。
eg = ExceptionGroup("demo", [ValueError("bad"), TypeError("wrong"), ValueError("oops")])
only_value_errors = eg.subgroup(ValueError) # 返回新的 ExceptionGroup,不是 list
if only_value_errors is not None:
print(len(only_value_errors.exceptions)) # 2
-
.subgroup()返回ExceptionGroup或None,比手动过滤 + 构造更可靠 -
.derive()用于派生新 group(例如添加额外上下文),但实际项目中极少需要 - 不要对
eg.exceptions做isinstance(e, ...)循环判断——这绕过了except*的语义,也丢失了嵌套 group 的层级信息
真正麻烦的不是怎么创建 ExceptionGroup,而是意识到它改变了异常流控的基本契约:异常不再是一条线性路径,而是一棵树。漏写一个 except* 分支,或者误用普通 except,都会让部分错误静默或中断整个流程。多看 traceback 里有没有 “ExceptionGroup: … with 2 exceptions” 这样的提示,那是 Python 在提醒你该换语法了。

















