本文通过一个真实的上线案例，详细讲解FastAPI与JavaScript实现WebSocket长连接保持的心跳机制。你会了解为什么连接会断、心跳原理是什么、前后端代码怎么写，以及那些文档里没写的调优陷阱。照着做，让你的实时通信稳如老狗。

你是不是也遇到过——WebSocket连接动不动就断开，尤其是在移动端，用户切换个Wi-Fi或者电梯里信号晃一下，消息就收不到了？用户投诉说“APP消息延迟”，你一查日志，满屏都是

，然后疯狂重连，服务器压力山大，用户体验稀碎。

有些项目图省事，觉得WebSocket连上就行了，结果线上跑了半天，运维小哥就发来报警：连接数忽高忽低，很多连接存活不到2分钟。查日志，好家伙，Nginx默认

 60秒，加上移动网络运营商会掐掉长时间无流量的连接，双向夹击，连接全断了。

核心结论：WebSocket长连接保持，不能靠“连上就不管”，必须引入心跳机制——就像两个人打电话，每隔一会儿问一句“喂，还在吗？”。今天我就把FastAPI后端 + JavaScript前端的完整心跳实现，掰开了揉碎了讲给你听，顺便把我踩过的坑标红。

*   为什么WebSocket会断？—— 中间件超时、网络状态变化

*   心跳原理：ping-pong 还是 pong-ping？

*   FastAPI后端：接收心跳消息 + 超时管理

*   JavaScript前端：定时发送心跳 + 断线重连

*   那些年我踩过的坑（间隔设置、重复定时器、服务端主动断开）

## 🧠 第一部分：连接为什么会断？

把WebSocket想象成一条水管，数据就是水。如果水管一直流水，它就不会堵。但要是你半天不放水，中间的路由器、防火墙就觉得“嘿，这管子是不是废弃了？”——咔嚓一刀给你掐了。尤其是在移动网络下，运营商的NAT网关空闲超时可能只有30秒到几分钟。还有我们常用的Nginx，默认

是60秒，一旦60秒内没有数据从后端发到客户端，Nginx就会自作主张断开连接。

所以，要想让连接长存，唯一的方法就是定期发送一些“无用”的数据，告诉中间件：“我还活着，别砍我！”——这就是心跳。

## 💓 第二部分：心跳机制的两种姿势

模式。WebSocket协议本身有控制帧

，但浏览器原生JS的WebSocket API并没有直接暴露发送Ping帧的方法，所以我们一般用普通消息模拟：

。但同样，客户端需要能解析并回复。

更常见的做法是客户端主动发心跳，服务器只需响应或记录。为啥？因为客户端更能感知网络变化，且断开后能立即重连。下面我就以客户端发心跳为例，上代码。

## ⚙️ 第三部分：FastAPI后端实战

先搭一个最简单的FastAPI WebSocket端点。这里我用了

路径，接收心跳消息（约定JSON格式

。同时，为了及时清理死连接，我会记录每个连接的最后心跳时间，启动一个后台任务检查超时（比如60秒没收到心跳就主动close）。

from fastapi import FastAPI, WebSocket, WebSocketDisconnect

        self.active_connections: dict[WebSocket, datetime] = {}

        self._heartbeat_check_interval = 30   # 每30秒检查一次

        asyncio.create_task(self.heartbeat_checker())

    async def connect(self, websocket: WebSocket):

        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):

                data = await websocket.receive_text()

                    msg = json.loads(data)

                # 如果是心跳ping，更新最后心跳时间并回复pong

                if msg.get("type") == "ping":

                    self.active_connections[websocket] = datetime.utcnow()

                    await websocket.send_text(json.dumps({"type": "pong"}))

                    # 其他业务消息，按需处理

                    await websocket.send_text(json.dumps({"type": "echo", "data": msg}))

            await asyncio.sleep(self._heartbeat_check_interval)

            timeout = timedelta(seconds=70)  # 超过70秒没心跳就断开

            for ws, last_ping in self.active_connections.items():

                if now - last_ping > timeout:

                    dead_conns.append(ws)

                    await ws.close(code=1000, reason="heartbeat timeout")

async def websocket_endpoint(websocket: WebSocket):

    await manager.handle_messages(websocket)

## 💻 第四部分：JavaScript前端实现

前端主要做三件事：建立连接、定时发心跳、监听断开自动重连。我习惯把WebSocket封装成一个类，方便复用。直接上代码：

        this.heartbeatInterval = 30000; // 30秒一次心跳

        this.reconnectInterval = 3000;   // 断线后3秒重连

            console.log('WebSocket 已连接');

            // 连接成功后，启动心跳

            // 如果之前有重连定时器，清掉

FastAPI实战：WebSocket长连接保持与心跳机制，从入门到填坑

数据库

FastAPI与JavaScript实现WebSocket长连接心跳机制详解，解决移动端连接频繁断开问题。包含前后端完整代码示例，30秒心跳间隔优化方案，以及超时管理、断线重连等实战技巧。避免Nginx超时、运营商掐线导致连接中断，确保实时通信稳定可靠。

中间件

服务器

路由器

防火墙

路由

JSON

4核4G3M云服务器 新用户低至38元/年！

2026新春采购季

message-queue-catalog

domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

FastAPI实战：WebSocket长连接保持与心跳机制，从入门到填坑

FastAPI实战：WebSocket长连接保持与心跳机制，从入门到填坑

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