WebSocket实时同步在线游戏Demo：20Hz帧循环与断线重连

简介：这是一份面向WebSocket实时通信与在线游戏开发入门者的实战Demo，聚焦客户端与服务器之间的全双工通信、玩家状态同步、服务器主动推送等核心场景，适合已了解JavaScript基础、希望打通实时对战项目链路的开发者对照学习。压缩包共488个文件、约2.96MB，以391个JavaScript脚本为主体，配合少量Go服务端源码、HTML页面、图标与图片素材及说明文档，基本覆盖前端交互、后端会话管理和静态资源组织等环节。已有94人学习，说明其在同类实时通信示例中具备一定参考价值。读者可从中梳理握手连接、数据帧收发、JSON消息格式设计、断线重连与广播同步的实现思路，并借助现有页面与素材快速搭建可运行的演示环境，理解WebSocket在游戏状态同步和低延迟交互中的具体落地方式，为后续扩展房间管理、负载均衡与WSS安全传输打下基础。

1. 从一次联机延迟说起：为什么这个 Demo 用 WebSocket 而不是轮询

二十个客户端挤进同一个房间，HTTP 短轮询会让服务器每秒应付四百次没有信息量的问询，延迟还压不下去。这套基于 WebSocket 的在线游戏开发 Demo，要解决的不是“能不能连上”，而是连上之后每条消息该多久发一次、一次发多少、丢了怎么补。它面向两类人：要交一份能当场跑起来的课设或毕设的学生，以及第一次做实时同步、需要一个能改能扩的骨架的开发者。默认形态是 2D 同屏多人对战，服务端权威、20Hz 广播、断线可恢复，代码量控制在一个周末能读完的范围内。选型上我刻意绕开了 WebRTC 数据通道和裸 UDP，理由放到下一章摊开讲，因为那部分决策比代码本身更值得抄。

2. 需求与选型：四条硬指标与三种通信方案的实际取舍

做实时联机最容易犯的错，是先写代码再想指标。等到发现手感发飘、角色瞬移，回头改协议的成本比从头搭一遍还高。所以这套 Demo 的第一步不是建目录，而是把“能玩”翻译成四条能测的数字，再拿这三条数字去卡通信方案。

2.1 四条硬指标：把「能玩」翻译成可测量的数字

第一条是输入延迟。玩家按下方向键到屏幕上角色开始动，P95 控制在 150ms 以内。这个数字不是拍脑袋来的：60 帧刷新下，人的视觉对 100ms 以内的延迟基本无感，超过 200ms 就会有明显的“粘手”感。第二条是容量，单房间 20 个玩家，单机 200 个并发连接不掉线。第三条是恢复能力，客户端断网 10 秒内重连回原房间，角色位置、血量、分数都不重置。第四条是顺序性，同一玩家的移动输入必须按序处理，否则会出现“先按右再按左，结果往右走”的玄学现象。

这四条背后其实是一组相互牵制的参数：广播频率越高延迟越低，但带宽和 CPU 吃得越多；渲染缓冲越大画面越平滑，但响应越迟钝；快照发得越全，重连越好做，但每帧的序列化开销越大。后面所有设计，本质都是在这几个方向上找平衡点。

提示：做毕设或课设时，把这四条指标直接写进开题报告和验收表，答辩时逐条演示，比讲一堆架构图有说服力得多。

2.2 三种通信方案对比：为什么排除轮询和 SSE

方案	端到端延迟	服务端推送	双向	实现成本	适用判断
HTTP 短轮询	200ms 起，随频率线性上升	无，靠客户端反复问	伪双向	低	聊天室够用，游戏不行
SSE 长连接	100ms 左右	有	单向，上行还得发 HTTP	中	只适合排行榜、公告
WebSocket	与心跳周期同级	有	原生双向	中	本 Demo 选定
WebRTC 数据通道	最低	有	双向	高，需信令与 NAT 穿透	小 Demo 属于过度设计

短轮询的问题不只是延迟，更是空转：客户端在没有任何输入的时候也在发请求，服务器 99% 的响应是“没变化”。SSE 解决了推送，但上行仍然是一次次独立的 HTTP 请求，输入和快照对不上节拍，做预测和回滚会非常别扭。WebRTC 数据通道性能确实更好，但需要信令服务器、ICE 协商、STUN 配置，一个课程设计规模的项目为这点延迟收益付出这个复杂度不划算。

