1. 为什么我要做 OmniGame 这个项目网页小游戏这个领域看起来门槛很低但真正做过的人都知道坑比想象中多得多。我最初的想法很简单能不能做一个完全零依赖、打开就能玩、还能联机的网页小游戏集合听起来像是那种“周末两天就能搞定”的活儿结果一头扎进去就是好几个月。市面上大部分网页小游戏方案要么依赖一堆 npm 包装完 node_modules 比游戏本身还大要么联机功能必须走中心化服务器部署成本高、延迟还不可控。我试过用传统的 WebSocket 方案做联机对战服务器一挂全完蛋而且玩家分布在不同地区的时候延迟差异大到根本没法玩。后来我把目光转向了 WebRTC 的 P2P 能力配合 Shadow DOM 做样式隔离用 Next.js 做静态导出最终打磨出了 OmniGame 这套架构。OmniGame 的核心目标就三个零运行时依赖、P2P 直连联机、样式完全隔离。它适合那些想快速上手网页小游戏开发的独立开发者也适合想研究 WebRTC 实际落地的前端工程师。不管你之前有没有接触过 P2P 技术只要你会写 JavaScript就能跟着这套思路走通。这篇文章我会把整个项目的设计思路、技术选型、实操步骤、踩过的坑全部摊开来讲。不是那种“官方文档翻译”式的教程而是我自己一行行代码写出来、一个个 bug 调出来的真实记录。2. 整体架构设计与技术选型思路2.1 为什么坚持零依赖零依赖这个决定一开始其实是被逼的。我最初用了一个轻量级的游戏引擎库结果发现它内部又依赖了三个其他包那三个包各自又依赖了更多。装完之后 node_modules 有 200 多兆而我的游戏代码本身才不到 50KB。更离谱的是其中某个依赖包更新了一个小版本导致我的游戏在部分浏览器上直接白屏。从那以后我就下定决心核心运行时绝对不引入任何第三方库。游戏循环用 requestAnimationFrame 自己写碰撞检测用简单的 AABB 算法手撸输入处理直接监听原生事件。听起来工作量很大但实际上一个 2D 小游戏需要的基础功能就那么些自己写反而更可控。零依赖带来的好处是实打实的。整个 OmniGame 打包出来的静态文件压缩后不到 80KB其中还包括了所有游戏的逻辑代码。部署的时候直接扔到任何静态托管服务上就能跑不需要 Node.js 运行时不需要数据库不需要任何后端服务。这对于个人开发者来说意味着零成本部署和零运维负担。当然零依赖不等于零工具。开发阶段我还是用了 Next.js 来做构建和静态导出但最终产物是纯静态的 HTML、CSS 和 JavaScript运行时不需要任何框架支撑。这个边界要划清楚否则容易走极端。2.2 WebRTC P2P 联机的核心逻辑联机功能是 OmniGame 最有意思的部分。传统的联机方案是客户端-服务器-客户端所有数据都要经过中心服务器转发。这种方案的问题很明显服务器带宽成本随玩家数量线性增长而且物理距离导致的延迟无法避免。WebRTC 的 P2P 方案则是让两个玩家的浏览器直接建立连接数据不经过任何中间服务器。听起来很美好但实际落地的时候有几个关键问题需要解决。第一个问题是信令交换。WebRTC 建立连接之前双方需要交换 SDP会话描述协议信息和 ICE 候选地址。这个过程需要一个信令通道来传递这些信息。我的做法是用一个极简的静态信令方案利用 URL hash 传递初始信令数据配合一个可选的轻量级信令中转可以用任何支持 WebSocket 的服务甚至是一个简单的 JSON 文件轮询。第二个问题是NAT 穿透。大部分玩家都处于 NAT 网络后面直接 P2P 连接往往建立不起来。WebRTC 内置了 STUN 协议来解决这个问题通过 STUN 服务器获取自己的公网地址然后尝试打洞。实测下来在大多数家庭网络环境下STUN 就能成功建立连接。少数对称 NAT 环境下需要 TURN 中继但那是备选方案不影响核心体验。第三个问题是连接稳定性。P2P 连接建立后如果一方网络波动连接可能会断开。我实现了一套简单的重连机制检测到连接状态变化后自动尝试重新交换信令并建立新连接。整个过程对玩家透明最多感觉到短暂的卡顿。2.3 Shadow DOM 样式隔离的实战价值做游戏集合的时候样式冲突是个很烦人的问题。不同游戏可能有自己的 CSS 类名比如.player、.score、.button如果都挂在全局作用域下很容易互相覆盖。我试过用 BEM 命名规范来规避但维护成本太高而且第三方游戏接入的时候没法强制约束。Shadow DOM 提供了一种原生的样式隔离方案。每个游戏挂载在自己的 Shadow Root 里面外部的 CSS 选择器进不来内部的样式也出不去。这就像是给每个游戏发了一个独立的“房间”房间里的装修风格不会影响到其他房间。具体实现上我用attachShadow({ mode: open })创建 Shadow Root然后把游戏的 DOM 结构和样式全部塞进去。样式通过style标签内联在 Shadow Root 内部不依赖任何外部 CSS 文件。这样做的好处是游戏可以完全控制自己的视觉表现同时不会污染宿主页面的样式。有一个细节需要注意Shadow DOM 内部的事件冒泡会被限制在 Shadow Root 内部但可以通过composed: true让特定事件穿透边界。我在处理键盘输入的时候踩过这个坑后来统一在宿主层面监听键盘事件再通过自定义事件分发给当前活跃的游戏实例。2.4 Next.js 在其中的角色定位Next.js 在这个项目里只做一件事构建和静态导出。我用它来组织页面结构、处理开发时的热更新、以及最终生成静态文件。运行时的所有逻辑都是纯原生的 JavaScript不依赖 React 或任何 Next.js 的运行时能力。为什么不用 Vite 或者纯手写构建脚本因为 Next.js 的静态导出功能足够成熟配置简单而且自带代码分割和资源优化。对于一个小游戏集合来说这些开箱即用的能力能省不少事。当然如果你更熟悉其他构建工具完全可以替换核心思路不变。需要强调的是Next.js 的页面组件在静态导出后就是普通的 HTML游戏逻辑通过useEffect或者直接在script标签中初始化。我选择在页面加载完成后动态创建 Shadow DOM 并挂载游戏这样首屏渲染速度最快用户几乎感觉不到加载过程。3. 核心模块的详细实现与关键细节3.1 游戏循环与渲染管线的搭建游戏循环是整个运行时的心脏。我采用的是固定时间步长加可变渲染的混合模式。逻辑更新固定为每秒 60 次渲染则跟随 requestAnimationFrame 的节奏。这样做的好处是在不同刷新率的显示器上游戏逻辑的速度保持一致不会出现高刷屏上游戏“加速”的问题。具体实现上我维护一个累加器变量accumulator每次 rAF 回调时累加时间差当累加器超过固定步长时就执行一次逻辑更新并减去相应的时间。渲染则在每次 rAF 回调时都执行保证画面流畅。const FIXED_STEP 1000 / 60; let accumulator 0; let lastTime performance.now(); function loop(currentTime) { const deltaTime currentTime - lastTime; lastTime currentTime; accumulator deltaTime; while (accumulator FIXED_STEP) { updateGameLogic(FIXED_STEP); accumulator - FIXED_STEP; } renderGame(); requestAnimationFrame(loop); }渲染管线方面我用了 Canvas 2D 作为主要渲染后端。对于小游戏来说Canvas 2D 的性能完全够用而且 API 简单直接。每个游戏实例管理自己的 Canvas 元素绘制指令在逻辑更新阶段生成渲染阶段统一提交。这种分离设计让逻辑和渲染解耦方便后续替换渲染后端。注意Canvas 的尺寸设置有个常见坑CSS 尺寸和画布分辨率是两回事。我统一用canvas.width和canvas.height设置实际分辨率用 CSS 控制显示尺寸并在窗口大小变化时重新计算避免画面模糊。3.2 WebRTC 连接建立的信令流程WebRTC 连接建立的过程我把它拆成了四个阶段准备阶段、交换阶段、打洞阶段、连接阶段。准备阶段双方各自创建 RTCPeerConnection 实例配置 STUN 服务器地址。我用的公共 STUN 服务配置很简单const config { iceServers: [ { urls: stun:stun.l.google.com:19302 } ] }; const pc new RTCPeerConnection(config);交换阶段发起方创建 DataChannel 并生成 Offer接收方收到 Offer 后生成 Answer。这些 SDP 信息需要通过信令通道交换。我的做法是把 SDP 压缩后编码成 URL 安全的字符串通过链接分享或者二维码传递。对于需要自动匹配的场景则用一个轻量级的 WebSocket 信令服务做中转。打洞阶段是 WebRTC 自动完成的。双方交换 ICE 候选地址后浏览器会尝试各种连接路径。这个过程通常需要几秒钟期间连接状态会经历new、checking、connected等变化。我在 UI 上做了一个连接状态指示器让玩家知道当前进展。连接阶段DataChannel 的onopen事件触发后就可以开始发送游戏数据了。我设计了一个简单的消息协议每条消息包含类型字段和负载数据用 JSON 序列化。对于高频的位置同步数据则用 ArrayBuffer 做二进制编码减少传输开销。// 发送游戏状态 const encoder new TextEncoder(); const data encoder.encode(JSON.stringify({ type: player_move, x: player.x, y: player.y })); dataChannel.send(data);提示DataChannel 默认是可靠传输模式适合游戏指令这类不能丢的数据。对于位置同步这种可以容忍丢包的数据可以创建另一个不可靠模式的 DataChannel设置maxRetransmits: 0降低延迟。3.3 Shadow DOM 挂载与样式封装每个游戏的挂载过程是这样的首先在宿主页面创建一个容器元素然后调用attachShadow创建 Shadow Root接着把游戏的 HTML 结构和样式注入进去最后初始化游戏逻辑。function mountGame(container, gameModule) { const shadowRoot container.attachShadow({ mode: open }); const style document.createElement(style); style.textContent gameModule.css; shadowRoot.appendChild(style); const gameContainer document.createElement(div); gameContainer.innerHTML gameModule.html; shadowRoot.appendChild(gameContainer); gameModule.init(gameContainer, shadowRoot); }样式封装的关键在于所有游戏相关的 CSS 都写在gameModule.css字符串里不依赖任何外部样式表。这样每个游戏都是自包含的复制到任何页面都能正常工作。有一个细节值得展开说Shadow DOM 内部的字体和图片资源路径。如果游戏用了自定义字体或者图片需要确保这些资源的 URL 是绝对路径或者相对于宿主页面的正确路径。我踩过一次坑开发环境下相对路径正常部署到子目录后就 404 了。后来统一用构建时注入的 basePath 来拼接资源路径问题解决。3.4 游戏状态同步的策略选择联机游戏的状态同步有两种主流策略状态同步和帧同步。状态同步是每个客户端把自己的状态发给对方对方直接应用帧同步是每个客户端发送操作指令所有客户端执行相同的指令序列。OmniGame 根据游戏类型灵活选择。对于实时对战类游戏我用了状态同步加插值平滑的方案。本地玩家立即应用操作远程玩家的状态通过插值过渡避免画面跳跃。对于回合制游戏则用帧同步保证逻辑完全一致。状态同步的核心代码如下// 本地玩家更新 function updateLocalPlayer(input) { player.x input.dx * speed; player.y input.dy * speed; sendState({ x: player.x, y: player.y }); } // 远程玩家插值 function interpolateRemotePlayer(targetState) { remotePlayer.x (targetState.x - remotePlayer.x) * 0.2; remotePlayer.y (targetState.y - remotePlayer.y) * 0.2; }插值系数 0.2 是调出来的经验值。太小了远程玩家移动滞后明显太大了画面会抖动。不同游戏类型可能需要微调但 0.15 到 0.3 之间通常是比较舒服的范围。注意状态同步的频率不需要和渲染帧率一致。我实测下来每秒发送 20 次状态更新配合插值画面已经很流畅了。发送频率太高反而会增加网络负担得不偿失。4. 完整实操流程从零搭建一个联机小游戏4.1 项目初始化与目录结构虽然运行时零依赖但开发环境还是需要一些工具。我的项目结构是这样的omnigame/ ├── pages/ # Next.js 页面 │ ├── index.js # 游戏列表页 │ └── play/[id].js # 游戏运行页 ├── games/ # 各游戏模块 │ ├── snake/ │ │ ├── index.js │ │ ├── style.css │ │ └── logic.js │ └── pong/ │ ├── index.js │ ├── style.css │ └── logic.js ├── core/ # 核心运行时 │ ├── loop.js # 游戏循环 │ ├── net.js # WebRTC 网络层 │ └── mount.js # Shadow DOM 挂载 └── next.config.js初始化命令很简单npx create-next-applatest omnigame --javascript --no-tailwind --no-eslint cd omnigame然后修改next.config.js开启静态导出module.exports { output: export, distDir: dist, images: { unoptimized: true } };这样执行next build后dist目录里就是纯静态文件可以直接部署。4.2 核心网络层的编写网络层我封装了一个NetConnection类对外暴露connect、send、onMessage、onStateChange几个方法。内部处理 WebRTC 的创建、信令交换、连接维护和重连。class NetConnection { constructor(config) { this.pc new RTCPeerConnection(config); this.channel null; this.handlers {}; this.setupPeerConnection(); } setupPeerConnection() { this.pc.onicecandidate (e) { if (e.candidate) { this.emit(ice, e.candidate); } }; this.pc.onconnectionstatechange () { this.emit(state, this.pc.connectionState); }; } async createOffer() { this.channel this.pc.createDataChannel(game, { ordered: true }); this.setupChannel(); const offer await this.pc.createOffer(); await this.pc.setLocalDescription(offer); return offer; } setupChannel() { this.channel.onopen () this.emit(open); this.channel.onmessage (e) this.emit(message, e.data); this.channel.onclose () this.emit(close); } }信令交换我用了一个简单的方案发起方生成 Offer 后把 SDP 编码成 Base64 字符串显示在页面上让玩家复制给对方。对方粘贴后生成 Answer再复制回来。虽然手动操作有点原始但胜在零服务器依赖。如果需要自动化可以接入一个简单的 WebSocket 信令服务。4.3 游戏模块的标准化接口为了让不同游戏能以统一方式接入我定义了一个游戏模块接口export default { id: snake, name: 贪吃蛇, minPlayers: 1, maxPlayers: 4, css: ..., html: ..., init(container, shadowRoot, net) { // 初始化游戏逻辑 }, destroy() { // 清理资源 } };init方法接收容器元素、Shadow Root 和网络连接实例。游戏逻辑在这里启动通过net.send发送数据通过net.onMessage接收数据。destroy方法在切换游戏时调用清理定时器和事件监听。这个接口设计的关键点是网络层与游戏逻辑解耦。游戏不需要知道底层是 WebRTC 还是其他传输方式只需要调用统一的发送和接收接口。这样后续如果要替换传输层游戏代码完全不用改。4.4 构建与部署的实操记录构建过程很直接npm run buildNext.js 会生成静态文件到dist目录。我实测下来整个构建过程大约 15 秒产出的文件结构清晰每个游戏被分割成独立的 chunk按需加载。部署方面任何静态托管服务都可以。我试过几种方案最终选择了对象存储加 CDN 的组合。上传dist目录内容后配置 CDN 回源全球访问延迟都很低。整个部署流程可以脚本化一条命令完成构建和上传。提示静态导出后Next.js 的客户端路由需要服务端配置 fallback。如果托管服务不支持可以在next.config.js中设置trailingSlash: true生成对应的目录结构兼容性更好。5. 实际开发中踩过的坑与排查技巧5.1 WebRTC 连接失败的常见原因WebRTC 连接建立失败是最常见的问题我整理了一个排查清单现象可能原因排查方法一直处于 checking 状态STUN 服务器不可达检查 STUN 地址是否可访问连接后立即断开双方 NAT 类型不兼容查看 ICE 候选类型考虑 TURN 中继信令交换正常但无连接防火墙拦截 UDP测试 TCP 模式或更换网络部分用户能连部分不能对称 NAT部署 TURN 服务器作为备选实测下来大部分连接失败都是 STUN 服务器配置问题。我建议至少配置两个不同的 STUN 服务器增加成功率。另外ICE 候选收集需要时间不要过早判断连接失败给至少 10 秒的超时窗口。5.2 Shadow DOM 内事件处理的陷阱Shadow DOM 的事件模型和普通 DOM 有差异我踩过几个坑。第一个坑是event.target在 Shadow Root 外部会被重定向为宿主元素。如果需要在外部获取实际点击的元素要用event.composedPath()[0]。第二个坑是键盘事件。如果焦点在 Shadow Root 内部键盘事件默认不会冒泡到外部。我的解决方案是在宿主层面统一监听键盘事件然后通过自定义事件转发给活跃的游戏实例。第三个坑是 CSS 继承。Shadow DOM 内部的元素默认不继承外部样式但某些属性如font-family、color是可以继承的。如果发现样式不符合预期检查是否有继承属性在起作用。5.3 游戏循环的性能优化经验游戏循环的性能直接影响体验。我总结了几个优化点。第一避免在循环中创建对象。每次循环都new一个对象会导致频繁的垃圾回收造成卡顿。我统一用对象池管理频繁创建销毁的对象比如子弹、粒子效果。第二减少 Canvas 状态切换。fillStyle、strokeStyle这些状态的切换是有开销的。我按颜色分组绘制同一颜色的图形一次性画完减少状态切换次数。第三合理使用离屏 Canvas。对于静态背景或者不常变化的图层预先渲染到离屏 Canvas每帧直接绘制整个图层比重新绘制所有元素快得多。第四控制绘制区域。只重绘发生变化的区域而不是整个画布。对于小游戏来说这个优化可能不明显但在复杂场景下效果显著。5.4 联机延迟的优化手段P2P 联机的延迟主要来自物理距离和网络抖动。我用了几个手段来优化体验。客户端预测是最有效的。本地玩家的操作立即在本地生效同时发送给远程。远程收到后校正状态。这样本地玩家感觉不到延迟远程玩家看到的是插值后的平滑移动。状态压缩也很重要。位置数据用 Float32 而不是 JSON 数字能省不少带宽。我实测下来二进制编码比 JSON 小 60% 左右。心跳机制用来检测连接质量。每秒发送一个心跳包统计往返时间。如果延迟突然升高可以动态调整插值系数让画面更平滑。注意不要过度优化。我一开始花了大量时间做各种优化后来发现对于大多数网络环境基础的插值加预测已经足够流畅。先保证功能正确再根据实际反馈优化。6. 这套架构还能怎么扩展OmniGame 目前的实现覆盖了核心的联机小游戏场景但还有很多可以延伸的方向。比如观战模式可以让第三个连接加入但不参与游戏只接收状态更新。再比如录像回放把状态更新序列保存下来按时间轴回放。这些功能在现有架构上都不难实现因为网络层和游戏逻辑已经解耦了。另一个有意思的方向是 AI 对手。由于游戏逻辑是纯 JavaScript 的可以很方便地接入一个简单的 AI 模块在单机模式下充当对手。AI 的决策逻辑和远程玩家的输入处理可以复用同一套接口切换起来很自然。我在实际使用中发现这套架构最舒服的地方在于部署简单。没有服务器要维护没有数据库要备份一个静态目录扔上去就能跑。对于个人项目或者小团队来说这种轻量级的方案能省下大量精力让你专注于游戏本身的玩法设计。