了解Edgegap的工作原理

對局配對

和

托管与编排

整合

Browser Games (JavaScript-based)

部署至 Edgegap

已发布

2026/10/16

最近一次准确性审核

2026/11/4

网页游戏（基于 JavaScript）：如何在专用服务器上托管多人 Three.js、Phaser 和 Babylon.js 游戏，并添加對局配對

本指南将向您展示如何在 Edgegap 的专用游戏服务器上托管使用 JavaScript 或 TypeScript 编写，并基于 Three.js、Phaser、Babylon.js、PixiJS 或纯 Canvas 构建的多人网页游戏，随后添加匹配功能，以便玩家能够自动分组并连接到离他们最近的服务器。

一旦您的游戏服务器完成容器化，Edgegap 即可通过简单的 API 调用将其部署到全球 615 多个边缘云节点（按需部署），并完全按使用量计费：无需在两场比赛之间租用、预配或保持整个服务器持续运行。对于需要预留容量的持久性服务器，Edgegap 提供了专用机队（Private Fleets）。Edgegap 的匹配（Matchmaking）建立在此基础之上，并且是可选功能。

网页游戏上线时会发生两项变化。首先，其规则会移至服务器端，因为任何人都可以在浏览器中查看和编辑运行的代码。其次，它通过 WebSocket 与该服务器通信：浏览器无法建立 UDP 连接，且通过 https:// 提供的页面只能使用安全 WebSocket（wss://）。您的服务器运行在 Node.js 中，Edgegap 的 TLS 升级 为其提供了安全的 WebSocket 端点，因此您无需购买或续订证书。

本指南涵盖：

准备您的游戏、Edgegap 账户以及容器化工具
将您的代码助手智能体连接到 Edgegap（可选）
将游戏规则迁移至 Node.js WebSocket 服务器
对服务器进行容器化并创建应用版本
部署测试服务器并从浏览器进行连接
添加匹配功能（可选）
发布您的游戏网页
在两个浏览器标签页中测试完整流程

您可以通过两种方式进行操作，也可以将它们结合使用：

借助代码智能体。将 Claude Code、Cursor 或其他智能体连接到 Edgegap MCP 服务器及其智能体技能。智能体将您的游戏拆分为客户端和服务器端，编写服务器代码和 Dockerfile，进行部署并设置匹配。您只需负责 Edgegap 控制台、机密管理和游戏测试。
纯手动操作。以下每个步骤也可以在没有智能体的情况下完成。

如果您的游戏是使用 Manus 构建的，请参阅 Manus AI。如果是使用 Unity 构建的，请参阅 Unity WebGL。

与工程师联系

无需信用卡。免费版包含部署真实游戏服务器所需的资源。

分步指南

详细集成步骤

1. 开始之前

一个免费的 Edgegap 账户。请验证您的电子邮件。测试无需信用卡。
基于 JavaScript 或 TypeScript 的浏览器游戏，可使用任何引擎：Three.js、Phaser、Babylon.js、PixiJS 或您自己的 canvas 循环。
用于游戏服务器的 Node.js（版本 22 或更高版本），以及正在运行的容器化工具。我们推荐使用 Docker Desktop。
您自行控制的后端（可选，建议用于正式发布）：用于为玩家登录并代表他们向匹配系统请求匹配。您现有的 Web 后端即可使用。有关实际示例，请参阅 Supabase Sumo Push 示例：在 Supabase 上实现登录、个人资料和排行榜，并通过 Supabase Edge Function 进行匹配。
对于代理路径：从控制面板 → 用户设置 → 令牌获取的 Edgegap API 令牌。它在组织范围内有效，因此请将其视为密码对待：切勿将其放入您的游戏、网页、服务器或聊天中。

2. 将您的代码代理连接到 Edgegap

如果您全程手动操作，请跳过此步骤。

Edgegap MCP 服务器允许您的智能体（agent）在您的账户上创建应用程序和版本、部署服务器、读取日志并生成匹配器配置。智能体技能为其提供了经过测试的 JavaScript 游戏构建组件：一个能够自动停止的 Node.js WebSocket 游戏服务器、一个支持重连的浏览器客户端、一个创建匹配票证的后端，以及 Dockerfile。这些均来自 edgegap-threejs 技能，并在 Edgegap 上通过了五款 Three.js 游戏的测试。其服务器和匹配组件不依赖于渲染器，因此也适用于 Phaser、Babylon.js 或纯 canvas。对于后端，请添加与您相匹配的技能：edgegap-supabase、edgegap-colyseus 或 edgegap-manus（参见步骤 6）。