WebSocket 的优势在于它是一条长连接上的双向字节流，服务端可以主动按固定节拍往下推快照，客户端也可以随时往上送输入，二者共享同一个时间基准。它的门槛也够低：Node.js 上一个ws库加三十行代码就能跑通握手和广播，浏览器端零依赖。

2.3 技术栈与目录骨架：Node.js + ws + 原生 Canvas

服务端选择 Node.js 加ws，理由是事件循环模型天然适配“大量连接 + 小消息”的场景，单线程避免了多线程锁的复杂度，200 并发这个量级远没到瓶颈。客户端用原生 JavaScript 加 Canvas 2D，不引框架，目的是让读过的人能直接把渲染循环换成自己的。状态存储全部在内存里，不接数据库——Demo 关掉就清空，反而省掉了持久化带来的一致性问题。

game-demo/ ├── server/ │ ├── index.js # 启动入口：HTTP 静态服务 + WebSocket 升级 │ ├── room.js # 房间对象：帧循环、玩家集合、快照生成 │ ├── session.js # 会话令牌、断线实体保留、重连恢复 │ └── heartbeat.js # 心跳与半死连接清理 ├── shared/ │ └── protocol.js # 前后端共用的 opcode 常量与编码函数 ├── client/ │ ├── net.js # 连接、断线退避重连、消息分发 │ ├── render.js # 快照缓冲 + 插值 + Canvas 绘制 │ └── input.js # 键盘采集，按 tick 打包上行 └── tools/ └── loadtest.js # 假客户端压测脚本

shared/protocol.js被前后端同时引用是这份骨架里最值得保留的一条纪律：opcode 只在一个地方定义，改协议时不可能一边改完另一边忘掉。很多联机 Demo 的“诡异不同步”，最后查出来就是两端常量表版本对不上。

3. 总体架构设计：服务端权威与客户端表现的两层职责

联机游戏最核心的一条分界线是：谁说了算。这套 Demo 采用服务端权威模型，位置、碰撞、伤害判定全部在服务端算，客户端只负责两件事——把本地输入尽快送上去，把收到的快照平滑地画出来。客户端永远不改自己的坐标，只猜、不决定。这样做的好处是作弊空间小、状态唯一，坏处是必须处理“猜错了要拉回来”，这部分放到 4.4 节讲。

3.1 三层结构：接入层、房间层、状态层各自管什么

接入层只做三件事：握手、鉴权（发会话令牌）、把连接交给房间层。它不认识游戏逻辑，也不知道房间里有几个人。这一层薄一点，后续换成别的传输方式时代码几乎不用动。

房间层是真正的心脏。每个房间持有一个固定步长的循环，维护玩家集合，每帧推进一次模拟、生成一次快照、广播一次。房间之间完全隔离，A 房间卡住不会影响 B 房间。房间的空闲回收也在这层：最后一个人离开后启动 30 秒倒计时，没人回来就销毁并释放定时器。

状态层是一个纯数据的内存池，房间层通过它读写实体，不直接碰连接对象。这样做的直接收益是压测和单元测试可以绕过网络，直接调room.simulate()断言位置变化。我一般会把这条写进毕设的“可测试性设计”小节，评审很吃这一套。

浏览器 A ──┐ 浏览器 B ──┼─→ 接入层(index.js) ─→ 房间层(room.js × N) ─→ 状态层(entities) 浏览器 C ──┘ │ │ 心跳/令牌清理 帧循环 20Hz

3.2 消息协议设计：九个 opcode 与载荷约定

协议只定义九个 opcode，够用且不容易乱。下行消息统一带t字段表示服务端 tick，客户端拿它做乱序丢弃和插值；上行消息统一带s表示客户端输入序号，服务端拿它做去重和排序。

