简介基于WebSocket的在线游戏开发Demo是一份面向游戏前端或Node.js/Go开发者的实战示例包。资源围绕WebSocket实时双向通信机制展示了从HTTP升级握手、数据帧解析到客户端/服务器双向消息推送的完整链路并给出玩家操作同步与服务器状态广播等典型游戏场景的实现代码。包内共488个文件约2.96MB以JavaScript脚本和Go后端源码为主兼有HTML登录页面、图片图标以及说明文档便于对照学习。目前已吸引93人学习下载。通过运行该Demo可直观理解在线游戏中的低延迟通信设计掌握连接管理、会话保持、JSON数据交换以及断线重连、WSS加密、负载均衡等常见优化思路适合正在入门实时游戏开发或希望快速搭建网页联机对战原型的技术人员。1. 基于WebSocket的在线游戏开发Demo它到底解决了什么做实时对战游戏的第一道坎不是图形渲染也不是玩法设计而是“怎么把两个玩家的操作在毫秒级内互相传达到位”。HTTP请求-响应模式天然不适合这种场景轮询的延迟和冗余又让人头疼。这个Demo用原生WebSocket协议打通了“客户端-服务端”双向通信链路附带一套可运行的房间匹配、位置同步和状态广播逻辑。它适合刚接触实时联机、想搞清楚WebSocket到底怎么用的前端或Node开发也适合那些想做回合制卡牌或休闲对战、但不想从零趟坑的从业者。整个压缩包解压后服务端与客户端代码分离逻辑清晰改一改就能嵌进自己的项目。2. 通信协议设计消息格式、房间与帧同步2.1 为什么用WebSocket而不是Socket.io或HTTP轮询WebSocket是TCP长连接上的全双工通信协议一次握手后服务端可以主动推数据客户端也能随时发数据。相比HTTP轮询省掉了大量请求头延迟从几百毫秒降到几十毫秒。Socket.io虽然封装了断线重连和事件广播但它本质是“WebSocket 降级方案 自定义事件包装”对于想理解底层、自己控制协议的小型游戏来说反而多了一层黑匣子。这个Demo直接使用原生WebSocket服务端用ws库客户端用浏览器内置的WebSocket接口依赖少路由清晰。协议设计上Demo没有像HTTP那样用URL区分资源而是统一走一个消息入口通过JSON里的type字段区分操作。这样做的好处是所有消息类型集中管理后续加新玩法只需要扩展type不用改连接层。常见做法是把消息分为两类客户端→服务端的请求如加入房间、操作指令服务端→客户端的广播或响应如玩家进入、位置更新、游戏开始。2.2 消息帧的字段定义与示例Demo中使用了类似于下面的消息结构在实际代码中我用的是这种风格{ type: move, data: { playerId: p_1024, x: 12.5, y: 30.2, dir: up, ts: 1712345678901 } }每个消息必须有type字段data字段存放具体业务数据。ts是客户端时间戳服务端收到后可以计算网络延迟也可以用于帧同步时的乱序处理。playerId在加入房间时由服务端分配客户端在后续所有操作中携带它这样服务端才能区分消息来源。参数说明type字符串枚举值Demo里定义了join、leave、move、state_ping、game_over等。data对象具体业务负载不建议把整个对象直接塞进args里后期版本兼容会很难受。ts毫秒时间戳用于差值计算。这个设计的好处是日志检索和调试非常方便。某开发者第一次做联机时把所有消息打成日志结果发现有几个消息没有type字段排查半天才发现是客户端把type写成了小写。从那以后我都强制在协议层做schema校验直接在解析处抛出错误。2.3 房间管理与状态广播Demo服务端维护了一个房间列表每个房间最多容纳两名玩家代码里写死为2人改起来也容易。加入房间的逻辑是新连接进来后先看有没有等待中的房间有就直接加入没有则新建房间。这个设计简单实用避免了复杂的匹配算法。房间对象里保存了两个socket引用以及每帧的玩家位置。广播机制用的是ws库的clients遍历但Demo里没有盲目向所有客户端广播而是只广播给同一房间内的另一个socket。这一步很关键——如果广播范围过大人数一多带宽就爆了。我在实际项目中见过有人直接在binaryMessage里调用wss.clients.forEach发送那时候在线人数300人服务端CPU直接打满。function broadcastToRoom(room, message) { const data JSON.stringify(message); room.clients.forEach(client { if (client.readyState WebSocket.OPEN) { client.send(data); } }); }逻辑说明broadcastToRoom遍历房间的clients数组逐个发送。发送前检查readyState状态防止在连接关闭后调用send抛出异常。这里没做消息压缩因为Demo场景是小型对战一条move消息不过百字节压缩反而增加CPU开销。如果未来要做千人同屏就需要考虑二进制协议或增量编码。3. 服务端实现ws库的连接管理、心跳与广播3.1 搭建基础WebSocket服务服务端用Node.js的ws库安装命令是npm install ws。启动后监听一个端口处理连接事件。Demo的入口文件叫server.js核心逻辑大概200行。WebSocket服务不像HTTP那样有路由概念所有连接都是同一个URL比如ws://localhost:8080。const WebSocket require(ws); const wss new WebSocket.Server({ port: 8080 }); wss.on(connection, (ws) { console.log(新连接: ${ws._socket.remoteAddress}); ws.isAlive true; ws.on(pong, () { ws.isAlive true; }); ws.on(message, (data) { handleMessage(ws, data.toString()); }); ws.on(close, () { handleClose(ws); }); });逻辑说明连接建立后先设置isAlive标记用于后续心跳检测。ws库的底层socket暴露在_socket属性里可以拿到远程地址但这个属性不是标准API生产环境不建议依赖。message事件回调里data可能是Buffer需要转成字符串方便JSON解析。这里没有做二进制流处理因为Demo只用JSON文本。3.2 心跳机制与断线重连WebSocket虽然自带ping/pong帧但ws库默认不自动处理。如果不做心跳某客户端突然断网服务端可能要等TCP超时才能感知期间数据一直发不出去表现为“假死”。Demo中实现了定时ping每30秒检查一次所有连接。const interval setInterval(() { wss.clients.forEach((ws) { if (ws.isAlive false) { ws.terminate(); return; } ws.isAlive false; ws.ping(); }); }, 30000);逻辑说明每30秒把ws.isAlive置为false然后发ping帧。如果客户端正常返回pong那么之前注册的pong监听器会把它重新置为true。如果没收到pong下一次循环就会terminate掉这个连接。注意terminate和close的区别close是正常关闭会发送关闭帧terminate是直接销毁底层连接。对于已经假死的连接terminate更干脆避免后续误操作。这里有个坑如果你的客户端不是浏览器而是某个自研引擎记得在底层协议栈里自动回复pong否则会被服务端踢下线。浏览器WebSocket接口会自动响应ping这个不用操心。3.3 消息路由与业务解耦handleMessage函数里Demo用了一个简单的switch结构把不同类型分发给不同处理函数。这种做法虽然散但很好改。我一般会再封装一层路由表因为当消息类型超过15个时switch会变得又长又乱。function handleMessage(ws, rawMsg) { let msg; try { msg JSON.parse(rawMsg); } catch (e) { ws.send(JSON.stringify({ type: error, data: { message: JSON解析失败 } })); return; } if (!msg.type) { ws.send(JSON.stringify({ type: error, data: { message: 缺少type字段 } })); return; } const handlers { join: handleJoin, move: handleMove, leave: handleLeave }; const handler handlers[msg.type]; if (handler) { handler(ws, msg.data); } else { ws.send(JSON.stringify({ type: error, data: { message: 未知类型: ${msg.type} } })); } }逻辑说明先解析JSON再校验type字段最后从handlers映射表里取处理函数。这样的好处是新增消息类型只需要往对象里加一个函数不需要动主体逻辑。同时错误处理统一走error类型返回客户端收到后弹出提示即可。注意JSON.parse在消息体过大或格式错乱时会抛异常所以必须try-catch。有一次我把一个包含双引号嵌套的字符串当JSON发出去服务端直接崩溃后来才意识到需要序列化后再发。血的教训。3.4 服务端状态维护与帧同步这个Demo的核心是位置同步但它的同步方式是“事件驱动”不是固定步长帧同步。也就是说每个玩家操作时客户端发move消息服务端更新对应玩家坐标然后广播给同房间的另一个玩家。这种方式简单适合休闲对战、棋牌、卡牌。如果是动作格斗或者赛车要求流畅的物理表现就需要引入固定间隔的帧同步服务端每16ms同步一次所有实体状态客户端做插值渲染。Demo没有做那一步但我也建议你复制扩展时先想清楚自己的游戏类型。服务端维护一个players对象key是playerIdvalue是坐标和房间ID。广播时服务端只发送数据不参与具体游戏逻辑这种模式叫“权威服务器客户端预测”但在Demo里服务端只是转发客户端两个方向都能移动其实没有真正做校验。这会导致作弊问题比如玩家A直接把坐标改成地图外服务端照样广播。我做的第一个联机Demo就是这样的后来加了一段边界校验把x和y限制在合法范围内。哪怕只是这么简单的限制也能挡住大部分瞎搞的请求。4. 客户端实现Canvas渲染与WebSocket状态机4.1 客户端WebSocket连接与状态管理浏览器端的WebSocket生命周期有四个状态CONNECTING、OPEN、CLOSING、CLOSED。Demo客户端用了一个小状态机来管理连接避免在连接未建立时发送消息。const ws new WebSocket(ws://localhost:8080); ws.onopen () { console.log(连接已建立); ws.send(JSON.stringify({ type: join, data: { name: player1 } })); }; ws.onmessage (event) { const msg JSON.parse(event.data); handleServerMessage(msg); }; ws.onclose (event) { console.log(连接关闭: code${event.code}, reason${event.reason}); }; ws.onerror (error) { console.error(WebSocket错误:, error); };逻辑说明onopen后第一件事是发送join消息通知服务端加入房间。onmessage收到消息后解析交给handleServerMessage分发。onclose事件中的code字段很重要1000是正常关闭1006是异常断开。浏览器不允许修改1006所以你需要在服务端协议里自定义一个业务端断线码比如4000表示房间解散4001表示玩家被踢。参数说明event.data在浏览器里可以是字符串或Blob。Demo里服务端发的是JSON文本所以客户端直接event.data就能拿到字符串。如果客户端设置了ws.binaryType arraybuffer那么data就是ArrayBuffer此时需要手动解码。4.2 Canvas渲染玩家位置客户端渲染部分是用Canvas 2D做的没有用任何游戏引擎。画面很简单一个背景网格两个方块代表玩家。这样做的目的是把注意力集中在网络通信上而不是被引擎API带偏。function drawPlayers() { ctx.clearRect(0, 0, canvas.width, canvas.height); Object.values(gameState.players).forEach(player { ctx.fillStyle player.id selfId ? #42a5f5 : #ef5350; ctx.fillRect(player.x - 15, player.y - 15, 30, 30); }); }逻辑说明gameState是客户端持有一份同步状态的副本。每次收到服务端的state广播就更新gameState里对应玩家的坐标然后重新绘制。这里没有做插值所以当网络抖动时玩家会看到另一方的方块一跳一跳的。要改善的话可以维护一个“渲染位置”和“目标位置”之间的线性插值每帧向目标靠近15%平滑效果立竿见影。4.3 输入采集与防抖发送键盘事件在浏览器里面临一个高频问题按住方向键时keydown事件会持续触发如果每次触发都发WebSocket消息每秒能发几十上百条带宽压力很大。Demo的处理是在keydown时更新本地输入状态但在requestAnimationFrame循环里以固定间隔比如50ms发送一次当前操作。let inputState { up: false, down: false, left: false, right: false }; let lastSendTime 0; document.addEventListener(keydown, (e) { if (e.key ArrowUp) inputState.up true; // 其他方向键同理 }); document.addEventListener(keyup, (e) { if (e.key ArrowUp) inputState.up false; }); function sendLoop(timestamp) { if (timestamp - lastSendTime 50) { ws.send(JSON.stringify({ type: move, data: { dir: inputState } })); lastSendTime timestamp; } requestAnimationFrame(sendLoop); }逻辑说明inputState是布尔值组合sendLoop每次请求动画帧时检查时间差达到50ms才发送一次。这样一个玩家每秒最多发20条消息已经足够感知操作了。如果你做的是赛车或射击类可能需要把间隔缩短到16ms一帧并且把输入合并为二进制减少包体积。这里有个常见错误直接在keydown回调里调用ws.send并且没有做节流导致消息数量爆炸。某开发者调试时发现服务端日志每秒打印上百条move还以为是网络卡了实际上是客户端没做任何过滤。4.4 服务端消息分发与渲染回调handleServerMessage函数在客户端也要做一次类型分发。Demo里比较粗糙直接在函数内switchfunction handleServerMessage(msg) { switch (msg.type) { case room_joined: selfId msg.data.selfId; gameState.players msg.data.players; break; case player_move: gameState.players[msg.data.playerId].x msg.data.x; gameState.players[msg.data.playerId].y msg.data.y; break; case player_left: delete gameState.players[msg.data.playerId]; break; case error: console.error(msg.data.message); break; } }逻辑说明room_joined返回当前房间的玩家列表让新玩家初始化画布。player_move更新对应玩家的坐标。这里没有做玩家身份的区分因为Demo中只有两个玩家不管谁发来都直接更新gameState。多人在线时就需要检查msg.data.playerId是否合法防止一人操纵所有角色。5. 避坑与调试连接失败、粘包、掉线问题5.1 连接失败的三个常见原因与定位顺序现象本地打开客户端WebSocket一直连不上浏览器控制台报WebSocket connection to ws://localhost:8080/ failed。原因先看服务端是否启动终端有没有监听输出再看端口是否被占用改成8081试试最后看代理设置某些浏览器插件会拦截WebSocket请求。解决从上到下排查。我一般用curl验证端口或者直接用Node写一个三行代码的测试服务排除服务端问题再回头看客户端。具体操作顺序确认服务端代码执行了wss监听没有报错。访问http://localhost:8080WebSocket服务不处理HTTP但如果你用浏览器直接访问会看到响应头信息能证明端口在监听。检查客户端ws url是否填了正确路径Demo没有路径就是ws://ip:port。5.2 消息粘包与半包问题现象WebSocket数据帧本身有边界但如果你在客户端使用流式读取或者服务端把多条消息拼在一个缓冲区一次性发送接收端可能会拿到“粘连”的字符串。原因WebSocket是消息协议不是流协议正常使用不会粘包但如果你对同一个socket连续同步调用send多次底层TCP会合并小包。解决Demo里用的是JSON消息每条消息一个JSON.stringify所以不存在粘包问题。注意不要自己拆分字符串应该直接用message事件。如果你发现一条消息里包含了两段JSON那就是应用层错误多半是你不小心用了write而不是send。5.3 服务端广播时的并发修改异常现象遍历wss.clients时某个连接已经关闭但还留在clients列表里调用send抛错。原因js是单线程但事件循环里close事件和定时器可能交错。解决在发送时检查readyState如前面broadcastToRoom所示。另一个办法是使用数组保存连接在close事件里从数组删除而不是依赖wss.clients。5.4 心跳踢线导致的频繁重连现象连接每隔30秒断一次客户端状态显示“连接中-断开-连接中”。原因服务端设置了30秒心跳客户端没有正确回复pong。浏览器WebSocket自动回复pong所以如果你的客户端是浏览器不会有这个问题。如果是自研客户端就要手动处理pong帧。解决在客户端底层收到ping帧时立即发送pong帧不要把逻辑放在业务层。微信小程序里的WebSocket接口会隐藏ping事件你需要用onSocketMessage模拟或者干脆调短心跳时间让服务端能及时感知。5.5 JSON.parse异常导致整个连接崩溃现象客户端对服务端发送非字符串数据比如直接发送Buffer对象服务端JSON.parse失败且没有try-catch进程直接崩溃。原因我在3.3节已经提到解析必须包裹try-catch。还有一个情况是服务端向客户端发送了undefined值JSON.stringify会丢弃这个字段但客户端解析时不会报错只是数据缺失。解决客户端也做一次try-catch解析失败时打印原始内容方便排查。某开发者的血泪经验是把原始数据打印出来发现是服务端把数字类型发成了字符串单引号当双引号用导致解析失败。6. 进阶把这个Demo扩展成小游戏骨架的习惯要把它变成一个可复用的小游戏骨架我一般从三个方向做改造。第一是协议层升级第二是数据压缩第三是断线重连和时序处理。协议层升级把type和data改为二进制编码。最稳定的方案是使用一个简单的头部第一个字节表示消息类型后面四个字节是负载长度再后面是JSON字节。发送方用Buffer.concat拼出包接收方先解析头部再按长度截取。这一步能减少10倍带宽占用对于移动端尤其明显。我试过用字符串协议在一个真实对战项目里高峰期每秒消息量2000条服务端带宽被文本格式拖累换二进制后CPU占用下降30%。不过注意二进制的调试难度会上升所以建议仅在确定需要优化后再做。断线重连WebSocket的原生重连需要自己写。在客户端维护一个reconnectCount断线后延迟重连延迟时间按指数退避1秒、2秒、4秒、8秒超过10次停止重试提示用户手动刷新。重连成功后客户端要重新发送join消息同时服务端要恢复该玩家在房间内的身份。这里有一个常见问题旧连接关闭时服务端会广播player_left但重连可能还没成功导致其他客户端短暂看到玩家消失。解法是先不广播离开等待3秒如果发现该玩家重新加入就取消离开事件。这个“延迟离开”技巧在我的项目里救了无数次。时序处理游戏中的消息乱序是常态。Demo的move消息每50ms发一次但在网络抖动时后发的可能先到。解决方法是给每条消息加一个序列号seq服务端或客户端缓存最近N条消息对seq做排序。如果发现跳号就主动请求补发。这个实现不复杂但能避免很多诡异的闪现问题。我养成的习惯是每个联机Demo都先在本地用两个浏览器窗口低延迟测试再用DevTools的Network面板模拟High latency和Offline观察客户端和服务端日志。从那以后我每次写完协议都强制走一遍模拟断网、模拟延迟、模拟粘包三步验证。希望帮到你。本文还有配套的精品资源点击获取