1. 项目缘起与整体设计思路1.1 为什么要在浏览器里做“零依赖”小游戏做网页小游戏这件事很多人第一反应是“引个引擎就完事了”。Phaser、PixiJS、Cocos Creator甚至直接上 Three.js生态成熟、文档齐全确实省事。但我在实际项目里反复遇到几个绕不开的痛点引擎体积动辄几百KB到几MB首屏加载慢版本升级带来破坏性变更老项目维护成本高更关键的是一旦涉及多人联机绝大多数轻量引擎并不内置网络层你得自己接 WebSocket 服务端部署、扩容、运维全是钱。OmniGame 这个项目的出发点就是把这些痛点一次性解决掉。它的核心目标可以概括成三句话零第三方运行时依赖、基于 WebRTC 的 P2P 直连、用 Shadow DOM 做样式隔离。听起来有点“造轮子”的意思但造这个轮子是有明确工程理由的——当你把游戏逻辑压缩到原生 API 能覆盖的范围你换来的是极致的加载速度、极低的运维成本和极强的可移植性。这个项目适合谁参考如果你是有一定前端基础、想理解“不依赖框架怎么把游戏跑起来”的开发者或者你正在做多人实时互动的小型应用、想搞清楚 P2P 连接到底怎么落地那这篇内容会对你有直接帮助。它不适合完全零基础的新手因为里面涉及不少浏览器底层 API 的细节但我会尽量把每个概念用生活化的方式讲清楚。1.2 技术选型的四个关键决策整个项目的架构决策我梳理成四个核心选择每一个背后都有取舍。第一个决策是渲染层用 Canvas 2D 而非 WebGL。WebGL 性能上限更高但对小游戏来说Canvas 2D 的 API 更直观调试成本低得多。实测下来几百个精灵的 2D 场景Canvas 2D 在主流设备上稳定 60 帧没问题。真正需要 WebGL 的是 3D 或大量粒子特效那不是这个项目的目标场景。第二个决策是网络层用 WebRTC DataChannel 而非 WebSocket。WebSocket 必须有一个中心服务器转发消息玩家越多服务器带宽和并发压力越大。WebRTC 的 DataChannel 建立的是浏览器到浏览器的直连通道数据不经过你的服务器理论上服务器只负责“牵线”信令交换之后就可以退场。这对小团队来说运维成本几乎归零。第三个决策是样式隔离用 Shadow DOM。游戏 UI 和宿主页面的 CSS 很容易互相污染尤其是当游戏被嵌入到别人的页面里时。Shadow DOM 提供原生的样式作用域隔离不需要 BEM 命名规范那套人为约束也不需要 CSS-in-JS 的运行时开销。第四个决策是构建工具用 Next.js 但只取其静态导出能力。Next.js 的路由、SSR、API Routes 这些能力在这个项目里其实用不上我看中的是它的工程化配置、TypeScript 支持和静态导出output: export。最终产物是一堆纯静态文件扔到任何静态托管上就能跑不需要 Node 服务端。提示这四个决策不是孤立的它们互相支撑。零依赖让静态导出变得干净静态导出让 P2P 架构的部署变得极简Shadow DOM 让嵌入场景变得无痛。选型时要看整体而不是单点最优。2. 核心细节解析与实操要点2.1 WebRTC P2P 连接到底是怎么建立的很多人对 WebRTC 的印象停留在“视频通话”其实它的 DataChannel 才是做游戏联机的利器。要理解 P2P 连接得先搞清楚三个角色信令服务器、STUN 服务器、对等端。信令服务器的作用是“交换名片”。两个浏览器想直连但彼此不知道对方的网络地址所以先各自连到信令服务器把自己的连接信息SDP offer/answer 和 ICE candidate发上去服务器帮忙转发给对方。这个过程叫“信令交换”。信令服务器可以用任何方式实现WebSocket、HTTP 轮询都行因为它只在连接建立阶段工作之后就不参与数据传输了。STUN 服务器的作用是“告诉你自己长什么样”。你的浏览器在局域网里公网看不到你的内网地址STUN 服务器帮你探测出你在公网上的映射地址也就是 ICE candidate 里的 srflx 类型。绝大多数情况下有了 STUN 就能建立直连。连接建立的核心流程是这样的// 发起方 const pc new RTCPeerConnection({ iceServers: [{ urls: stun:stun.example.com }] }); const channel pc.createDataChannel(game, { ordered: false, maxRetransmits: 0 }); const offer await pc.createOffer(); await pc.setLocalDescription(offer); // 通过信令服务器把 offer 发给对方 // 接收方 const pc2 new RTCPeerConnection({ iceServers: [{ urls: stun:stun.example.com }] }); pc2.ondatachannel (e) { const ch e.channel; /* 绑定消息处理 */ }; await pc2.setRemoteDescription(offer); const answer await pc2.createAnswer(); await pc2.setLocalDescription(answer); // 通过信令服务器把 answer 发回发起方这里有个关键参数容易被忽略ordered: false和maxRetransmits: 0。对于实时游戏的位置同步丢一帧旧数据比等它重传更有意义所以选择不可靠传输模式。但如果是聊天消息或关键指令就得用可靠模式默认ordered: true。这个取舍直接决定了游戏的同步手感。2.2 Shadow DOM 做样式隔离的实操细节Shadow DOM 的用法本身不复杂attachShadow({ mode: open })就能创建一个影子根但实际项目里有几个坑。第一个坑是事件穿透。Shadow DOM 内部的事件默认会被重定向到宿主元素event.target在外部拿到的是宿主而非内部真实元素。如果你需要精确知道点到了哪个内部元素得用event.composedPath()来获取完整路径。第二个坑是样式继承。Shadow DOM 隔离了选择器但可继承属性color、font-family 等依然会从宿主穿透进来。所以初始化时最好显式重置:host { all: initial; display: block; contain: content; }all: initial把所有属性重置为初始值contain: content告诉浏览器这个子树的内容不会影响外部布局能带来渲染性能提升。第三个坑是字体和图标。Shadow DOM 里引用外部字体需要显式声明font-face因为外部的字体定义不会自动继承。我的做法是把字体文件转成 base64 内联进样式虽然体积大一点但省去了加载时序问题。2.3 游戏循环与状态同步的设计游戏主循环用requestAnimationFrame驱动这是标准做法。但多人游戏的核心难点在于状态同步策略。我采用的是“主机权威 客户端预测”的简化版。选一个玩家作为主机通常是房间创建者主机负责跑权威的游戏逻辑把状态快照广播给其他玩家。其他玩家本地也跑一份逻辑用于即时反馈预测收到主机快照后做校正。同步频率上位置数据每帧发送太浪费带宽我实测 20Hz每 50ms 一次对大多数休闲游戏足够。发送的数据结构要尽量精简用数组而非对象用数字索引而非字符串键// 不推荐 { type: move, playerId: abc, x: 100, y: 200 } // 推荐 [1, 0, 100, 200] // [消息类型, 玩家索引, x, y]这个优化在玩家多的时候效果明显JSON 的键名重复传输是纯浪费。3. 实操过程与核心环节实现3.1 项目初始化与目录结构用 Next.js 起项目但配置成静态导出模式。next.config.js里加上/** type {import(next).NextConfig} */ const nextConfig { output: export, images: { unoptimized: true }, trailingSlash: true, }; module.exports nextConfig;目录结构我按职责划分避免所有东西堆在pages里src/ game/ # 游戏核心逻辑纯 TS不依赖 DOM engine.ts # 主循环、时间步管理 entities.ts # 实体定义与更新 physics.ts # 碰撞检测 net/ # 网络层 peer.ts # WebRTC 封装 signaling.ts # 信令交换 protocol.ts # 消息编解码 ui/ # 界面层 shadow-host.ts # Shadow DOM 宿主封装 hud.ts pages/ index.tsx把game目录做成纯逻辑、不碰 DOM好处是它可以在 Node 环境里跑单元测试也方便未来移植到其他渲染后端。3.2 信令交换的最小实现信令服务器我用了最简单的方案一个基于 HTTP 长轮询的“消息信箱”。每个房间有一个队列玩家 POST 自己的信令消息GET 拉取对方的消息。这样连 WebSocket 服务端都不用起一个静态托管加一个极简的 KV 存储就能跑。// signaling.ts 核心逻辑 async function exchangeSignal(roomId: string, myId: string, message: any) { await fetch(/api/signal/${roomId}, { method: POST, body: JSON.stringify({ from: myId, payload: message }), }); const res await fetch(/api/signal/${roomId}?for${myId}); return res.json(); }实际生产环境里这个信令服务可以用任何支持 HTTP 的 Serverless 函数实现冷启动延迟对信令交换影响不大因为交换只在开局发生一次。3.3 数据通道的建立与消息协议连接建立后DataChannel 的onmessage是消息入口。我设计了一个极简的二进制协议用ArrayBuffer而非 JSON 字符串进一步压缩体积const MSG_MOVE 1; const MSG_SPAWN 2; const MSG_DESPAWN 3; function encodeMove(playerIdx: number, x: number, y: number): ArrayBuffer { const buf new ArrayBuffer(7); const view new DataView(buf); view.setUint8(0, MSG_MOVE); view.setUint8(1, playerIdx); view.setInt16(2, x, true); view.setInt16(4, y, true); return buf; }坐标用Int16而非Float32因为游戏世界坐标范围有限Int16的 ±32767 完全够用还能省一半带宽。这个细节在玩家数量上来之后收益很明显。3.4 渲染与 Shadow DOM 集成渲染层封装成一个类对外只暴露mount(container)和unmount()。内部创建 Shadow Root把 Canvas 和 HUD 都塞进去class GameRenderer { private shadow: ShadowRoot; mount(container: HTMLElement) { this.shadow container.attachShadow({ mode: open }); const style document.createElement(style); style.textContent GAME_STYLES; // 内联的完整样式 this.shadow.appendChild(style); const canvas document.createElement(canvas); this.shadow.appendChild(canvas); this.ctx canvas.getContext(2d); this.startLoop(); } }GAME_STYLES是一整块字符串包含所有游戏内样式。因为 Shadow DOM 隔离我不用担心类名冲突可以用.player、.hud这种最简命名。4. 常见问题与排查技巧实录4.1 P2P 连接失败的高频原因P2P 连接失败是最让人头疼的问题我整理了一张速查表现象可能原因排查方法ICE 一直处于 checkingSTUN 不可达或网络限制换 STUN 服务器检查控制台 ICE candidate 列表连接建立后立即断开DataChannel 配置不兼容确认双方ordered/maxRetransmits一致部分用户永远连不上对称型网络环境需要 TURN 中继兜底信令交换超时轮询间隔过长缩短轮询间隔或改用推送对称型网络环境是 P2P 的天然克星大约有 10% 到 20% 的用户处于这种环境STUN 探测出的地址无法用于直连。这时候必须有 TURN 服务器做中继兜底。TURN 会消耗服务器带宽但只在直连失败时启用成本可控。4.2 Shadow DOM 里的性能陷阱我踩过一个坑在 Shadow DOM 里频繁操作 DOM 导致重排。游戏 HUD 如果每帧更新文本内容会触发大量样式计算。解决办法是把 HUD 更新节流到 10Hz并且用transform而非top/left做位移让浏览器走合成层。另一个坑是contain属性用错。contain: strict虽然性能最好但会裁掉溢出内容如果游戏有弹出式 UI 就会被切掉。我最终用contain: layout paint兼顾性能和显示。4.3 状态不同步的调试方法多人游戏最难调的是“我这边看到的位置和别人不一样”。我的调试手段是在开发模式下叠加一个网络状态面板显示每个玩家的本地预测位置和最近一次主机快照的差异值。当差异超过阈值时高亮一眼就能看出是预测算法问题还是网络延迟问题。还有一个实用技巧给每个状态快照打上递增的序号客户端收到乱序快照时直接丢弃旧的。UDP 式的不可靠传输下乱序是常态不做序号校验会出现“瞬移”现象。注意调试 P2P 时本地开两个标签页测试往往连不上因为同一台机器的 ICE candidate 可能互相冲突。建议用两台设备或两个不同网络环境测试或者强制走 TURN 中继来验证逻辑正确性。5. 工程化与部署的实战经验5.1 静态导出后的部署选择因为最终产物是纯静态文件部署选择非常自由。我试过几种方案对象存储加 CDN、静态托管平台、甚至直接扔进一个 Nginx 目录。核心要求只有一个——支持 HTTPS因为 WebRTC 的getUserMedia和部分 API 在非安全上下文下不可用DataChannel 本身在 localhost 下可用但生产环境必须 HTTPS。信令服务单独部署用 Serverless 函数最省心。它只在开局时被调用几次流量极小免费额度基本够用。5.2 首屏加载的极致优化零依赖的最大红利就是首屏快。整个游戏 JS 打包后压缩前大约 80KBgzip 后 25KB 左右。对比引入 Phaser 的同类项目动辄 1MB差距是数量级的。进一步优化的话把游戏核心逻辑和 UI 代码做代码分割首屏只加载必要的部分。字体图标用 SVG 内联而非图标字体省一次网络请求。Canvas 的初始尺寸根据devicePixelRatio设置避免模糊。5.3 可扩展的方向这个架构后续可以往几个方向扩展。一是加入房间匹配系统用信令服务做简单的房间列表。二是支持观战模式让一个额外的 DataChannel 单向推送状态给观战者。三是把游戏逻辑做成可插拔的模块同一套网络层和渲染层复用到不同游戏上。我在实际项目里发现真正花时间的不是游戏逻辑本身而是网络层的边界情况处理——断线重连、玩家中途加入、主机迁移。这些才是决定一个多人小游戏能不能上线的关键。主机迁移尤其麻烦需要把权威状态从旧主机完整同步给新主机我目前的方案是定期做全量状态快照迁移时用最近一次快照恢复牺牲一点实时性换取实现简单。最后分享一个小心得P2P 游戏的玩家体验对延迟极其敏感哪怕 100ms 的额外延迟都能明显感觉到。所以信令交换要尽快完成连接建立后立刻开始预热数据通道别等到游戏真正开始才发第一条消息。这个预热动作能让开局手感顺滑不少。