BackgroundTasks 在 FastAPI 的 WebSocket 路由中完全失效，因其依赖 HTTP 请求结束的生命周期节点，而 WebSocket 是无响应体的长连接，缺乏触发上下文；必须改用 asyncio.create_task() 启动独立协程，并手动处理异常、复用客户端及连接状态校验。
BackgroundTasks 在 FastAPI 的 WebSocket 路由里完全不生效——这不是配置问题，是设计使然。WebSocket 连接没有“请求结束”这个生命周期节点，BackgroundTasks 依赖的 Request 上下文根本不存在，调用 add_task() 后函数静默不执行，连日志都不会打。
为什么 BackgroundTasks 在 @app.websocket 中失效
FastAPI 的 BackgroundTasks 是为 HTTP 请求流设计的：它在响应已生成、但连接尚未关闭的瞬间触发任务。而 WebSocket 是长连接，websocket.accept() 之后连接持续存在，整个过程不返回 HTTP 响应体，BackgroundTasks 的触发机制彻底失联。
你写的异步函数（比如调用外部 API 或订阅 Redis）如果只是塞进 background_tasks.add_task(...)，它永远不会运行。
- 不是语法错，不是漏 await，是根本没注册进事件循环
-
WebSocketDisconnect异常捕获再完善也救不了它——任务压根没启动 - 本地测试可能“看似有效”，那通常是协程被意外 await 了（比如误写成
await func()），但这会阻塞主连接循环，导致消息收发卡顿
必须用 asyncio.create_task() 启动真正后台协程
这是唯一可靠的方式：把协程直接提交到当前事件循环，和 WebSocket 主循环并行跑，互不阻塞。
立即学习“Python免费学习笔记（深入）”；
关键点：
- 必须显式
await websocket.accept()后再创建任务，否则连接未建立就发消息会报错 - 任务内部要自己处理异常，否则崩溃后无声退出（建议包
try/except+logging.error） - 不要在任务里反复创建新 HTTP 客户端（如
aiohttp.ClientSession()），应复用单例或通过依赖注入传入 - 如果任务需要向该 WebSocket 发送消息，得确保连接仍活跃——不能只靠
websocket.send_text()，要捕获WebSocketDisconnect并主动取消任务
示例片段：
import asyncio
from fastapi import WebSocket, WebSocketDisconnect
<p>@app.websocket("/ws/{user_id}")
async def ws_endpoint(websocket: WebSocket, user_id: str):
await websocket.accept()</p><pre class="brush:php;toolbar:false;"># 启动后台任务：监听 Redis Pub/Sub
task = asyncio.create_task(
listen_redis_and_forward(websocket, user_id)
)
try:
while True:
data = await websocket.receive_text()
# 处理客户端发来的指令
await handle_user_message(data, user_id)
except WebSocketDisconnect:
task.cancel() # 主动取消后台任务
try:
await task
except asyncio.CancelledError:
pass
WebSocket 连接管理中容易被忽略的边界情况
真实部署时，以下几点比“能连上”更重要：
-
websocket.receive_text()和websocket.receive_bytes()会阻塞等待，如果客户端断网但 TCP 连接未及时关闭（如 NAT 超时），服务端会一直挂起；建议加asyncio.wait_for(..., timeout=30) - 多个客户端共用一个连接管理器（如
ConnectionManager）时，send_text()抛出WebSocketDisconnect不代表连接已从集合中移除，必须在except块里手动.remove() - Uvicorn 默认单 worker，WebSocket 连接无法跨进程广播；要做群聊或广播，必须引入 Redis 或其他共享状态后端
- 前端页面刷新或网络闪断，会导致重复连接；服务端若不做
client_id去重或 session 绑定，可能产生脏数据或资源泄漏
WebSocket 的难点不在“怎么写第一个 echo”，而在连接长期存活下的资源清理、异常传播、并发安全和跨实例协调——这些细节不处理，上线后就是内存缓慢增长、任务静默丢失、消息偶尔不达。
