启用 return_exceptions=True 可让 asyncio.gather 保留所有异常，作为结果列表中对应位置的 Exception 实例；需用 isinstance(r, Exception) 显式判断并处理，而非外层 try/except。

asyncio.gather 默认只抛第一个异常，怎么让所有异常都保留？

默认情况下，asyncio.gather 遇到任意一个协程抛异常，会立刻取消其余任务，并只把第一个异常重新抛出——这在需要批量处理、统一分析错误时非常不利。

解决办法是启用 return_exceptions=True 参数。此时异常不会被抛出，而是作为对应位置的返回值，类型为 Exception 实例（比如 ValueError、TimeoutError），和正常返回值一样保留在结果列表中。

• 必须显式传入 return_exceptions=True，没有默认开启
• 返回结果顺序严格对应传入协程的顺序，即使某些协程已失败
• 即使所有任务都失败，结果列表长度仍等于输入协程数量

如何区分成功结果和捕获的异常？

开启 return_exceptions=True 后，结果混杂了正常值和异常对象，需要用 isinstance(..., Exception) 判断：

import asyncio
async def good(): return "ok"
async def bad1(): raise ValueError("first fail")
async def bad2(): raise TypeError("second fail")
results = await asyncio.gather(
good(), bad1(), bad2(),
return_exceptions=True
)
for i, r in enumerate(results):
if isinstance(r, Exception):
print(f"Task {i} failed: {type(r).name}: {r}")
else:
print(f"Task {i} succeeded: {r}")

注意不要用 except Exception 去包 gather 调用——那又回到只抓第一个异常的老路；也不要用 try/except 包单个协程再返回 None，那样会丢失异常类型和 traceback。

和 asyncio.wait 对比：什么场景该选 gather + return_exceptions？

asyncio.wait 也能等全部完成并拿到 done 集合，但它返回的是 Task 对象，需手动调用 task.exception() 或 task.result()，代码更啰嗦，且不保证顺序。

• 要保持输入顺序 + 统一结构化结果 → 用 gather(..., return_exceptions=True)
• 需要精细控制取消逻辑（比如超时后只取消部分任务）→ 用 wait 或 create_task + 手动管理
• 任务数量极大（数千以上）且对内存敏感 → gather 会一次性 hold 所有结果，可能触发 GC 压力；考虑分批或流式处理

常见误用：return_exceptions=True 后还 try/except gather 调用

这是典型误区：开了 return_exceptions=True 却还在外层包 try/except，以为能捕获“所有异常”，其实这时 gather 根本不会抛异常，except 永远进不去。

正确做法是信任返回值，直接遍历判断：

# ❌ 错误：加了 return_exceptions=True 还 try/except
try:
    results = await asyncio.gather(a(), b(), return_exceptions=True)
except Exception as e:
    # 这里永远不会执行
    pass
✅ 正确：直接检查每个元素
results = await asyncio.gather(a(), b(), return_exceptions=True)
for r in results:
if isinstance(r, Exception):
handle_error(r)
else:
process_result(r)

最容易被忽略的一点：异常对象本身携带完整 traceback（只要没被提前丢弃），所以别急着 str(r) ——用 traceback.format_exception 可以还原原始报错上下文。

https://www.php.cn/faq/2023883.html