Python3.11+ExceptionGroup捕获方法

Python 3.11 引入的 ExceptionGroup 本意是统一处理并发异常，但 asyncio.gather 在默认行为下却“背叛”了这一设计——它遇到多个协程同时失败时只抛出第一个异常，其余异常被悄然吞没；要真正捕获全部异常，必须显式启用 return_exceptions=True，再手动筛选异常项并用 ExceptionGroup 重新封装，这一看似反直觉的机制背后，是 gather 对底层 TaskGroup 异常聚合逻辑的意外绕过，掌握它，才能让异步错误处理既健壮又符合现代 Python 的异常语义。

asyncio.gather 默认不传播 ExceptionGroup

Python 3.11 引入 ExceptionGroup，但 asyncio.gather 在默认模式（return_exceptions=False）下遇到多个协程同时抛出异常时，**不会打包成 ExceptionGroup**，而是直接 raise 第一个异常，其余被静默丢弃。这和你预期的“收集所有异常”相悖。

根本原因：底层 gather 使用 asyncio.TaskGroup（它确实支持 ExceptionGroup），但 gather 自己做了异常处理封装，绕过了原生聚合逻辑。

• 想拿到全部异常 → 必须显式启用 return_exceptions=True
• 启用后，结果列表里混着成功值和 Exception 实例，需手动过滤、分组
• ExceptionGroup 不会自动出现，得你自己用 ExceptionGroup("msg", exceptions) 构造

正确捕获并构造 ExceptionGroup 的写法

先让 gather 不中断、返回所有结果（含异常），再从中提取异常并重包：

import asyncio
from exceptiongroup import ExceptionGroup  # Python <3.12 需 pip install exceptiongroup
<p>async def fails_fast():
await asyncio.sleep(0.1)
raise ValueError("fast failed")</p><p>async def fails_slow():
await asyncio.sleep(0.2)
raise TypeError("slow failed")</p><p>async def main():
results = await asyncio.gather(
fails_fast(),
fails_slow(),
return_exceptions=True  # ← 关键！必须设为 True
)</p><pre class="brush:php;toolbar:false"><code>exceptions = [r for r in results if isinstance(r, BaseException)]
if exceptions:
    raise ExceptionGroup("concurrent tasks failed", exceptions)</code>

asyncio.run(main())

注意：ExceptionGroup 在 Python 3.11+ 是内置的，但如果你用的是 3.11.0–3.11.2，某些发行版可能未完全暴露；稳妥起见可加 try/except ImportError 回退到第三方包。

为什么不用 asyncio.TaskGroup 替代 gather？

因为 asyncio.TaskGroup 原生支持 ExceptionGroup，且语义更清晰：

• TaskGroup 是专为并发任务 + 异常聚合设计的，gather 更偏向“快捷合并返回值”
• 当多个任务失败时，TaskGroup 会自动 raise ExceptionGroup，无需手动判断
• 但 TaskGroup 要求所有任务在 with 块内创建，不能像 gather 那样传一堆已定义好的协程对象

等价写法：

async def main_with_taskgroup():
    async with asyncio.TaskGroup() as tg:
        tg.create_task(fails_fast())
        tg.create_task(fails_slow())
    # 如果任一 task 失败，这里直接 raise ExceptionGroup

如果你控制得了任务创建时机，优先选 TaskGroup；如果必须用已有协程对象（比如从配置或函数返回），就只能走 gather(..., return_exceptions=True) + 手动聚合这条路。

容易忽略的兼容性细节

ExceptionGroup 的嵌套行为和匹配逻辑跟普通异常不同，尤其影响 except 捕获：

• except ValueError: 不会捕获 ValueError 包在 ExceptionGroup 里的场景 —— 得用 except* ValueError:（注意星号）
• except* 是 Python 3.11 新语法，旧版本直接报错；若需兼容，只能降级为遍历 exceptions 属性手动检查
• ExceptionGroup.exceptions 是只读 tuple，修改它不会影响原 group；要提取子异常，得用 except* 或 BaseExceptionGroup.subgroup()

真正棘手的地方不在怎么抛，而在下游怎么接 —— 如果你的错误处理逻辑没适配 except*，那即使上游构造了 ExceptionGroup，也会漏掉异常分支。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~