Claude Code：安装 Edgegap 插件。它会同时添加 MCP 服务器和技能，并在安装过程中要求提供您的 API 令牌（存储在您系统的凭据存储中）：

/plugin marketplace add edgegap/llm-agent-skills，然后运行 /plugin install edgegap@edgegap。重启会话。

如果只需要 MCP 服务器，而不需要插件？请在您自己的终端中运行以下命令：claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user。切勿两者同时操作，否则您将拥有两个 edgegap 服务器。

Cursor、VS Code 以及其他支持发送请求头的客户端：添加 https://mcp.edgegap.dev/mcp 并附带请求头 Authorization: token YOUR_EDGEGAP_API_TOKEN，然后使用 npx skills add edgegap/llm-agent-skills --skill "*" 安装技能。

Claude Desktop：自定义连接器无法发送请求头，因此请改用本地服务器（Node 18+）：{ "mcpServers": { "edgegap": { "command": "npx", "args": ["-y", "@edgegap/mcp"] } } }。它会在首次使用时请求令牌。

检查是否正常运行：

“列出我的 Edgegap 应用程序。”

3. 将游戏规则移至 Node.js WebSocket 服务器

大多数网页游戏都在一个循环中运行所有内容：读取输入、更新游戏、绘制。将其拆分为两部分：

服务器掌管位置、物理和碰撞、得分、生命值、计时器、生成、随机性以及谁在对局中。它以固定速率（大多数游戏适合每秒 20 次）运行更新步骤，并将状态发送给每位玩家。
浏览器捕获输入并将其作为意图发送（“向右按”、“开火”），绝不是结果（“我在 x=500”）。它绘制接收到的状态，在更新之间进行平滑处理，并保留菜单、声音和特效。

按引擎划分：

Three.js 和 Babylon.js：服务器只需要数字（位置、旋转）。兼容 Node 的物理引擎（如 Rapier 或 cannon-es）可原样在服务器上运行。
Phaser：Phaser 需要页面才能运行，因此请将其保留在浏览器中，并将其游戏决策转移到服务器上你自己的模拟中。
PixiJS 和普通 canvas：循环的更新步骤移至服务器；绘制步骤保留。
每帧移动固定量的代码（x += 5）首先需要变为每秒速度乘以经过的时间：服务器的 tick 频率是 20 Hz，而不是 60。

Edgegap 需要服务器提供的内容：它通过普通 WebSocket 在固定端口（例如 7777）上的 0.0.0.0 进行侦听，并在比赛结束时停止自身的部署（第 4 步涵盖了该调用）。

配合你的智能体：

“加载 edgegap-threejs 技能。拆分我的游戏：将规则移入在 0.0.0.0:7777 上运行的权威 Node.js WebSocket 服务器，该服务器以 20 Hz 进行 tick 并发送状态快照，然后更改浏览器以发送输入并绘制快照。接着在本地用两个标签页进行测试。”

4. 将服务器容器化并创建应用版本

Edgegap 运行 linux/amd64 容器。对于 Node.js 服务器：

从精简的 Node 镜像开始（FROM node:22-slim），仅安装生产环境包（npm ci --omit=dev），并直接启动服务器：CMD ["node", "server.js"]。通过 npm start 运行会向您的服务器隐藏停止信号。以 node 用户身份运行，而不是 root。
即使在 Apple Silicon 上，也请针对 Edgegap 平台进行构建：docker build --platform linux/amd64 -t registry.edgegap.com/<project>/<image>:<tag> .，然后使用来自容器注册表页面的凭据执行 docker login registry.edgegap.com 后进行 docker push。每次构建都使用新标签。

在控制面板中创建应用程序和版本：设置您的镜像和标签、注册表凭据、初始配置为 0.25 vCPU 和 512 MB，端口为 7777，协议为 WS，名称为 gameport，并开启 TLS Upgrade。

在比赛结束时停止服务器：您的服务器向 ARBITRIUM_DELETE_URL 环境变量发送 DELETE 请求，并使用 ARBITRIUM_DELETE_TOKEN 作为其 Authorization 请求头。在游戏结束 10 秒后、所有人都离开 30 秒后，或若无人加入则在 2 分钟后执行此操作。收到 SIGTERM 信号时，通知玩家并退出。

可选，配合 JavaScript SDK 使用：来自 @edgegap/sdk 的 DeploymentEnvironment 和 MatchEnvironment 会为您读取 Edgegap 的环境变量，包括自动停止 URL 和比赛门票，而 ServerAgent 则通过回填填补空缺席位。请将其服务器令牌保存在环境变量中，切勿放入浏览器捆绑包内。

