了解Edgegap的工作原理

對局配對

和

托管与编排

整合

Unity WebGL

部署至 Edgegap

已发布

2024/5/12

最近一次准确性审核

2026/10/16

Unity WebGL：如何在专用服务器上托管浏览器多人游戏并添加對局配對

本指南向您展示如何在 Edgegap 的专用游戏服务器上托管使用 Unity 构建的网页端（WebGL）多人游戏，然后添加匹配功能，以便玩家可以自动分组并连接到附近的服务器，并将其发布到 itch.io。

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

网页游戏与桌面游戏有一个巨大的区别：浏览器无法打开 UDP 连接。您的游戏通过 WebSockets 与其服务器通信，而通过 https:// 提供的页面只能使用安全 WebSockets (wss://)。Edgegap 的 TLS Upgrade 为每台服务器提供了一个安全 WebSocket 端点，因此您无需购买或更新证书。

本指南涵盖：

准备 Unity、您的网络代码、Edgegap 账户和容器化工具
将您的编码智能体连接到 Edgegap（可选）
让您的游戏准备好适配浏览器和专用服务器
构建并容器化您的游戏服务器
部署测试服务器并连接到该服务器
添加匹配（可选）
构建 WebGL 客户端并发布到 itch.io
在两个浏览器标签页中测试完整流程

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

使用编码智能体。 将 Claude Code、Cursor 或其他智能体连接到 Edgegap MCP 服务器及其智能体技能。智能体负责编辑您的项目、构建并容器化服务器、部署服务器并编写匹配代码。您只需在 Unity、Edgegap 控制面板和 itch.io 中点击操作，并进行游戏测试。
手动操作。 以下每个步骤在没有智能体的情况下也同样适用。

我们使用 Edgegap 的 Mirror WebGL 示例，该示例基于 Mirror 的 Tanks 示例和 Unity 6.3 LTS 构建。任何带有 WebSocket 传输层的 Unity 游戏都以相同的方式运行。

与工程师联系

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

分步指南

详细集成步骤

1. 开始之前

一个免费的 Edgegap 账户。请验证您的电子邮件。测试无需信用卡。
安装了 Linux 和 Web 构建模块的 Unity 引擎。 Edgegap 建议使用 LTS 版本。
- 从 Unity Hub 添加以下模块：Linux Build Support (Mono)、Linux Build Support (IL2CPP)、Linux Dedicated Server Build Support 以及 Web Build Support。添加后请重启 Unity。
- 该示例使用 Unity 6.3 LTS。在 Windows 上，首次针对 Linux 进行构建时，Unity 6 可能还会要求安装 Linux 工具链包（com.unity.toolchain.win-x86_64-linux）。
具有 WebSocket 传输协议的网络代码，可在 localhost 上运行。 我们推荐使用 Mirror 及其 SimpleWebTransport：其 WebGL 路径已通过 Edgegap 匹配系统进行端到端验证。要从我们的示例开始，请下载或克隆 Mirror WebGL 示例。
一个正在运行的容器化工具。 我们推荐在构建时已安装并运行的 Docker Desktop。
对于 Agent 路径：需要一个 Edgegap API 令牌，可从 Dashboard → User Settings → Tokens 获取。该令牌适用于整个组织，因此请像对待密码一样妥善保管：切勿将其放入您的项目、游戏客户端或聊天中。

Git： Unity 需要在您的 PATH 环境变量中配置 Git 客户端（2.14.0 或更高版本），以从 Git URL 安装软件包（例如 Edgegap SDK）。macOS 通常已自带（Xcode 命令行工具）；在 Windows 上，请安装 Git。

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

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

Edgegap MCP 服务器允许您的 Agent 在您的账户上创建应用和版本、部署服务器、读取日志并生成配对（matchmaker）配置。Agent 技能为其提供了经过测试的 Unity 工作流，包括 WebGL、C# 模板、Dockerfile 以及已知的避坑指南。

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 和其他支持发送标头（headers）的客户端：添加 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 应用。”

返回空列表是正常的。关于令牌的错误通常意味着标头被错误解析为了 token token ...。

3. 让您的游戏适配浏览器和专属服务器

在 Edgegap 上，没有玩家作为主机主持比赛。无头专用服务器拥有该游戏、自行启动、监听固定端口并在比赛结束时停止。对于网页浏览器游戏，该端口使用 WebSockets 通信。

连接工作原理：

服务器在固定端口运行普通 WebSockets (ws)，对于 Mirror 的 SimpleWebTransport 则是 7778。它不需要证书：在服务器上保持关闭 SSL。
Edgegap 的 TLS 升级在其前面添加了安全层，并带有服务器主机名的证书。
客户端使用 wss:// 连接到部署的主机名（不能是其 IP，否则证书检查会失败）及其外部端口。

使用您的智能体：

“加载 edgegap-unity 技能并将此项目设置为专用服务器 WebGL 游戏：7778 上的 SimpleWebTransport，服务器上关闭 SSL，客户端上使用 wss，服务器构建在 0.0.0.0 上无头启动，客户端连接时生成玩家，并在比赛结束时服务器自动停止。安装 Edgegap SDK 3.5.5，添加服务器生命周期和匹配客户端脚本以及 Mirror 适配器和 link.xml。然后检查它在一个服务器和一个客户端的情况下是否仍能在本地正常运行。”

