了解Edgegap的工作原理

對局配對

和

托管与编排

整合

Unity Matchmaking SDK

部署至 Edgegap

已发布

2026/7/17

最近一次准确性审核

2026/10/16

Unity 對局配對 SDK：如何使用 Edgegap 为您的 Unity 多人游戏添加對局配對

本指南向您展示如何为已在 Edgegap 专用游戏服务器上运行的 Unity 多人游戏添加匹配功能：玩家选择寻找比赛 (Find Match)，根据您的规则进行分组，并连接到 Edgegap 在他们附近启动的服务器。

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

Edgegap 的匹配器是一项托管服务：无需编写或运行后端。它适用于任何网络代码 (netcode)。只有将玩家连接到所分配服务器的那行代码取决于您的网络方案。

本指南涵盖：

为您的游戏准备一个正常工作的 Edgegap 应用版本
将您的编码智能体连接到 Edgegap（可选）
安装 Edgegap 的 Unity SDK
将匹配客户端添加到您的游戏中
创建您的匹配器
选择您的匹配规则
使用两名玩家进行测试

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

使用编码智能体。将 Claude Code、Cursor 或其他智能体连接到 Edgegap MCP 服务器及其智能体技能。智能体会添加匹配客户端和适用于您网络代码的代码，生成匹配器配置并检查结果。您只需在 Unity 和 Edgegap 控制面板中进行点击操作，并进行游玩测试。
手动操作。从 SDK 现成的示例开始，以下每个步骤在没有智能体的情况下也同样适用。

在此，我们使用 Mirror 的 Tanks 示例。任何 Unity 网络代码的运作方式都是相同的。

与工程师联系

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

分步指南

详细集成步骤

1. 开始之前

一个免费的 Edgegap 账户。请验证您的电子邮箱。测试无需信用卡。
一个运行正常的 Edgegap 游戏服务器应用版本：即您至少部署并成功加入过一次的服务器。匹配会为每场对局部署所请求的版本，因此需要一个功能完备的容器化游戏服务器来实现端到端运行。如果您目前还没有，请参考我们的指南：
您的服务器在对局结束时会自动停止，因此您只需在玩家游玩时付费。上述指南对此均有涵盖。
针对代理方式：需要一个 Edgegap API 令牌，可从控制面板 → 用户设置 → 令牌中获取。该令牌适用于整个组织，请将其视同密码：切勿将其放入您的项目、游戏客户端或聊天中。

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

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

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

Edgegap MCP 服务器允许您的 Agent 在您的账户上创建应用程序和版本、部署服务器、读取日志并生成撮合系统（matchmaker）配置。Agent 技能则为其提供了经过测试的 Unity 撮合客户端、适用于您的网络代码（netcode）的代码以及已知的注意事项。

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. 安装 Edgegap 的 Unity SDK

以下是我们关于 Edgegap 的 Unity 匹配 SDK 的视频教程，使用 Mirror 的 Tanks 示例，涵盖从安装到两名玩家匹配成功的过程：

Edgegap 的 Unity SDK 是匹配软件包。它与构建和部署服务器的插件是分开的。

使用您的代理：

“加载 edgegap-unity 技能并在该项目中安装 Edgegap Unity SDK，版本为 3.5.5 或更高版本。”

正在使用 FishNet 或 PurrNet？在此步骤和下一步中，请让您的代理改为加载 edgegap-fishnet 或 edgegap-purrnet。

手动操作：

在 Unity 中，选择 Window → Package Management → Package Manager，选择 +，然后选择 Add package from git URL，粘贴 https://github.com/edgegap/sdk-unity-sessions-matchmaker-server-browser.git 并选择 Add。
在 SDK 的 Samples 选项卡中，导入 Matchmaking - Simple Example。您只需要这一个。

该 SDK 会测量每个玩家到 Edgegap 信标的 ping 值，创建匹配票证，并等待分配服务器。它特意留下了一个空白：将玩家连接到该服务器的代码行，因为这取决于您的网络代码。步骤 4 将填补这一空白。

4. 将匹配客户端添加到您的游戏中

使用您的智能体：

“将 edgegap-unity 撮合客户端和服务器生命周期脚本添加到我的网络场景中，为我的 netcode 填入 netcode 适配器，并将我的 Play 按钮关联到 FindMatch。撮合器 URL 和令牌暂时留空。”