opcode	方向	载荷要点	说明
1 JOIN	上行	昵称、房间号	加入请求
2 JOIN_ACK	下行	token、你的实体 id、当前 tick	加入成功，token 用于重连
3 INPUT	上行	序号 s、方向 dx/dy、按键位	每 50ms 一次，可批量
4 SNAPSHOT	下行	tick、全量或增量玩家状态	每帧一次
5 PING / 6 PONG	双向	时间戳	应用层心跳，测 RTT
7 RESUME	上行	token	断线重连
8 RESUME_ACK	下行	全量快照	重连后强制对齐
9 ERROR	下行	错误码	房间满、令牌过期等

格式上选择 JSON 而不是二进制。原因很实际：一个 20 人的房间每帧快照量化后不到 600 字节，20Hz 下每人每秒 12KB，浏览器调试面板能直接看懂每条消息。用 ArrayBuffer 能省一半带宽，但调试成本翻倍，Demo 阶段不划算。真要上量，把 SNAPSHOT 一路换成二进制，其他 opcode 不动即可。

3.3 房间生命周期：创建、匹配、开局、回收

房间不是预先建好的，而是第一个人进来时按房间号懒创建。这个设计让 Demo 不需要单独的匹配服务：想开新局，换一个房间号就行。生命周期四步走——create分配 id 和定时器；join检查人数上限（20）并把实体塞进状态池；tick循环推进；destroy在最后一人离开 30 秒后清除定时器、清空 Map。

最容易漏的是第四步。定时器不清，房间对象就永远被引用着，一晚上跑下来内存曲线只涨不跌。我在destroy里固定写三行：clearInterval(this.timer)、this.players.clear()、rooms.delete(this.id)，并且用一个closed标志位挡住销毁后仍在飞的消息。

// server/room.js —— 销毁必须幂等，避免定时器重复清理 destroy() { if (this.closed) return; this.closed = true; clearInterval(this.timer); this.players.clear(); rooms.delete(this.id); }

closed标志看着冗余，实际能挡掉一类很隐蔽的崩溃：玩家在最后 100ms 内点了离开，销毁定时器和离开回调同时触发，第二次clearInterval不会报错，但后续往已清空的 Map 里写数据会抛异常。

4. 核心模块实现：20Hz 帧循环、快照广播与断线重连

设计定完，落地时有四个模块是绕不过去的：服务端怎么按稳定节拍推进、快照怎么省着发、客户端怎么把 20Hz 的数据画成 60Hz 的顺滑画面、断线之后怎么接回原来那个角色。这一章按这个顺序给代码，每一段后面说清楚参数为什么取这个值。

4.1 服务端帧循环：固定步长 + 累加器 + 追帧上限

不要用setInterval(simulate, 50)直接跑逻辑。定时器会漂移，机器一忙就堆积回调，几十个回调在同一毫秒里连着执行，物理模拟会瞬间加速。标准写法是固定步长加累加器：定时器只负责“唤醒”，逻辑用固定 dt 推进，醒来时把欠下的帧补齐。

// server/room.js —— 固定步长的帧循环 const TICK_MS = 50; // 20Hz，与客户端 100ms 渲染缓冲配套 const MAX_CATCHUP = 5; // 一次最多补 5 帧，防止卡顿后疯狂追帧 class Room { constructor(id) { this.id = id; this.players = new Map(); // sessionId -> 实体 this.tick = 0; this.acc = 0; // 未消化的时间（毫秒） this.last = process.hrtime.bigint(); // 半周期唤醒：把定时器抖动摊平，避免长期累积漂移 this.timer = setInterval(() => this.step(), TICK_MS / 2); } step() { const now = process.hrtime.bigint(); const delta = Number(now - this.last) / 1e6; // 纳秒转毫秒 this.last = now; this.acc += delta; let guard = 0; while (this.acc >= TICK_MS && guard++ < MAX_CATCHUP) { this.acc -= TICK_MS; this.tick++; this.simulate(TICK_MS / 1000); // 逻辑只认固定 dt，不认真实耗时 this.broadcastSnapshot(); } if (guard >= MAX_CATCHUP) this.acc = 0; // 追不上就认输，丢弃积压 } }

