ClientDisconnect仅在读取请求体(如request.body())时触发,流式响应中主力异常是asyncio.CancelledError;需用asynccontextmanager包裹生成器统一捕获,并通过ASGI中间件存trace_id实现断连可观测。

ClientDisconnect异常在Uvicorn中如何被捕获
Uvicorn本身不主动抛出ClientDisconnect,它只按ASGI协议把连接中断事件转为disconnect消息,交由应用层处理。FastAPI等框架才封装了ClientDisconnect异常——但这个异常**只在请求体读取过程中触发**,比如你用await request.body()或await request.json()时客户端突然断开,才会raise出来。如果只是响应已发出一半、用户关掉浏览器,Uvicorn底层会静默关闭socket,不会通知你的路由函数。
- 常见错误现象:你在
try/except ClientDisconnect里写日志,但压根没打印出来——大概率是因为你没在真正读请求体的地方触发它 - 正确捕获点:仅限于
request.body()、request.form()、request.stream()这类阻塞式IO调用 - 流式响应(如SSE、AI流)场景下,
ClientDisconnect几乎不会被抛出;此时实际抛的是asyncio.CancelledError或ConnectionResetError
asyncio.CancelledError才是流式接口断连的主力异常
当用户关闭页面或网络中断,Uvicorn的底层连接会被取消,当前协程收到asyncio.CancelledError。这个异常比ClientDisconnect更底层、更普遍,尤其在yield或await asyncio.sleep()期间最容易暴露。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
- 不要只捕获
ClientDisconnect,必须同时处理asyncio.CancelledError - 在流式生成器外层加
asynccontextmanager是最稳妥的做法,统一收口所有退出路径 -
uvicorn --log-level debug能让你在uvicorn.error日志里看到Connection lost before response completed这类提示,是断连的间接证据
为什么try/except不总管用
不是代码写错了,而是异常发生的位置超出了你的try块范围。比如你在@app.get("/stream")函数里写了try,但实际断连发生在FastAPI内部的response.streaming_response发送逻辑中——那个协程不在你的函数栈里。
- 推荐做法:把流式逻辑封装进独立的异步生成器,再用
asynccontextmanager包裹整个生成器 - 避免在
return StreamingResponse(...)之后写清理逻辑,它不会执行 - 若需记录断连,应在
send()调用后立即检查scope["client"]是否还有效,或依赖receive()返回{"type": "disconnect"}事件
生产环境断连日志怎么加trace_id
Uvicorn默认不透传trace_id到断连钩子,因为disconnect事件不携带原始请求头。想让断连日志带上下文,得在请求刚进来时就把trace_id存进scope,并在disconnect事件到来时取出。
- 在中间件里提取
trace_id(如从X-Trace-IDheader),存入scope["trace_id"] - 自定义ASGI app包装器,在
receive协程中监听{"type": "disconnect"},并用scope.get("trace_id")打日志 - 别依赖
logging.LoggerAdapter或contextvars,它们在disconnect事件协程中可能已失效
ClientDisconnect就万事大吉,结果流式接口崩了却没日志、没指标、没人知道谁断了。

















