应显式捕获 starlette.exceptions.ClientDisconnect 异常，而非 Exception 或 asyncio.CancelledError；它由 ASGI 服务器在客户端断连时主动抛出，用于及时终止流式响应并释放资源。
FastAPI/Starlette 中如何识别 client disconnected 异常
在 FastAPI 或底层 Starlette 中，客户端提前关闭连接（比如用户刷新页面、网络中断、移动端切后台）会触发 ClientDisconnect 异常。它不会自动抛出，必须显式捕获——否则请求会静默失败或卡住，日志里也看不到明确线索。
常见错误现象：RuntimeError: Response closed 或 ConnectionResetError 出现在流式响应（如 StreamingResponse）中；或者异步任务持续运行却没人接收结果。
-
ClientDisconnect是 Starlette 定义的异常，位于starlette.exceptions，FastAPI 兼容它 - 只在请求体已接收完成、但响应尚未写完时断开才触发该异常（例如正在
yield数据） - 不能靠
try/except Exception捕获，必须明确写except ClientDisconnect
from starlette.exceptions import ClientDisconnect
from fastapi import FastAPI
<p>app = FastAPI()</p><p>@app.get("/stream")
async def stream_data():
try:
for i in range(10):
yield f"data: {i}\n\n"
await asyncio.sleep(1)
except ClientDisconnect:
print("客户端已断开，停止推送")
return # 提前退出生成器
为什么 asyncio.CancelledError 不是可靠判断依据
有人尝试用 CancelledError 捕获断连，这是错的。它只在任务被显式 cancel() 时抛出，而客户端断开由 ASGI 服务器（如 Uvicorn）以 ClientDisconnect 通知应用层，两者机制不同。
立即学习“Python免费学习笔记（深入）”；
Uvicorn 在检测到 socket 关闭后，会调用 scope["client"] 对应的 disconnect 逻辑，并让当前任务收到 ClientDisconnect；CancelledError 多半来自超时或手动取消，和网络断开无直接关系。
- 依赖
CancelledError会导致漏掉真实断连场景 - 某些旧版 Uvicorn（ClientDisconnect，建议升级到最新稳定版
- 若用
asyncio.wait_for包裹流式逻辑，需注意：超时引发的TimeoutError和断连无关，别混为一谈
在中间件中统一处理断连是否可行
不可行。ASGI 中间件无法拦截已开始的响应流中的断连事件——因为 ClientDisconnect 发生在 await send(...) 调用时，而中间件只包裹 receive 和 send 的初始调用点，不介入后续多次 send。
也就是说，你可以在路由函数、依赖、或自定义 StreamingResponse 的 iterator 内部捕获，但没法在中间件里“全局兜底”。强行在中间件里 try/catch 不起作用。
- 想做统一日志？只能在每个流式端点里加
except ClientDisconnect块 - 想自动清理资源（如关闭数据库游标、取消后台任务）？必须在捕获后手动处理，框架不帮你做
- 如果用了
BackgroundTasks，记得在ClientDisconnect后调用task.cancel()，否则任务可能继续跑
使用 httpx.AsyncClient 请求时如何模拟断连测试
本地调试时很难手动“快速断开”，用 httpx.AsyncClient 配合 timeout 和 aclose() 可复现：
import httpx
import asyncio
<p>async def test_disconnect():
async with httpx.AsyncClient() as client:
resp = await client.get("<a href="https://www.php.cn/link/4c9aab06f63ad6870758bb31de6ecec1">https://www.php.cn/link/4c9aab06f63ad6870758bb31de6ecec1</a>", timeout=2)</p><h1>立即关闭连接，触发服务端 ClientDisconnect</h1><pre class="brush:php;toolbar:false;"> await client.aclose()
# 此时服务端正在 yield，会收到异常
更贴近真实场景的做法是用 curl + Ctrl+C：启动流式接口后，在终端执行 curl https://www.php.cn/link/4c9aab06f63ad6870758bb31de6ecec1，几秒后按 Ctrl+C，服务端日志就能看到 ClientDisconnect 被捕获。
注意：浏览器开发者工具里“Cancel”请求，不一定触发 ClientDisconnect（取决于浏览器实现和 HTTP/2 支持），curl 最可靠。
真正难的是区分“用户主动放弃”和“网络抖动重试”——ClientDisconnect 本身不带上下文，你需要结合请求 ID、客户端 UA、重试头（如 Retry-After）自己判断。这点容易被忽略，但线上排查时很关键。