三个参数各有讲究。TICK_MS = 50意味着每帧 50ms 的逻辑时间，20 次每秒；选 20Hz 而不是 60Hz，是因为 60Hz 下带宽和 CPU 直接翻三倍，而 2D 同屏对战对这个精度并不敏感。MAX_CATCHUP = 5是一道保险：服务端被垃圾回收卡了 800ms，如果老实补 16 帧，下一次唤醒又会欠得更多，形成雪崩，不如直接丢掉积压、接受一次跳跃。process.hrtime.bigint()而不是Date.now()，因为后者精度只到毫秒，20Hz 下误差占比不可忽略。

simulate(dt)里所有位移都必须乘dt，写成x += vx * dt。这一步写错，机器负载一变，角色速度就跟着变，是最典型的“我本地好好的，评委会电脑上跑得飞快”。

4.2 快照广播：定点数量化与一次序列化多次发送

每帧给 20 个人各发一份快照，最朴素的做法是循环里JSON.stringify20 次。20 人时看不出问题，压测到 200 连接时 CPU 直接打满。改成序列化一次、字符串复用，成本立刻降一个量级。

// server/room.js —— 定点数量化后再序列化 broadcastSnapshot() { const p = []; for (const [sid, e] of this.players) { // 坐标乘 10 取整：保留一位小数，同时把 "12.3456789" 压成 "123" p.push([sid, Math.round(e.x * 10), Math.round(e.y * 10), e.hp, e.dir]); } const text = JSON.stringify({ op: OP.SNAPSHOT, t: this.tick, p }); for (const client of this.clients) { if (client.readyState === 1) client.send(text); // 1 = OPEN } }

量化的收益比想象中大：浮点数12.3456789是 10 个字符，量化后的123是 3 个字符，20 人 20Hz 下每秒省下近 3KB。玩家肉眼分辨率根本区分不出 0.1 像素，这个精度损失没有感知。

另一个细节是readyState检查。不加这一句，只要有一个连接正在关闭，send就会抛异常，而异常发生在帧循环里，整个房间直接停摆——这就是典型的“一个人掉线，全房间卡死”。

注意：快照里永远不要带昵称、头像这类不变字段。这类信息在 JOIN_ACK 里发一次就够，混进每帧广播等于每秒重复 20 次同样的字符串。

4.3 客户端插值：用 100ms 渲染延迟换平滑

服务端 20Hz，屏幕 60Hz，中间差了三倍。如果收到快照就立刻把角色画到新位置，画面会以 50ms 为间隔一格一格跳。解决办法是故意让渲染落后一点：维护一个快照缓冲，永远渲染“100ms 之前”的那个时刻，在两帧之间做线性插值。

// client/render.js —— 快照缓冲 + 线性插值 const RENDER_DELAY = 100; // ms，约两个 tick，用来吸收网络抖动 const buf = []; // [{ at, snap }]，at 为本地接收时间 function pushSnapshot(snap) { buf.push({ at: performance.now(), snap }); // 只保留最近 1.5 秒，防止长时间运行内存持续上涨 while (buf.length > 2 && buf[buf.length - 1].at - buf[0].at > 1500) buf.shift(); } function render(now) { const t = now - RENDER_DELAY; let a = null, b = null; for (let i = buf.length - 1; i > 0; i--) { if (buf[i - 1].at <= t && t <= buf[i].at) { a = buf[i - 1]; b = buf[i]; break; } } if (!a) return; // 缓冲不够，这一帧先不画 const k = (t - a.at) / (b.at - a.at); // 0~1 的插值系数 for (const [sid, x, y, hp] of b.snap.p) { const prev = a.snap.p.find(v => v[0] === sid); const px = prev ? prev[1] : x, py = prev ? prev[2] : y; drawPlayer(sid, (px + (x - px) * k) / 10, (py + (y - py) * k) / 10, hp); } }

RENDER_DELAY = 100是个经验值。它要覆盖“一个 tick 的传输时间 + 一次抖动”，网络正常时 60ms 就够，但一旦抖一下，缓冲被吃空，角色就会卡在原地等数据。100ms 的代价是手感上慢了一拍，但对非竞技向的 Demo 完全可接受。如果指标要求 150ms 以内的端到端延迟，这里最多只能给 100ms，剩下 50ms 留给网络和服务端 tick。

