asyncio.gather默认不传播ExceptionGroup，遇多异常仅抛第一个；需设return_exceptions=True后手动提取异常并用ExceptionGroup构造。
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;">exceptions = [r for r in results if isinstance(r, BaseException)]
if exceptions:
raise ExceptionGroup("concurrent tasks failed", exceptions)asyncio.run(main())
注意：ExceptionGroup 在 Python 3.11+ 是内置的，但如果你用的是 3.11.0–3.11.2，某些发行版可能未完全暴露；稳妥起见可加 try/except ImportError 回退到第三方包。
立即学习“Python免费学习笔记（深入）”；
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
为什么不用 asyncio.TaskGroup 替代 gather？
因为 asyncio.TaskGroup 原生支持 ExceptionGroup，且语义更清晰：
-
TaskGroup是专为并发任务 + 异常聚合设计的，gather更偏向“快捷合并返回值” - 当多个任务失败时，
TaskGroup会自动 raiseExceptionGroup，无需手动判断 - 但
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，也会漏掉异常分支。
