📌 摘要：本文通过一个真实的上线案例，详细讲解FastAPI与JavaScript实现WebSocket长连接保持的心跳机制。你会了解为什么连接会断、心跳原理是什么、前后端代码怎么写，以及那些文档里没写的调优陷阱。照着做，让你的实时通信稳如老狗。
你是不是也遇到过——WebSocket连接动不动就断开，尤其是在移动端，用户切换个Wi-Fi或者电梯里信号晃一下，消息就收不到了？📱 用户投诉说“APP消息延迟”，你一查日志，满屏都是WebSocket disconnected，然后疯狂重连，服务器压力山大，用户体验稀碎。
有些项目图省事，觉得WebSocket连上就行了，结果线上跑了半天，运维小哥就发来报警：连接数忽高忽低，很多连接存活不到2分钟。查日志，好家伙，Nginx默认proxy_read_timeout 60秒，加上移动网络运营商会掐掉长时间无流量的连接，双向夹击，连接全断了。😭
核心结论：WebSocket长连接保持，不能靠“连上就不管”，必须引入心跳机制——就像两个人打电话，每隔一会儿问一句“喂，还在吗？”。今天我就把FastAPI后端 + JavaScript前端的完整心跳实现，掰开了揉碎了讲给你听，顺便把我踩过的坑标红。
🚦 本文路线图
🔹 为什么WebSocket会断？—— 中间件超时、网络状态变化
🔹 心跳原理：ping-pong 还是 pong-ping？
🔹 FastAPI后端：接收心跳消息 + 超时管理
🔹 JavaScript前端：定时发送心跳 + 断线重连
🔹 完整可运行代码示例
🔹 那些年我踩过的坑（间隔设置、重复定时器、服务端主动断开）
🧠 第一部分：连接为什么会断？
把WebSocket想象成一条水管，数据就是水。如果水管一直流水，它就不会堵。但要是你半天不放水，中间的路由器、防火墙就觉得“嘿，这管子是不是废弃了？”——咔嚓一刀给你掐了。尤其是在移动网络下，运营商的NAT网关空闲超时可能只有30秒到几分钟。还有我们常用的Nginx，默认proxy_read_timeout是60秒，一旦60秒内没有数据从后端发到客户端，Nginx就会自作主张断开连接。
所以，要想让连接长存，唯一的方法就是定期发送一些“无用”的数据，告诉中间件：“我还活着，别砍我！”——这就是心跳。
💓 第二部分：心跳机制的两种姿势
心跳本质是一种ping/pong模式。WebSocket协议本身有控制帧Ping和Pong，但浏览器原生JS的WebSocket API并没有直接暴露发送Ping帧的方法，所以我们一般用普通消息模拟：
✨ 方案A：客户端定时发送ping消息，服务器收到后立即回复pong。
✨ 方案B：服务器定时发送ping，客户端回复pong。但同样，客户端需要能解析并回复。
更常见的做法是客户端主动发心跳，服务器只需响应或记录。为啥？因为客户端更能感知网络变化，且断开后能立即重连。下面我就以客户端发心跳为例，上代码。
⚙️ 第三部分：FastAPI后端实战
先搭一个最简单的FastAPI WebSocket端点。这里我用了/ws路径，接收心跳消息（约定JSON格式{"type": "ping"}），并回复{"type": "pong"}。同时，为了及时清理死连接，我会记录每个连接的最后心跳时间，启动一个后台任务检查超时（比如60秒没收到心跳就主动close）。
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
import asyncio
import json
from datetime import datetime, timedeltaapp = FastAPI()class ConnectionManager:def __init__(self):self.active_connections: dict[WebSocket, datetime] = {}self._heartbeat_check_interval = 30 # 每30秒检查一次asyncio.create_task(self.heartbeat_checker())async def connect(self, websocket: WebSocket):await websocket.accept()self.active_connections[websocket] = datetime.utcnow()print(f"新连接加入，当前连接数：{len(self.active_connections)}")def disconnect(self, websocket: WebSocket):if websocket in self.active_connections:del self.active_connections[websocket]print(f"连接断开，当前连接数：{len(self.active_connections)}")async def handle_messages(self, websocket: WebSocket):try:while True:data = await websocket.receive_text()try:msg = json.loads(data)except:continue# 如果是心跳ping，更新最后心跳时间并回复pongif msg.get("type") == "ping":self.active_connections[websocket] = datetime.utcnow()await websocket.send_text(json.dumps({"type": "pong"}))else:# 其他业务消息，按需处理await websocket.send_text(json.dumps({"type": "echo", "data": msg}))except WebSocketDisconnect:self.disconnect(websocket)async def heartbeat_checker(self):while True:await asyncio.sleep(self._heartbeat_check_interval)now = datetime.utcnow()timeout = timedelta(seconds=70) # 超过70秒没心跳就断开dead_conns = []for ws, last_ping in self.active_connections.items():if now - last_ping > timeout:dead_conns.append(ws)for ws in dead_conns:try:await ws.close(code=1000, reason="heartbeat timeout")except:passself.disconnect(ws)manager = ConnectionManager()@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):await manager.connect(websocket)await manager.handle_messages(websocket)🔔 重点说明： - handle_messages里只处理心跳，其他业务消息可以自定义。 - 后台心跳检查线程每30秒跑一次，如果某连接超过70秒没收到心跳，就主动关闭。这个70秒一定要大于客户端的心跳间隔（比如客户端30秒发一次，那70秒大概漏掉2次都没回复才断，防止网络抖动误杀）。 - 注意WebSocketDisconnect的捕获，及时清理字典，避免内存泄漏。
💻 第四部分：JavaScript前端实现
前端主要做三件事：建立连接、定时发心跳、监听断开自动重连。我习惯把WebSocket封装成一个类，方便复用。直接上代码：
class WebSocketClient {constructor(url) {this.url = url;this.ws = null;this.heartbeatInterval = 30000; // 30秒一次心跳this.reconnectInterval = 3000; // 断线后3秒重连this.heartbeatTimer = null;this.reconnectTimer = null;this.connect();}connect() {this.ws = new WebSocket(this.url);this.ws.onopen = () => {console.log('WebSocket 已连接');// 连接成功后，启动心跳this.startHeartbeat();// 如果之前有重连定时器，清掉if (this.reconnectTimer) {clearTimeout(this.reconnectTimer);this.reconnectTimer = null;}};this.ws.onmessage = (event) => {const data = JSON.parse(event.data);if (data.type === 'pong') {console.log('收到心跳pong，连接正常');// 可以在这里更新UI显示最后心跳时间，但不必须} else {// 处理其他业务消息console.log('业务消息', data);}};this.ws.onclose = (e) => {console.log('WebSocket 关闭', e.reason);// 停止心跳this.stopHeartbeat();// 尝试重连this.reconnect();};this.ws.onerror = (err) => {console.error('WebSocket 错误', err);this.ws.close();};}startHeartbeat() {this.heartbeatTimer = setInterval(() => {if (this.ws && this.ws.readyState === WebSocket.OPEN) {this.ws.send(JSON.stringify({ type: 'ping' }));console.log('发送心跳ping');} else {console.warn('连接未开启，停止发送心跳');this.stopHeartbeat();}}, this.heartbeatInterval);}stopHeartbeat() {if (this.heartbeatTimer) {clearInterval(this.heartbeatTimer);this.heartbeatTimer = null;}}reconnect() {this.stopHeartbeat();if (!this.reconnectTimer) {this.reconnectTimer = setTimeout(() => {console.log('尝试重连...');this.connect();}, this.reconnectInterval);}}// 主动关闭连接（比如页面卸载时）close() {this.stopHeartbeat();if (this.ws) {this.ws.close();}}
}// 使用示例
const client = new WebSocketClient('ws://你的域名/ws');
// 页面关闭前主动清理
window.addEventListener('beforeunload', () => client.close());⚠️ 关键细节： - 心跳间隔不要超过Nginx的proxy_read_timeout，一般设30秒比较安全。 - 断线重连要防抖：通过reconnectTimer避免重复重连。 - 页面关闭时一定要close连接，否则服务端可能保留孤儿连接直到超时。
🧪 第五部分：跑起来看看效果
启动FastAPI（uvicorn main:app --reload），打开浏览器控制台，你会看到每隔30秒发送一次ping，服务器立即回复pong。即使你断开Wi-Fi再打开，客户端也会自动重连，并且重连后心跳继续。🎯
💣 第六部分：那些年我踩过的坑（必看）
坑1：心跳间隔太短，服务器压力大 —— 1秒一次纯属自残，30秒一次足够，既保活又省资源。
坑2：服务端没做超时主动断开 —— 客户端突然掉线（比如用户强制杀进程），服务端不知道，连接一直占着内存。所以后台心跳检查一定要有，超时就close。
坑3：重连时忘记清理旧定时器 —— 每次重连都新建一个setInterval，导致多个心跳线程并发，消息爆炸。解决方案：重连前先stopHeartbeat()。
坑4：前后端心跳格式约定不一致 —— 我用的是{"type":"ping"}，如果你后端用字段heartbeat，一定记得对齐，否则服务器不认，相当于没心跳。
坑5：没考虑SSL/加密连接 —— 生产环境用wss://，证书配置要正确，否则连接直接被拒绝。
另外，如果你想更优雅一点，可以结合asyncio.timeout或者websocket.receive()的超时参数，不过我觉得上面这种“记录最后心跳+后台检查”的模式最清晰。
📌 最后啰嗦一句
心跳机制不是银弹，但它确实是WebSocket长连接保持最简单有效的办法。结合断线重连，能让你的实时应用在恶劣网络环境下依然坚挺。如果你在生产环境还有更高要求，比如集群下的连接状态同步、心跳与业务消息优先级，欢迎留言交流。
老朋友提醒 👋
这篇文章里的代码我都是用血泪教训换来的，现在直接抄就能跑。但你的业务场景可能不一样，比如心跳间隔是否需要动态调整？服务端要不要主动ping？欢迎在评论区分享你的“奇葩”踩坑经历，或者收藏起来，下次上线前翻出来看一眼，也许能帮你省下一个通宵。
如果你觉得有用，点赞或分享给团队，下次遇到WebSocket断连问题，咱们就不再慌了。😎