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 连接失败是最让人头疼的问题，我整理了一张速查表：

对称型网络环境是 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 打包后压缩前大约 80KB，gzip 后 25KB 左右。对比引入 Phaser 的同类项目动辄 1MB+，差距是数量级的。

进一步优化的话，把游戏核心逻辑和 UI 代码做代码分割，首屏只加载必要的部分。字体图标用 SVG 内联而非图标字体，省一次网络请求。Canvas 的初始尺寸根据devicePixelRatio设置，避免模糊。

5.3 可扩展的方向

这个架构后续可以往几个方向扩展。一是加入房间匹配系统，用信令服务做简单的房间列表。二是支持观战模式，让一个额外的 DataChannel 单向推送状态给观战者。三是把游戏逻辑做成可插拔的模块，同一套网络层和渲染层复用到不同游戏上。

我在实际项目里发现，真正花时间的不是游戏逻辑本身，而是网络层的边界情况处理——断线重连、玩家中途加入、主机迁移。这些才是决定一个多人小游戏能不能上线的关键。主机迁移尤其麻烦，需要把权威状态从旧主机完整同步给新主机，我目前的方案是定期做全量状态快照，迁移时用最近一次快照恢复，牺牲一点实时性换取实现简单。

最后分享一个小心得：P2P 游戏的玩家体验对延迟极其敏感，哪怕 100ms 的额外延迟都能明显感觉到。所以信令交换要尽快完成，连接建立后立刻开始预热数据通道，别等到游戏真正开始才发第一条消息。这个预热动作能让开局手感顺滑不少。