手动操作，在 Mirror 上：

在 NetworkManager 上，将 KCP Transport 替换为 Simple Web Transport，端口设为 7778。将 Headless Start Mode 设置为 Auto Start Server。
安装 Edgegap SDK：在 Window → Package Manager 中，选择 +，然后选择 Add package from git URL，并粘贴 https://github.com/edgegap/sdk-unity-sessions-matchmaker-server-browser.git#3.5.6。需要 3.5.5 或更高版本：较旧的版本会导致 WebGL 构建失败。
使用 link.xml 文件在 IL2CPP 构建中保留 SDK 的数据类（示例在 Assets/EdgegapMatchmaking 中包含一个）。
在服务器构建中，仅启动服务器，切勿作为主机启动，并在客户端连接时生成玩家。在服务器上设置 Application.targetFrameRate（30 到 60），否则无头构建会导致单个 CPU 核心占用率达到 100%。

其他网络代码：Fish-Networking 的 Bayou 传输方式相同（参见 Fish-Networking）。Netcode for GameObjects 可以使用带 WebSockets 的 Unity Transport，但该路径尚未在 Edgegap 上进行验证：请尽早进行测试。

首先在本地测试：一个编辑器作为服务器，另一个作为客户端。切勿容器化在 localhost 上无法运行的游戏。

4. 构建并容器化您的服务器

Edgegap 在容器中运行您的 Linux 服务器构建。可以使用任一选项，或两者兼用。

选项 A：适用于 Unity 的 Edgegap 自动化游戏服务器构建工具插件。

在 Window → Package Manager 中，选择 +，然后选择 Add package from git URL，并粘贴 https://github.com/edgegap/buildtool-unity-plugin.git。如果您的 Mirror 版本已包含该插件（Assets/Mirror/Hosting/Edgegap），请跳过此步骤：重复安装会导致其脚本冲突。
打开 Tools → Edgegap Server Hosting，登录，并在 Connect your Edgegap Account 下粘贴系统提供的令牌。选择 Validate Token。
选择 Build Server，然后在 Docker 运行的情况下，选择 Validate 和 Containerize with Docker。
选择 Upload Image and Create App Version。在浏览器中设置端口：7778，协议 WS，名称 gameport，并开启 TLS Upgrade。插件会预填名为“Game Port”的 7770/UDP：请将这三项全部更改。提交。

选项 B：询问您的代理（Agent）。

“构建 Linux 专用服务器，使用适用于 linux/amd64 的 edgegap-unity Dockerfile 将其容器化，添加新标签推送到我的 Edgegap Container Registry，然后创建应用程序和应用版本，端口为 7778，协议为 WS，名称为 gameport，并开启 TLS Upgrade。”

代理会要求您自行运行 docker login registry.edgegap.com，并使用来自容器注册表页面的用户名和令牌，以确保这些凭据不会出现在聊天中。请确保应用版本已设置注册表凭据：如果没有凭据，部署将失败并提示“Unable to pull image from registry”。

每次构建都使用新的镜像标签，切勿使用 latest。

5. 部署测试服务器并连接

在添加配对功能之前，先手动启动一台服务器以验证镜像、端口以及 TLS Upgrade 是否正常工作。以下任意方式均可：

通过插件：选择您的应用和版本，然后选择 Deploy to Cloud。
通过控制面板：在 Edgegap 控制面板中打开您的应用版本，选择 Deploy，选择靠近您的位置并进行部署。
通过您的代理：“在我附近部署最新的 Edgegap 版本，等待其就绪，检查 WebSocket 端口是否响应 HTTP 101，向我展示日志，并提供主机名和外部端口。”

部署处于 Ready 状态后，复制其 Host URL 和 External Port。在客户端的 NetworkManager 中，将 Network Address 设置为该 Host URL，将 Simple Web Transport 客户端设置为在该 External Port 上使用 wss，然后点击播放并选择 Client。外部端口在每次部署时都会改变，因此每次都需要重新查看。

如果服务器日志显示 First bytes from client was not 'GET' for handshake, instead was 16-03-01，则说明该端口上的 TLS Upgrade 未开启：请在新应用版本中将其开启。

测试完成后停止部署（在插件中使用 Stop Last Deployment，或告知您的代理）。免费层级一次只能运行一个部署，遗留的测试服务器会阻止配对。

6. 添加匹配功能

Edgegap 的撮合服务是一项托管服务：玩家发送票证，该服务会根据您的规则（比赛规模、队伍、技能等级、模式）将他们分组，在他们附近部署您的服务器，并将地址返回给每个客户端。

网页游戏的两个规则：

无延迟规则。浏览器无法发送桌面游戏所使用的延迟 Ping。撮合系统会根据玩家的地理位置来放置服务器。
列出您的来源（Origin）。将提供您游戏服务的每个网址都添加到 allowed_cors_origins 中，否则浏览器将阻止撮合系统的响应。对于本地测试和 itch.io：http://localhost:8080、https://YOUR-NAME.itch.io 和 https://html-classic.itch.zone。