缓冲上限 1.5 秒是防内存泄漏的。浏览器切到后台标签页时requestAnimationFrame会暂停，回来时缓冲里堆了几百帧，一次画完直接卡死；有了上限，最多丢一段历史，不会崩。

提示：调试插值时把a和b两个快照的 tick 号打到屏幕上。如果两个 tick 号不连续，说明中间丢了包，问题在服务端广播或网络，不在插值算法。

4.4 断线重连：会话令牌、实体保留与旧连接剔除

重连的难点不是重连本身，而是“重连之后别多出一个分身”。核心思路是：连接可以断，实体不能立刻删。玩家加入时服务端发一个 token，连接断开后实体进“保留池”，60 秒内凭 token 换回原实体；超过 60 秒才真正移除。

// server/session.js —— 实体保留 60 秒，令牌换回原角色 const RESERVE_MS = 60_000; const ghosts = new Map(); // token -> { entity, roomId, timer } function detach(client) { const { token, roomId, entity } = client; client.room.players.delete(client.sessionId); // 保留期内实体不下线，只是不再广播它的输入 const timer = setTimeout(() => ghosts.delete(token), RESERVE_MS); ghosts.set(token, { entity, roomId, timer }); } function resume(ws, token) { const g = ghosts.get(token); if (!g) return ws.send(encode(OP.ERROR, { code: 'SESSION_EXPIRED' })); clearTimeout(g.timer); ghosts.delete(token); const room = rooms.get(g.roomId); room.players.set(token, g.entity); // 原位置、原血量接回来 // 重连必须补一份全量快照，客户端此前的增量预测全部作废 ws.send(encode(OP.RESUME_ACK, { t: room.tick, p: room.snapshot() })); }

客户端侧的退避策略也要写死，不能固定 500ms 狂刷。第一次 500ms，之后每次翻倍，封顶 8 秒。

// client/net.js —— 指数退避重连，带令牌恢复 let retry = 500; const token = sessionStorage.getItem('sid'); function connect() { const ws = new WebSocket(URL); ws.onopen = () => { retry = 500; // 连上就重置退避 if (token) ws.send(JSON.stringify({ op: OP.RESUME, d: { token } })); }; ws.onclose = () => { setTimeout(connect, retry); retry = Math.min(retry * 2, 8000); }; }

还有一处必须处理：同一个 token 在保留期内可能被两个连接同时使用（玩家迅速刷新页面，旧连接还没被判死）。服务端的做法是resume成功后立刻找到该 token 对应的旧连接并terminate()，让旧连接的下行广播彻底停掉，否则会出现“我这边角色不动，别人那边看到两个我”。

5. 常见问题排查：联机 Demo 最容易翻车的五个点

这套骨架我前后改过几版，遇到的问题高度集中。下面五条按“现象 → 原因 → 解决”写，几乎每一条都在答辩现场或演示环节真实出现过。

第一条，本机能连，换台电脑连不上。现象是同一台机器开两个标签页正常，室友访问就超时。原因九成是服务端listen(3000)没写 host，绑到了127.0.0.1，只有本机可达；剩下的一成是系统防火墙拦了入站。解决是把监听改成listen(3000, '0.0.0.0')，同时让客户端用相对路径ws://${location.host}而不是硬编码 IP。硬编码 IP 还有一个副作用：换网络环境后整个前端要重新打包，血泪经验。

第二条，玩两三分钟集体掉线。现象是所有客户端几乎同时onclose，服务端日志没有任何异常。原因是中间链路（反向代理、容器网关、云主机安全组）对空闲连接有超时回收，默认值常在 60 秒上下，而玩家站着不动时确实没有业务消息。解决办法是应用层心跳：客户端每 15 秒发一次 PING，服务端回 PONG；服务端同时用ws.ping()发协议级 ping 帧，浏览器会自动回 pong。判定死亡的阈值设成心跳间隔的两倍，超过就terminate()，不要用close()——半死连接上close()常常等不到握手回包，句柄一直挂着。

