简介在线游戏开发中实时双向通信是核心需求而WebSocket凭借低延迟与全双工特性成为重要解决方案。面向Web开发者与游戏开发者这份Demo展示如何利用WebSocket构建多人在线游戏环境内容覆盖连接握手、数据帧结构、文本与二进制编码、多用户位置同步、战斗事件广播、服务器主动推送以及断线重连、WSS安全传输等实战细节。包内共488个文件以JS脚本为主391个承担客户端游戏逻辑与交互辅以Go语言服务器源码、HTML登录与主界面、图片素材及说明文档整体仅2.96MB结构清晰便于按模块研读。目前已有93人学习下载适合刚接触实时通信或希望快速搭建游戏原型的开发者。通过该Demo可掌握从配置WebSocket服务器到实现多人同步、数据压缩与负载均衡的完整思路借鉴其目录组织与代码写法可快速构建自己的在线游戏原型。1. 基于 WebSocket 的在线游戏 Demo一次握手换全程实时连状态同步都省一半一个多人小游戏最怕的不是玩法而是状态同步延迟。HTTP 轮询能做到秒级但对一个 20 人同屏的点名游戏来说每秒 10 次请求足以把服务和带宽拖垮。WebSocket 的思路完全不同一次 HTTP 握手升级成 TCP 长连接之后服务端随时可以推数据客户端发指令也不用再带一堆 Header。这份 Demo 正好把这条链路从头到尾切了一遍从握手、消息路由、状态广播到断线兜底都有现成实现适合两种人刚学会 WebSocket API 但不知道服务端怎么维护连接的新手以及想快速验证「实时交互」效果、又不想从零写连接池的熟手。它解决的核心问题就是把「谁连上了、谁动了、谁掉了」这三件事在一个连接里管干净。2. 资源拆包先看工程结构再决定从哪下手2.1 目录结构一份在线游戏 Demo 通常长什么样下载下来是个 zip 压缩包解压后工程结构一般是这样的——前端静态页、服务端入口、共享协议定义、静态资源四块分开放。我拆过不少这类 Demo最常见的布局如下websocket-game-demo/ ├── server/ │ ├── index.js # Node.js 服务端入口 │ ├── room.js # 房间/会话管理 │ └── package.json # 依赖声明ws 库等 ├── client/ │ ├── index.html # 游戏主界面 │ ├── game.js # 前端逻辑连接、渲染、输入 │ └── style.css # 样式 ├── shared/ │ └── protocol.js # 消息协议定义消息类型常量 └── README.md # 启动说明关键在shared/protocol.js。服务端和前端各自独立只要遵守同一套消息枚举改动就不会互相踩脚。实际开发里我习惯把这套文件单独拎出来维护改协议时前后端一起替换谁能跑谁不能跑一下就能看出来。2.2 选型理由为什么不直接用 HTTP 轮询或 SSE先给结论这份 Demo 用 WebSocket 不是因为它新而是因为游戏场景里有两个硬需求双向实时推送、低冗余头部开销。HTTP 轮询客户端定时发请求服务端把最新状态带回来。适合低频查询但游戏里每个操作都要上报位置一秒 10 次就变成每秒 10 个完整 HTTP 报文光 Cookie 和 Header 就能吃掉一半流量。SSEServer-Sent Events服务端单向推送省了轮询但客户端不能通过同一条连接往服务端发数据还是要额外走 HTTP POST。对「每个人的操作要广播给所有人」这种场景消息路径多了一条时序就乱了。WebSocket一次握手升级之后走 TCP 帧最小帧头只有 2 字节双向随意发。延迟能做到个位数毫秒级局域网公网一般也在 50ms 以内。当然WebSocket 不是银弹。连接数上来之后服务端维护心跳、踢死假连接的成本不小这个 Demo 里服务端的room.js就承担了这部分的简化版职责。若你的业务只是「定期拉个数据展示」那 HTTP 轮询反而是成本最低的方案只有像游戏、协同编辑、行情推送这样「双方都要主动说话」的场景才有必要上 WebSocket。3. 服务端实现拆解握手、消息分发与心跳一条连接从头管到尾3.1 用 ws 库搭一个最小服务端监听、升级、广播Demo 的服务端基于 Node.js 的ws库这是目前最主流的 WebSocket 服务端实现之一。启动逻辑非常薄核心就是三件事创建 WebSocketServer、监听 connection 事件、把收到的消息按类型分发。最小骨架如下const WebSocket require(ws); const wss new WebSocketServer({ port: 8080 }); // 维护在线玩家列表key 为玩家 idvalue 为连接对象 const clients new Map(); wss.on(connection, (ws, req) { // 每个连接进来先分配一个 id const playerId req.headers[sec-websocket-protocol] ? req.headers[sec-websocket-protocol] : player_${Math.random().toString(36).slice(2, 8)}; clients.set(playerId, ws); // 告诉其他人有新玩家加入 broadcast({ type: join, playerId, ts: Date.now() }); // 接收该连接的消息 ws.on(message, (data) { let msg; try { msg JSON.parse(data.toString()); } catch (e) { ws.send(JSON.stringify({ type: error, message: invalid JSON })); return; } // 根据消息类型路由 if (msg.type action) { // 玩家操作指令附带位置/方向等 broadcast({ type: update, playerId, action: msg.action, ts: Date.now() }); } else if (msg.type ping) { ws.send(JSON.stringify({ type: pong })); } }); ws.on(close, () { clients.delete(playerId); broadcast({ type: leave, playerId, ts: Date.now() }); }); }); function broadcast(data) { const str JSON.stringify(data); clients.forEach((client) { if (client.readyState WebSocket.OPEN) { client.send(str); } }); }这里有个细节容易被新手术后clients用 Map 而不是数组因为玩家上下线频繁删除操作的时间复杂度 O(1)广播时也能顺手过滤掉readyState不是OPEN的僵尸连接。ws.on(message)里拿到的data默认是 Buffer 或字符串一定要先toString()再 JSON 解析否则处理二进制帧时会翻车。3.2 消息类型设计从「收到啥回啥」到「按 type 路由」做游戏通信消息协议最忌讳「收到一条回一条」因为状态是全局共享的。Demo 里的协议分四类type方向用途joinclient - server新玩家上线带昵称leaveserver - client有人离线前端移除对应角色actionclient - server玩家操作指令移动、使用道具等updateserver - client服务端广播最新状态一个容易忽略的问题是客户端的「动作」和服务端的「状态更新」不是一一对应的。比如客户端说「我往左走了」服务端不直接转发这句话而是更新内存中的玩家位置后再把「玩家 X 现在在坐标 (x, y)」广播出去。好处是防作弊——客户端发的原始坐标永远不可信服务端校验收敛后才广播。这个设计虽小但它是在线游戏「权威服务端」思路的雏形。3.3 心跳机制连上了不代表还活着假死连接比断线更可怕TCP 连接断开时服务端通常能收到 close 事件但如果客户端是手机突然锁屏、网络切到弱信号连接处于半开状态服务端这边永远等不到消息也等不到关闭事件。假死连接的堆积最终会耗尽文件描述符。这块 Demo 实现的覆盖逻辑是客户端每 30 秒发一次ping服务端回pong服务端自身每 60 秒遍历一遍所有连接把「超过 90 秒没收到任何消息」的连接主动 terminate。setInterval(() { const now Date.now(); clients.forEach((ws, id) { if (now - ws.lastActiveAt 90 * 1000) { ws.terminate(); clients.delete(id); } }); }, 60 * 1000);配合lastActiveAt的更新需要在ws.on(message)里每收到一条消息就刷新一次时间戳。主动terminate()比发一个消息等响应更可靠因为某些半开连接发消息后一直收不到回复反而拖慢整个清理流程。4. 前端落地从连接建立到渲染远端状态一份可抄的客户端代码4.1 连接 WebSocket 与重连策略断线重连不能只做一次前端的浏览器 API 很简单new WebSocket(ws://localhost:8080)就能连上。但写游戏要处理的事情比 API 本身多得多。Demo 里前端game.js的骨架分四步连接、绑定事件、发送操作、渲染远端状态。const wsUrl ws://${location.host}/game; let gameState { players: {}, selfId: null, }; function connect() { const ws new WebSocket(wsUrl); ws.binaryType arraybuffer; // 如果服务端发二进制必须提前设置 ws.onopen () { console.log([ws] connected); // 连上后立即上报自己的基本信息 ws.send(JSON.stringify({ type: join, nickname: player_${Date.now() % 1000} })); }; ws.onmessage (evt) { const msg JSON.parse(evt.data); handleMessage(msg); }; ws.onclose () { console.warn([ws] disconnected, retry in 3s); setTimeout(connect, 3000); }; ws.onerror (err) { console.error([ws] error, err); // onerror 之后一般会触发 onclose不需要在这里重复重连 }; }4.2 消息处理渲染远端状态不能「来一条画一条」在线游戏的前端渲染有个原则消息驱动渲染但不等于一收到消息就立刻操作 DOM。正确做法是把远端状态放到一个本地对象gameState里消息只是「更新状态」真正的渲染由requestAnimationFrame统一驱动。否则20 个玩家同时移动时DOM 会被反复修改卡顿在所难免。function handleMessage(msg) { switch (msg.type) { case join: // 新玩家加入先放进内存等待下一帧渲染 gameState.players[msg.playerId] { x: 0, y: 0, color: randomColor() }; break; case update: // 服务端广播的权威位置覆盖本地猜测 if (gameState.players[msg.playerId]) { gameState.players[msg.playerId].x msg.state.x; gameState.players[msg.playerId].y msg.state.y; } break; case leave: delete gameState.players[msg.playerId]; break; case pong: // 心跳回包可以在这里计算 RTT 并显示 break; } }还有一个细节玩家自己的位置是「本地预测 服务端校正」的双轨制。按下方向键时本地立刻移动自己减少感知延迟同时把动作发给服务端服务端广播给大家的是它的权威位置。若服务端位置和本地预测差距超过阈值就回滚修正。这个机制在正规游戏引擎里叫客户端预测这个 Demo 里做的是简化版但思路一样。5. 避开这些坑连接建立背后的五个常见问题与修复路径5.1 连接成功却收不到消息先检查事件绑定顺序和 binaryType现象服务端日志显示玩家已连接broadcast也执行了但前端页面始终看不到其它玩家。原因分两种一是onmessage事件绑定在onopen之后才做但这通常没问题因为消息事件不会在连接建立前触发真正常见的坑是ws.binaryType没设对——服务端发的是二进制帧浏览器默认当文本处理JSON.parse直接抛异常消息流程就断了。解决在创建WebSocket实例后立即设置ws.binaryType arraybuffer解析时判断数据类型字符串走JSON.parseArrayBuffer 走new TextDecoder().decode()。5.2 主动断开还是被动掉线不要用「请求超时」当心跳现象客户端经常断线重连服务端日志显示连接被重置。原因把心跳机制误写成「客户端每隔 30 秒发一次 ping然后设一个 5 秒的 setTimeout超过 5 秒没收到 pong 就断开」。移动网络下一个正常的保活包延迟 510 秒很常见误杀率极高。解决把「客户端断开」改为「服务端统一清理」计算的是最后活跃时间而不是单次请求的响应时间。这样客户端永远不主动断开除非连续多次 ping 无响应才给用户提示。5.3 数个连接争抢同一玩家 ID要校验重复会话现象同一玩家用两个浏览器标签页打开游戏后打开的页会把先打开的挤下线或者两个连接同时往服务端发消息状态错乱。原因客户端生成playerId的方式是随机数不具备唯一性且服务端没有做「新旧连接替换」的逻辑。解决服务端在join时校验该玩家 ID 是否已存在。若存在先terminate()旧连接再注册新连接同时给旧连接发送一条kick消息提示「账号在其他设备登录」。这是 WebSocket 在线游戏的常规操作MySQL 里UNIQUE KEY的思路到这里同样适用。5.4 端口与路径反代没配 /ws 路径连接一直 404现象本地直接访问ws://localhost:8080没问题部署到服务器后用wss://访问就报 404 或者握手失败。原因常见的部署拓扑是 Nginx 反代但 Nginx 默认只转发 HTTP 升级请求的关键 Header需要额外配置proxy_set_header Upgrade和proxy_set_header Connection upgrade且需要专门把/ws路径代理到后端端口。解决Nginx 配置加这一段再nginx -s reloadlocation /ws { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; }5.5 用wss://访问却用ws://连协议混淆现象页面是通过 HTTPS 打开的但代码里连的是ws://浏览器控制台报错Mixed Content: The page at https://... was loaded over HTTPS, but attempted to connect to an insecure WebSocket.原因浏览器安全策略不允许 HTTPS 页面发起非加密的 WebSocket 连接。解决判断当前页面协议动态选择 ws 还是 wssconst wsUrl ${location.protocol https: ? wss : ws}://${location.host}/ws;这是我在部署时最容易翻车的一处本地正常一上生产就黑屏因为写死了ws://协议。6. 验证与进阶用 wscat 实测把 demo 改成房间制游戏验证这套东西能不能扛起真实场景不要只开一个浏览器页面。先装一个命令行 WebSocket 客户端wscat它能模拟第二个独立玩家方便验证广播链路npm install -g wscat wscat -c ws://localhost:8080打开后你会看到和自己浏览器一样的消息流——有人加入、有人更新状态。这个工具还能测试服务器主动断开的行为关掉服务端进程wscat 会立刻打印connection closed比前端日志更直观。压测连接数同理可以用websocat或写个简单的 Node 脚本循环建连看服务端内存和文件描述符变化就能测出这台机器最多扛多少在线玩家。不需要复杂的压测工具这层验证对 demo 阶段完全够用。再往深走一步把这份 demo 从「一个房间全员广播」改成真正的房间制核心改动只有两处服务端clients从单一 Map 改为MaproomId, MapplayerId, ws广播函数改成按房间维度遍历前端join消息里增加roomId字段超时时间50ms和消息重发策略可以顺手加上。改完之后每个房间的消息不再互相干扰玩法就能从「所有人在同一张地图」扩展到「每个房间独立一个地图」。另外提一个我自己的习惯所有消息统一带ts时间戳前端显示延迟、服务端统计活跃度都靠它。这个 Demo 里已经预留了这个字段但很多人容易忽略它只当是消息格式的一部分其实它是排查线上问题的第一线索。从那以后我每次接手此类实时项目第一件事就是确认所有消息是否带头尾时间戳没有就先补上再去查功能逻辑希望帮到你。本文还有配套的精品资源点击获取