FastAPI原生支持WebSocket,无需额外配置,关键在正确使用@app.websocket()装饰器、显式调用await websocket.accept()、手动实现心跳及协程安全的连接管理。

直接上结论:FastAPI 本身不需额外配置就能跑 WebSocket,关键在路由声明、连接生命周期管理、以及避免常见异步陷阱。它依赖 Starlette 的 WebSocket 类和 ASGI 协议支持,不是插件也不是扩展——只要用对 API,连接就通了。
怎么写一个最简可用的 WebSocket 路由
核心是用 @app.websocket() 装饰器,参数必须是 websocket: WebSocket,且函数体必须是 async def。不能用 def,否则会报 RuntimeError: Expected coroutine function。
必须显式调用 await websocket.accept() 才算握手成功;漏掉这句,前端 new WebSocket() 会卡在 connecting 状态,控制台显示 Failed to connect。
- 接收文本消息用
await websocket.receive_text(),二进制用await websocket.receive_bytes() - 发送文本用
await websocket.send_text(),二进制用await websocket.send_bytes() - 关闭连接推荐用
await websocket.close(code=1000),避免直接抛异常导致连接残留
为什么 WebSocket 连接会莫名其妙断开
绝大多数“自动断开”不是代码 bug,而是网络中间件(如 Nginx、Cloudflare)或客户端浏览器主动踢掉空闲连接。默认情况下,WebSocket 没有心跳,TCP 层的 keepalive 通常不生效,中间代理会在 60–300 秒后静默关闭连接。
解决办法是手动加心跳:服务端定期发 ping(用 await websocket.ping()),客户端收到后回 pong;或者双方约定业务层心跳包(比如每 25 秒发一次 {"type": "ping"})。别只在服务端发,不处理客户端的响应,否则无法判断对方是否还活着。
- Nginx 需要显式配置
proxy_read_timeout 300;和proxy_set_header Upgrade $http_upgrade;等头字段 - 浏览器 tab 切到后台时,
setInterval可能被节流,心跳间隔拉长,容易触发超时 - FastAPI 的
WebSocket实例不是线程安全的,不能跨任务共享(比如在后台任务里直接调用send_text)
怎么让多个客户端之间广播消息
FastAPI 没内置连接池,得自己管。最常用的是维护一个全局 set 或 list 存活的 WebSocket 实例,但要注意:这个集合必须是线程/协程安全的,且每个连接断开时必须及时清理,否则内存泄漏+消息发错人。
推荐用 asyncio.Lock 包裹增删操作,或改用 weakref.WeakSet 自动回收已关闭的连接对象。别用普通 dict 存连接并靠 id(websocket) 当 key——WebSocket 对象销毁后 id 可能复用,导致误判。
- 广播前先检查
websocket.client_state == WebSocketState.CONNECTED,跳过已断开的连接 - 发送失败(如
ConnectionClosedOK异常)时,必须从集合中移除该连接 - 多进程部署时,这个集合只在单个 worker 内有效;跨进程广播需引入 Redis Pub/Sub 或消息队列
真正麻烦的从来不是“怎么连上”,而是“连上之后怎么不丢、不乱、不崩”。连接数一上去,异常分支、并发写入、进程隔离这些点,比写第一个 send_text 花的时间多十倍。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!