第三条，位置抖动、偶发瞬移。现象是大部分时间顺滑，但每隔几秒角色“弹”一下。原因通常是客户端插值用的时间基准和服务端 tick 没有对齐，或者缓冲被吃空后代码回退到“直接画最新位置”。检查方法很土但有效：在屏幕上打出缓冲队列长度，正常情况下应该在 2 到 4 之间波动；如果频繁掉到 1，说明RENDER_DELAY给小了；如果一直涨到 10 以上，说明服务端广播频率高于客户端消费速度，或者有重复消息没去重。

第四条，重连之后出现两个自己。现象是断线重连成功，但别人看到两个角色，其中一个不动。原因就是 4.4 节说的旧连接没清理，或者detach里只删了连接没删实体、resume里又新建了一个实体。解决办法是实体和连接彻底解耦：实体只认 token，一个 token 全局只允许一个活跃连接，resume时先踢旧的再挂新的。

第五条，人数一多服务端 CPU 打满。现象是 20 人时 CPU 30%，50 人时直接 100%，tick 开始掉。原因一般是每帧对每个连接单独JSON.stringify，或者每帧遍历全量玩家做 O(n²) 碰撞。前者按 4.2 节改成序列化一次；后者把碰撞检测从“每帧全量”改成“按空间网格分桶”，20 人时其实两者差别不大，但压测到 200 连接时是数量级差距。顺带一提，Node 是单线程，一个房间的模拟卡住会拖累同进程内所有房间，压测时看到所有房间一起掉帧，就该怀疑是某个房间里有死循环。

6. 验收与答辩：一份能当场复现的测试清单

代码写完不等于交付完成。答辩现场最怕的是“我这能跑，但现在不方便演示”。我的做法是提前准备一份可以逐条打勾的验收清单，每一条都对应一个能在 30 秒内展示的操作，评委问什么就直接演示什么。

验收项	操作方法	判定标准
双人同步	两个浏览器窗口进同一房间，交替移动	双方看到的对方位置一致，无残影
延迟量级	屏幕角落常驻显示 RTT 与缓冲帧数	RTT < 50ms（局域网），缓冲帧数稳定在 2~4
掉线恢复	断网 5 秒后恢复，或直接刷新页面	10 秒内回到原房间，位置血量不重置
满员拒绝	用脚本开 21 个连接进同一房间	第 21 个收到 ERROR，前 20 个不受影响
空房回收	所有人离开后等 30 秒	服务端日志出现房间销毁，内存不持续上涨
并发承压	压测脚本 50 个假客户端跑 60 秒	服务端 tick 不丢帧，CPU 低于 70%

压测脚本不用写得很复杂，一个能定时发输入的假客户端就够：

# 50 个假客户端，每个 20Hz 发输入，跑 60 秒，观察服务端 tick 与 CPU node tools/loadtest.js --room R1 --clients 50 --hz 20 --duration 60

脚本内部只做三件事：连上、每 50ms 发一条 INPUT、统计收到的 SNAPSHOT 数量。跑完之后对比“理论应收帧数 = 20 × 60”和实际收到的数量，比值低于 0.95 就说明服务端在中途掉过帧，这时候去看MAX_CATCHUP是否触发、有没有房间在空转。

答辩讲述的顺序也有讲究。很多人上来先讲架构图，讲了三分钟评委还没看到东西动。我的建议是倒过来：先开两个窗口演示同步和断线重连——这是最有冲击力的部分；再回头讲为什么用 WebSocket 而不是轮询；最后落到帧循环和插值这两个技术点上。评委的注意力通常只在前五分钟，把最能证明“这东西真能跑”的部分放在最前面。

还有一个小技巧：提前把浏览器的网络限速调到“慢速 3G”再演示一次。画面会明显滞后但依然平滑，这恰好证明了插值缓冲在起作用；如果限速之后角色开始瞬移，说明缓冲策略还有问题，这也是评委最常追问的点。演示前把这条路径自己走一遍，比临场解释十句都管用。

从那以后我每次交这类带实时同步的项目，都会在答辩前一天晚上按清单从头跑一遍，包括换一台没装过环境的电脑、用手机热点连一次、把服务端重启一次看客户端能不能自己爬回来。这套动作看着笨，但能把“演示当天翻车”的概率压到很低。希望帮到你。

本文还有配套的精品资源，点击获取