配合您的智能体使用：

"加载 edgegap-containerize 技能。将我的 Node.js 游戏服务器针对 linux/amd64 进行容器化，使用新标签推送，并创建 Edgegap 应用和版本：端口 7777，协议 WS，开启 TLS Upgrade，命名为 gameport，0.25 vCPU 和 512 MB。"

5. 部署测试服务器并从浏览器进行连接

从控制面板部署您的版本（点击 Deploy，选择离您较近的位置），或者让您的代理执行：“在靠近我的位置部署我最新的 Edgegap 版本，等待其就绪，检查 WebSocket 端口是否响应 HTTP 101，并向我提供主机名和外部端口。”

当部署状态为 Ready 时，在您的游戏页面中使用 new WebSocket("wss://<Host URL>:<External Port>") 进行连接。请始终使用主机名而非 IP 地址，否则证书验证将会失败。外部端口在每次部署时都会发生变化。

如果服务器日志显示 First bytes from client was not 'GET'，说明该端口未开启 TLS 升级（TLS Upgrade）：请在新的应用版本中将其开启。

完成后请停止部署。免费层每次仅支持运行一个部署。

6. 添加匹配功能

Edgegap 的匹配器根据您的规则（比赛规模、队伍、模式、地区）对玩家进行分组，将您的服务器部署在他们附近并返回其地址。对于网页浏览器游戏：

无延迟规则。浏览器无法像桌面游戏那样发送延迟 Ping；匹配器转而根据玩家所在的位置来部署服务器。
由您的后端请求比赛（推荐）。后端负责让玩家登录，使用匹配器的 Auth Token 创建匹配票证（ticket），并且仅向浏览器提供服务器地址以及用于服务器校验的短期有效加入令牌（join token）。每个玩家一个票证，绑定真实账户。
或者由浏览器直接请求（用于原型）：在配置的 allowed_cors_origins 中列出提供游戏服务的所有网址，否则浏览器会阻止回复。

选择您的后端：

无后端（原型）：浏览器直接使用 JavaScript SDK (npm install @edgegap/sdk) 请求匹配器。其 GroupAgent 会创建票证、等待服务器并生成 wss:// 地址。Edgegap 的 Three.js 小游戏正是使用了该方式。
Supabase：Supabase 负责玩家登录并保存个人资料和排行榜。Supabase Edge Function 保存匹配器的 Auth Token，并为每个已登录玩家创建一个票证，游戏服务器会验证每个玩家的票证并上报结果。请参阅 Supabase Sumo Push 示例和 edgegap-supabase 技能（skill）。
Colyseus：房间和状态同步保留在 Colyseus 上，每场比赛都在其独立的 Edgegap 服务器上运行。请参阅 Colyseus 指南。
使用 Manus 构建：请参阅 Manus AI 指南。

接下来：

使用您的智能体（Agent）生成配置：“为我的应用版本生成 Edgegap 匹配器配置：一支 2 到 8 名玩家的队伍，无延迟规则，单独一名玩家在 20 秒后分配到服务器。”
在控制面板中，打开 Matchmaker，选择 Create Matchmaker，上传文件并选择 Create and Start。将 API URL 和 Auth Token 复制到后端的机密（secrets）中。
向您的智能体发出指令：“加载 edgegap-threejs 技能以及适用于我后端的技能（edgegap-supabase、edgegap-colyseus 或 edgegap-manus）。通过我的后端添加具有加入（join）、状态查询（status）和取消（cancel）功能的匹配系统，并在我的游戏中添加一个‘寻找比赛’（Find Match）按钮，该按钮通过 wss:// 连接到分配的服务器。在没有后端的情况下，请在浏览器中使用 JavaScript SDK。”

7. 发布你游戏的网页

您可以将游戏页面托管在任何您喜欢的地方：您自己的网站、静态托管服务、itch.io 或游戏门户。请进行两项检查：

该页面通过 https 提供服务，因此游戏会使用 wss:// 进行连接，TLS Upgrade 已经可以处理此问题。
如果浏览器直接调用匹配系统，请将该页面的地址添加到 allowed_cors_origins 中（对于 itch.io：https://YOUR-NAME.itch.io 和 https://html-classic.itch.zone）。每个条目都是一个完整的源（包含端口），并且支持通配符，例如 https://*.my-game.com。仅填写 localhost 无法匹配任何内容：请完整列出您的开发服务器，例如 http://localhost:5173。