使用您的智能体：

“为我的 WebGL 应用版本生成一个 Edgegap 撮合配置：一支 2 到 4 名玩家的队伍，无延迟规则，单人玩家在 20 秒后分配到服务器，并允许这些来源：http://localhost:8080、https://YOUR-NAME.itch.io、https://html-classic.itch.zone。将其保存为 matchmaker-config.json。”

示例中还包含一个可随时编辑的 matchmaker-config.json：将 application.name 和 application.version 设置为您的应用版本。

然后，在控制面板中（此步骤没有 API）：

打开 Matchmaker 并选择 Create Matchmaker。
为其命名，上传 matchmaker-config.json，然后选择 Create and Start。
当状态变为 ONLINE 时，复制 API URL 和 Auth Token。Auth Token 可以安全地随游戏客户端一起发布：它不会提供对您 Edgegap 账户的访问权限。

回到 Unity：在示例中，激活 MirrorTanks 场景中的 EdgegapMatchmaking 对象，并在 TanksMatchmakingClient 上设置 Base URL 和 Auth Token。或者询问您的智能体：“将撮合 API URL 和 Auth Token 设置在关闭延迟信标的匹配客户端上，将我的 Play 按钮关联到 FindMatch，然后重新构建并推送服务器并创建新的应用版本。”

当您发布新的服务器构建时，请在撮合配置中更新 application.version（停止、编辑、启动），否则比赛将继续部署旧构建。

7. 构建 WebGL 客户端并将其发布到 itch.io

在 Player Settings → Publishing Settings 中，将 Compression Format 设置为 Gzip 并开启 Decompression Fallback，以便构建能够在 itch.io 等托管平台上加载。
在 File → Build Profiles 中，选择 Web，然后点击 Build。或者让您的智能体运行该技能的 WebGL 客户端构建。
要在本地进行测试，请从允许的源提供构建文件夹服务，例如 python -m http.server 8080 --bind 127.0.0.1，然后打开 http://localhost:8080。
要发布，请将构建文件夹压缩为 zip 文件。在 itch.io 上，选择 Upload new project，将 Kind of project 设置为 HTML，上传 zip 文件并勾选 This file will be played in the browser。保存后打开该页面。

您的 itch.io 页面源必须包含在配对系统的 allowed_cors_origins 中（步骤 6）。

8. 在两个浏览器标签页中测试完整闭环

确保没有正在运行的测试部署。
在本地或 itch.io 上，用两个浏览器标签页或窗口打开您的游戏。点击之前将每个窗口置于最前：后台标签页会降低 Unity WebGL 的运行速度。
在两边都选择Find Match。状态会从搜索中变为找到比赛，再到分配主机，然后两个标签页都会连接到同一个服务器。
离开比赛。示例服务器会在最后一名玩家离开 30 秒后停止部署，或者在无人加入 2 分钟后停止。这种自动停止机制可以在无人玩游戏时将您的账单保持为零。

在免费层中，匹配器在每次启动 3 小时后停止（从仪表板重新启动它），部署在 60 分钟后停止，且一次只运行一个部署。

后续步骤

也面向桌面端或移动端构建？请参阅 Unity Engine 和 Mirror。开发另一款网页游戏？请参阅针对 Godot Web 导出的 Godot Engine，或查看采用 Manus 构建游戏的 Manus AI。

准备上线？让您的代理运行 edgegap-launch 技能的检查清单：版本发布、重启策略、最长持续时间、成本控制。

遇到问题？让您的代理加载 edgegap-troubleshoot，或在 Edgegap Discord 上向我们的团队和其他工作室咨询。

常见问题

关于在 Edgegap 专属服务器上托管 Unity WebGL 多人游戏的常见问题。

Unity WebGL 游戏可以连接到专用服务器吗？

是的，通过 WebSockets。浏览器无法打开 UDP 连接，因此请使用 WebSocket 传输协议，例如 Mirror 的 SimpleWebTransport。服务器作为 Linux 专用服务器版本运行，浏览器使用 wss:// 连接到该服务器。

我的游戏服务器需要 SSL 证书吗？

不。在服务器的 WebSocket 端口上开启 TLS Upgrade：Edgegap 会处理该服务器主机名的证书。您的服务器运行普通的 WebSockets，而客户端使用 wss:// 连接到该主机名。

为什么我的 WebGL 游戏无法连接到撮合服务器？

浏览器会阻止来自配对程序不允许的来源的请求。请将提供您游戏服务的所有地址（例如 http://localhost:8080 和您的 itch.io 页面）添加到配对程序配置中的 allowed_cors_origins 中。

哪种网络代码（netcode）最适合 Unity WebGL 多人游戏？

采用 SimpleWebTransport 的 Mirror 是经过 Edgegap 匹配器端到端验证的路径，Edgegap 的示例也使用了它。Fish-Networking 的 Bayou 传输方式也可以使用。Netcode for GameObjects 可以使用 WebSocket，但建议尽早测试。