该智能体会添加一个可立即使用的 Find Match 面板、针对仍在启动中的服务器的连接重试机制，以及在对局结束时停止对应服务器的代码。如果您的服务器镜像发生更改，它会重新构建镜像并创建新的应用版本。

手动操作，可通过适用于任何 AI 编码助手的两个提示词，或使用您自己的代码完成：

提示词 1，审查您的项目（只读）：

“只读，不修改代码。我的 Unity 项目使用了一个 netcode 框架，我现在正在添加 Edgegap 撮合功能，该功能将在运行时为我的客户端提供服务器地址（FQDN）和外部端口。请查找并告诉我：1) 启动客户端连接到服务器的方法、所在文件和行号，以及触发它的条件；2) 在连接前设置服务器地址和端口的位置：确切的属性或字段名称、正在使用的 transport，以及文件和行号。不要修改任何内容。”

提示词 2，添加连接：

“在 Edgegap 示例 MatchmakingClientHandler.cs 中，找到票证状态为 HOST_ASSIGNED 时运行的代码块。该代码块目前仅记录分配信息。请将其替换为通过我的 netcode 连接到所分配服务器的代码：将分配的 FQDN 设置为网络地址，将 gameport 的外部端口转换为我的 transport 所期望的类型并设置在 transport 上，然后启动客户端。请使用上一步中查找到的内容。”

然后，在您的游戏场景中，选择 GameObject → Create Empty，将其命名为 對局配對，并添加 Matchmaking Client Handler 组件。暂时将 Base URL 和 Auth Token 留空：它们将在步骤 5 中提供。

使用 Mirror 时，连接会将 NetworkManager.singleton.networkAddress 设置为 FQDN，在活动 transport 上设置端口，并调用 StartClient()。其他 netcode 对这三项操作有各自的命名。

5. 创建您的撮合器

在控制台中打开 Matchmaker，选择创建匹配器 (Create Matchmaker) 并命名，例如 mygame-dev。
选择一个配置：
- 最快方式：在配置列表中选择简单示例 (Simple Example)（包含的内容）：一支由两名玩家组成的队伍，按延迟分组。它会自动填充您最新的应用和版本：请检查是否符合您的需求。
- 通过智能助手：“为我的应用版本生成 Edgegap 匹配器配置：一支 2 到 4 名玩家的队伍，并让单人玩家在 20 秒后获取服务器，以便我可以单独测试。将其保存为 matchmaker-config.json。” 然后上传该文件。
选择创建并启动 (Create and Start)。出现服务器镜像未缓存的警告对于测试来说没有问题：选择继续 (Continue)。匹配器启动需要几分钟时间，其地址响应最多还需要 5 分钟。
当状态为 ONLINE 时，将 API URL 和 Auth Token 复制到您的匹配组件中（Base URL 和 Auth Token），或者提供给您的智能助手。

Auth Token 仅提供对您匹配器的访问权限，无法访问您帐户中的其他任何内容，因此在游戏客户端中是安全的。在生产环境中，许多工作室会让玩家先登录自己的后端以创建票据，这样他们就可以在匹配前检查身份和封禁状态。

6. 选择您的匹配规则

使用您的首个配置运行第 7 步测试，然后根据您的游戏量身定制规则。每条规则根据一个维度对玩家进行分组：

对局规模：队伍数量以及每队的玩家人数。
延迟：玩家 ping Edgegap 的信标，并与距离他们较近的玩家分在一组。随后 Edgegap 会在该组附近启动服务器。
技术水平、模式、地图或区域：数值范围或玩家必须共有的某个值。
扩展规则：在等待一段时间后放宽规则，例如在 20 秒后接受更少的玩家，之后票证在 30 秒时过期，从而避免有人无限期等待。

需要记住的两条规则：

除对局规模外，每条规则都需要在每位玩家的票证中包含一个同名的匹配值。缺少或多余的值将被拒绝 (HTTP 400)。添加规则时请通知您的代理，它会同时更新双方。
WebGL 游戏：浏览器无法 ping 信标，因此请忽略延迟规则，并在 allowed_cors_origins 下列出托管您游戏的站点。请使用 SDK 3.5.5 或更高版本。

合作、对抗、社交和自定义大厅游戏以及补位（玩家加入正在进行的对局）的现成配置，均可在匹配系统文档中找到。更改正在运行的匹配系统的配置会使其重新加载并清除正在等待的票证。发布新的服务器版本时，请更新 application.version（停止、编辑、启动），否则比赛将继续部署旧版本。