Unity - 入门指南

通过实践学习，并在 Edgegap 上部署你的第一个专用服务器。本指南结束时，你将免费使用 Edgegap 部署一个专用服务器。

✔️ 准备工作

对你的服务器构建有信心吗？ 跳转到 Unity 或高级功能查看更多内容。

⚙️ 1. 连接账户

☑️ 登录并确认 Unity 控制台中没有与 Edgegap 插件相关的新错误。

✅ 你现在可以继续下一步了。

故障排除和常见问题

!Success: 400 BAD REQUEST - POST | https://api.edgegap.com/v1/wizard/init-quick-start - {"message": "浏览器（或代理）发送了一个此服务器无法理解的请求。"}

如果你是通过复制 ZIP 文件安装的，或者使用了一个以这种方式复制了插件的示例项目，你需要手动安装包依赖，包括 Newtonsoft JSON 库，参见官方插件仓库.
如非上述情况，请通过社区 Discord 联系我们以获得帮助。

🔧 2. 构建游戏服务器

无论你使用的是 Windows、Mac 还是 Linux 机器， 你都需要为 Linux 运行时构建服务器，因为如今大多数云服务提供商（包括 Edgegap）都运行在 Linux 上。别担心，使用我们的插件完成这一步不需要任何 Linux 知识。

☑️ 确认你已安装所需的 Unity Linux 构建工具。

☑️ 编辑构建设置以 确保所有必需的游戏场景都已包含.

高级 Unity 用户 - 可选地更改 Unity 构建设置。注意！这可能会破坏你的构建。

☑️ 可选：从 Edgegap 服务器托管菜单向你的初始服务器场景添加用于端口验证和环境初始化的特定 netcode 脚本（在层级窗口中右键 / ➕ ）。

完成步骤 Unity后，如果你的 netcode 地址或端口与 Edgegap 应用版本端口映射配置进行的内部负载测试，限制每秒请求数。

服务器构建应在你的 netcode 传输中使用地址 0.0.0.0 和端口 7777 。如果你自定义了端口，请在你应用和版本时指定相同的值 Unity.

☑️ 配置满意后，点击 构建服务器，等待流程完成，并确认 Unity 控制台中没有新错误。完成此步骤后，你的项目根目录中将出现一个 新文件夹 - Builds/EdgegapServer/ServerBuild .

✅ 你现在可以继续下一步了。

故障排除和常见问题

Unity：唯一受支持的独立目标是带有 OpenXR 的 Windows x64 和 OSX。

在构建服务器之前，请打开 Packages 并禁用 OpenXR。
OpenXR 插件仅供客户端使用，与 Linux 服务器构建不兼容。将其从服务器构建中排除不会损失任何功能。

🐋 3. 容器化服务器

在开发团队中工作意味着要共享代码。当出现问题时，最不想听到的话就是“在我机器上能跑”。游戏服务器必须能在任何机器上可靠运行，因为成功的游戏服务器会在全球成千上万台服务器机器上运行。

为了让你的服务器更可靠，我们使用 Docker——一种虚拟化软件，可确保你的所有服务器代码依赖项，直到操作系统层面，在服务器启动于何处、如何启动的情况下都始终完全一致。

☑️ 现在先点击验证按钮，以确保你已完成开发者工具.

☑️ 你可以配置以下选项（或保持默认值）：

构建路径 是指服务器构建产物的相对路径，暂时保持默认即可。

将构建保留在项目文件夹内，Docker 只接受相对于项目根目录的构建路径。

镜像名称 是你自定义的唯一标识，用于在发布前标记你的服务器构建。
- 通常这会包含你的游戏名称，例如“my-game-server”。
镜像标签 是指向你镜像特定版本的标识符。
- “构建产物”一词有时也用于指代镜像的特定版本。
- 使用时间戳作为标签是个不错的选择，例如 2024.01.30-16.23.00-UTC .
Dockerfile 路径 可用于自定义镜像的构建方案。
- 我们建议暂时保留默认设置，你稍后可以在第 Unity.
可选的 docker 构建参数 中了解更多细节，以进一步指导 Docker 处理更细微的设置。
- 我们建议暂时保留默认设置，你稍后可以在 Docker 文档中阅读更多内容.

☑️ 配置满意后，点击 使用 Docker 容器化，等待流程完成，并确认 Unity 控制台中没有新错误。完成此步骤后，你的项目根目录中将出现一个 新镜像出现在你的本地机器上。你可以在 Docker Desktop 的 Images 选项卡下的 Local（默认）中验证，或者在 docker CLI 中运行 docker images .

✅ 你现在可以继续下一步了。

故障排除和常见问题

/bin/bash: 未找到 docker 命令 ，或者 找不到 Packages\com.edgegap.unity-servers-plugin\Editor

首先，确保你已完成开发者工具.
确认你已验证 Edgegap 账户，你应该已通过电子邮件收到验证链接。
更新 Docker Desktop 后，某些设置可能已重置。请尝试进入 Docker Desktop 设置 / 高级，并在“Choose how to configure the installation of Docker’s CLI tools:”中选择“System (requires password)”。

docker build 需要恰好 1 个参数

请确认你的镜像标签不包含任何空白字符（空格、制表符）。重新输入镜像标签值可以确保你没有意外复制这些字符。

（HTTP 代码 400）unexpected - 无效的标签格式

这是一个 macOS Docker 4.33 版本中的已知问题，请考虑回退到 4.32 或升级到 4.35。

错误：解决失败：ubuntu:22.04：无法为 http://docker.io/library/ubuntu:22.04 解析源元数据：授权失败：无法获取 oauth 令牌

你是否位于中国？你的连接可能会被防火长城中断。请尝试手动运行 docker pull ubuntu:22.04 在命令行中（按 Win+R 打开命令行，然后输入 cmd 并按 Enter）。

System.IndexOutOfRangeException：索引超出了数组边界。

如果你通过下载 ZIP 安装了我们的 Unity 快速入门插件，你的 Unity Editor 缓存可能已损坏。请尝试删除插件副本，并使用 git URL 或 Unity Asset Store 重新安装。你将不再需要 Newtonsoft.JSON 包，因为它会与其他源代码一起自动包含。

我的 docker 镜像大小很大（超过 1GB）/ 很小（低于 100mb），这样可以吗？

在某些情况下这可能没问题，只要你能运行服务器并成功连接（参见 Unity）。如果不是这样，请考虑检查你的构建选项，将其重置为默认值，并逐步添加选项以观察它们如何影响构建大小。另请参见 Unity.

我遇到了本文档中未提及的其他问题。

首先，请尝试更新你的 Edgegap 插件，因为我们可能已经发布了修复。如果这没有帮助，请通过我们的社区 Discord 联系我们，我们会立即与你一起调查。

🧪 4. 在本地测试服务器

☑️ 你可以配置以下选项（或保持默认值）：

服务器镜像标签 来自上一步。
- 默认为你使用插件构建的最后一个标签。
可选的 docker run 参数 可用于暴露多个端口，或在 macOS 机器上运行你的镜像。
- 如果需要，你可以为容器发布多个端口，只需为每个端口添加参数 -p {internal port}/{protocol} ，例如 -p 8080/tcp -p 7777/udp 以发布并映射你的服务器端口 8080 到一个随机的外部端口用于 TCP 连接，以及服务器端口 7777 同时到一个随机的外部端口用于 UDP 连接。
- 在 Transport 或特定 netcode 设置中查找服务器端口配置。
- 如果你使用的是 ARM 架构的机器（macOS M1、M2、M3 等），你应该在可选的 docker 构建参数中看到此可选参数： --platform=linux/amd64 .

☑️ 配置满意后，点击 部署本地容器，等待流程完成，并确认 Unity 控制台中没有新错误。完成此步骤后将会 启动一个新容器 在你的开发机器上。

更多细节请参见 Docker Desktop / Containers，或 Docker CLI 命令 docker ps .

☑️ 现在是时候 将你的 Unity Editor 游戏客户端连接到本地 docker 容器 以验证你的服务器镜像是否正常工作。找到你的 netcode 客户端设置并输入：

localhost 或 0.0.0.0 （在大多数情况下等同）替代服务器 IP，
在 Docker Desktop / Containers / edgegap-server-test 中找到的随机外部端口值。

✅ 你现在可以继续下一步了。

故障排除和常见问题

我无法使用 Unity Editor 游戏客户端连接到本地 docker 容器。

首先，确保容器状态为 Up，而不是 Restarting 或 Exited，这表示存在运行时异常。如果你的容器未运行，请通过 Docker Desktop 的 Containers 选项卡（点击你的容器）查看日志，或使用 docker logs {container_id} --timestamps 通过 docker CLI。
接下来，请确认服务器构建中的 Network Manager 端口设置与 可选的 docker run 参数中发布的端口一致。如果不一致，请尝试重置或手动更改此输入字段的值，使其与 {container} 中的端口设置一致。请在你的 netcode 设置中找到协议。
最后，请确认你的 Unity Editor 游戏客户端 netcode 设置使用的是 可选的 docker run 参数 中发布的端口（见上方截图）。

（段错误）- core dumped

如果你使用的是 ARM 架构的机器（macOS M1、M2、M3 等），你应该在可选的 docker 构建参数中看到此可选参数： --platform=linux/amd64 。如果没有，请尝试重置此输入字段的值。

在 SceneObjects 中未找到 SceneId 9120233082191360994。

这可能意味着你尝试加载的场景未正确包含在构建中，这是旧版插件中的已知问题。为解决此问题，请尝试更新你的 netcode 集成版本，或更新你的 Edgegap 插件.

http2：服务器：从客户端读取 preface 时出错 //./pipe/docker_engine：文件已被关闭

这是一个这是 Windows 版 Docker Desktop 较旧版本中的已知问题。请更新你的 Docker Desktop 应用并再次尝试容器化。

Curl 错误 35：证书握手失败。致命错误。UnityTls 错误代码：7

此错误表示根 SSL 证书验证问题，这是旧版插件中的已知问题。为解决此问题，请尝试更新你的 Edgegap 插件.

☁️ 5. 上传到 Edgegap

☑️ 你可以配置以下选项（或保持默认值）：

应用名称 在 Edgegap 上可以与你的镜像名称一致，也可以自定义。
- 我们暂时选择复制你的镜像名称。
应用版本 在 Edgegap 上可以与你的标签一致，也可以自定义。
- 使用时间戳作为应用版本名称是个不错的选择，例如 2024.01.30-16.50.20-UTC .
- 多个应用版本可以指向同一个镜像标签，例如 v1.1.0 和 dev .
- 了解更多关于应用和版本的信息。
服务器镜像名称 来自步骤 Unity.
服务器镜像标签 来自步骤 Unity.

在你机器上的 Docker Desktop / Images.

☑️ 配置满意后，点击 上传镜像并创建应用版本，等待流程完成，并确认 Unity 控制台中没有新错误。

☑️ 你将被带到我们的仪表板，你可以在其中配置可选设置。完成此步骤将会导致创建一个新的应用版本，并且你的构建产物被标记并上传到 Edgegap 的容器注册表.

☑️ 现在系统会提示你为新应用版本定义端口。请确保设置的服务器端口值与步骤 Unity 中 Transport 或特定 netcode 设置里的端口一致。

✅ 你现在可以继续下一步了。

🚀 6. 部署到云端

☑️ 现在我们将执行最后测试，并 将你的 Unity Editor 游戏客户端连接到云端部署。从部署的以下信息输入游戏客户端连接细节：

主机 URL 指向服务器 IP，通常在 NetworkManager 组件中。
外部端口 映射到服务器内部监听端口，通常在 Transport 组件中。

故障排除和常见问题

无法将客户端连接到服务器 - 请求超时。 , 请求超时 , ConnectionFailed ，或者 端口验证失败

首先，确保部署处于 Ready 状态，并且你的部署日志中没有运行时异常或错误。如果你的部署已停止，请在我们的仪表板.
如果你使用的是 Mirror netcode，你需要在你的 “Auto Start Server” 中选择 NetworkManager ，然后重新构建、推送并重新部署你的服务器。
如果你使用的是 FishNet netcode，你需要在你的中启用 “Start on Headless” ServerManager，然后重新构建、推送并重新部署你的服务器。
如果你使用的是 Photon Fusion 2 netcode，请确保你的服务器正在传递部署公共 IP、外部端口以及 roomCode 到服务器，并且客户端中的相同 room code 位于 “NeworkRunner.StartGame” 参数 StartGameArgs。部署 ID（例如 b63e6003b19f）是一个不错的选择，因为它在全球范围内唯一，并且客户端可以通过匹配器和深入了解.
接下来，请确认你服务器构建中的 netcode 设置里的端口设置与应用版本中的内部端口一致。你可以通过编辑应用版本来更改端口映射，而无需重新构建。在你的 netcode 集成中找到协议。
请确保你的游戏客户端连接到 外部端口 ，该端口显示在你的部署详情页面上；由于安全原因，此值始终会随机化。
如果你在 netcode 集成中使用的是安全 WebSocket（WSS）协议，请确保你的应用版本 WSS 端口的端口配置已启用 TLS 升级。
你是否位于中国并且正在使用智能舰队？你的连接可能会被防火长城阻止。请考虑在你的机群中添加一个位于中国的服务器，或使用 VPN 连接。

我的部署停止/重启了，我再也无法访问它的日志。

如果服务器进程因异常崩溃，我们的系统会尝试自动重启服务器。建议本地测试你的服务器以找出根本原因。
我们只会在部署期间保留日志；如果你想在部署停止后检查日志，请集成第三方日志存储.
参见部署以找出导致部署停止的所有原因。

我的部署在 X 分钟后自动停止了。

免费套餐部署有 60 分钟限制，请考虑升级你的账户。
根据我们的服务器清理策略、为了基础设施维护，以及防止在部署未正确关闭时产生意外费用，所有部署在运行 24 小时后都会被终止。对于长时间运行的服务器，请考虑使用私有舰队使用持久化.
参见部署以找出导致部署停止的所有原因。

我的部署已就绪，但之后几分钟仍无法连接。

一旦部署处于 Ready 状态，你的游戏引擎初始化就会开始。此过程可能需要几秒到几分钟不等，在此期间服务器不会接受玩家连接。
请考虑优化你的服务器初始化以缩短这段时间。
游戏客户端应每隔 1 秒重试连接一小段时间（取决于你的初始化时长），之后应返回匹配系统。
请考虑添加一个加载场景，这样服务器可以与客户端同时执行初始化（以及在 Unreal Engine 中进行旅行/切换场景），同时同步双方状态。

我的 Meta Quest 设备报错 HTTP 0：无法解析目标主机 .

在为 Android 目标构建 Unity 应用时，你的 Internet Access 权限可能会在输出的 APK 客户端构建产物中被自动移除。
重新添加权限（之后需要重新构建客户端）：
- Project Settings / OpenXR / ⚙️ Meta Quest Support / Force Remove Internet Permissions（取消勾选）。
- Player Settings / Internet Access（设置为 require）。

如果玩家离开我的部署，会发生什么？

默认情况下，服务器不会拒绝玩家连接。玩家身份验证由你的开发者决定，因为可以使用许多不同的方法和玩家身份验证提供商。
游戏客户端可能会在本地存储连接信息，以便在客户端意外崩溃时尝试重新连接。
若要允许玩家加入进行中的游戏，请考虑使用深入了解或会话.

我的服务器在就绪后显示 100% CPU 使用率。

这可能不是问题，因为游戏引擎在服务器初始化期间往往会执行 CPU 密集型操作。如果从部署开始后 2-3 分钟 CPU 使用率仍未下降，你可能需要优化服务器或增加应用版本资源。
降低 tick rate 会影响 CPU 使用率，因为服务器执行的消息操作更少。
如果你使用的是 Mirror netcode，你需要在你的 “Auto Start Server” 中选择 NetworkManager ，然后重新构建、推送并重新部署你的服务器。
如果你使用的是 FishNet netcode，你需要在你的中启用 “Start on Headless” ServerManager，然后重新构建、推送并重新部署你的服务器。
在免费套餐中，你最多只能使用 1.5 vCPU 和 3GB 内存（RAM）。
你可以在创建新应用版本时增加分配的资源。你可以在我们的仪表板中复制你的应用版本并按需调整这些值，而无需重新构建服务器或镜像。

我的部署不断重启并显示错误 OOM kill

这是由于超出分配的内存量导致的。请考虑使用对象池、压缩或移除场景中不需要的对象来优化内存使用。
确保你的项目正在加载包含你的 NetworkManager 的默认场景，并且该场景已包含在 Unity 的 Build Settings 中。
在免费套餐中，你最多只能使用 1.5 vCPU 和 3GB 内存（RAM）。
你可以在创建新应用版本时增加分配的资源。你可以在我们的仪表板中复制你的应用版本并按需调整这些值，而无需重新构建服务器或镜像。

有时，我服务器的内存（RAM）使用会突然飙升到很高的值，这有问题吗？

只要你没有超过分配的应用版本内存量，这就不是问题。
超过分配的应用版本内存量会导致 OOM kill （见上文）。

我的服务器性能会受到同一机器上运行的其他服务器影响吗？

不会，我们的平台确保分配的资源不会被其他工作室或共享基础设施上的其他服务器使用。在 Edgegap 上，不会有“邻居噪音”问题。

👉 下一步

停止部署

了解各种方法以停止部署，当比赛结束且玩家离开后。

对于优雅关闭，我们强烈建议在你的游戏中实现自停止 API：

Unity C# 自停止 API 代码示例

using System;
using System.Collections;
using UnityEngine;
using UnityEngine.Networking;

public class EdgegapSelfStop : MonoBehaviour
{
    private const int MaxRetries = 2;
    private const int TimeoutSeconds = 30;
    private string url = Environment.GetEnvironmentVariable("ARBITRIUM_DELETE_URL");
    private string token = Environment.GetEnvironmentVariable("ARBITRIUM_DELETE_TOKEN");

    public void Run()
    {
        StartCoroutine(SendDeleteWithRetry());
    }

    private IEnumerator SendDeleteWithRetry()
    {
        if (string.IsNullOrEmpty(url))
        {
            Debug.LogError("Edgegap | ARBITRIUM_DELETE_URL 未设置。");
            yield break;
        }

        if (string.IsNullOrEmpty(token))
        {
            Debug.LogError("Edgegap | ARBITRIUM_DELETE_TOKEN 未设置。");
            yield break;
        }

        int attempt = 0;

        while (attempt <= MaxRetries)
        {
            attempt++;

            using (UnityWebRequest request = UnityWebRequest.Delete(url))
            {
                request.timeout = TimeoutSeconds;
                request.SetRequestHeader("Authorization", token);

                yield return request.SendWebRequest();

                if (request.result == UnityWebRequest.Result.Success)
                {
                    Debug.Log("Edgegap | DELETE 请求成功。");
                    yield break;
                }

                Debug.LogWarning(
                    $"Edgegap | DELETE 第 {attempt} 次尝试失败。\n" +
                    $"Result: {request.result}, Error: {request.error}"
                );

                if (attempt == MaxRetries)
                {
                    Debug.LogError("Edgegap | 在所有重试后 DELETE 请求仍失败。");
                    yield break;
                }
            }
        }
    }
}

如果崩溃或内存耗尽，你的 Unity 服务器将自动重启。

注入变量

通过访问注入的环境变量，可以读取诸如部署 ID、服务器 IP 地址、服务器位置等有用信息。每个部署都会自动包含：

部署变量 - 由 Edgegap 自动提供，
匹配变量 - 在使用匹配,
应用版本变量 - 由你配置的自定义键值对。

通过检查 Edgegap 变量是否已设置来验证当前实例是游戏客户端还是服务器： ：

if (
  string.IsNullOrEmpty(Environment.GetEnvironmentVariable("ARBITRIUM_REQUEST_ID"))
)
{
  // 客户端代码
} else {
  // 服务器代码
}

会话

手动启动你的部署、粘贴 URL 和端口，对于正式运行的游戏来说远远不够。

阅读更多关于匹配 以在玩家上线时即时自动部署。

优化服务器构建

仅重新构建自上次构建以来发生变化的资源。

请考虑使用 Unity 的增量构建来加快构建时间。

请考虑使用 Unity 的增量构建来加快构建时间。

仅包含服务器运行绝对需要的内容。

将未使用的文件复制到镜像中会导致镜像膨胀、上传更慢、缓存更慢，以及整体服务器启动更慢。查看 Docker 镜像优化建议.

禁用网格的静态批处理以减小镜像大小。

禁用静态批处理可加快构建、上传和部署。

压缩网格以减小镜像大小。

将网格压缩设置为 High 可加快构建、上传和部署。
顶点压缩不会影响镜像大小。

实现资源的条件式延迟加载。

通过将纹理和网格设置为禁用 CPU 读写.
请考虑使用 Unity Addressables 用于客户端构建，以通过按需加载资源来加快构建和部署，或者在服务器构建中通过检查是否存在注入变量.

请考虑使用 多阶段 Docker 构建（链接）.

将大型服务器依赖拆分到单独镜像中，以便在多阶段构建中复用。Docker 会缓存每一层，并简单复用上一版本，除非明确指示，否则会跳过上传这部分，从而节省带宽以及等待上传完成的时间。
如果你不确定为什么某个 Dockerfile 命令会报错，请尝试在本地调试。在问题发生前创建一个新阶段（再添加一个 FROM 命令），使用 --target 指示构建过程在出问题的阶段停止，然后使用 docker exec -it {container} /bin/bash 进入容器内的交互式终端。之后，你可以在基础镜像中使用 shell 命令进一步排查（例如 top 在 ubuntu 上）。

自定义服务器镜像

对于因构建大小优化、额外依赖或更复杂启动流程而需要更多镜像控制的用户，我们也支持添加自定义 Dockerfile。你可以在步骤 Unity中可选地提供自定义 Dockerfile 路径。现在我们将分享一些“自己动手”的技巧和最佳实践。

在使用 WebSocket 或 HTTPS 请求时遇到问题吗？

如果你遇到 Curl 错误 35：证书握手失败。致命错误。UnityTls 错误代码：7 别灰心，这是旧版基础（FROM）镜像中包含已过期根证书的已知问题。你可以通过升级到更新的基础镜像版本来修复它（例如 ubuntu:22.04），并运行 update-ca-certificates ，请将其添加到你的 Dockerfile：
```
FROM ubuntu:22.04

RUN apt-get install -y ca-certificates && \\
    apt-get clean && \\
    update-ca-certificates
```

遇到瓶颈了吗？我们在我们的社区 Discord 中随时乐意提供帮助。

最后更新于 7天前

这有帮助吗？

hashtag✔️ 准备工作

hashtag⚙️ 1. 连接账户

hashtag🔧 2. 构建游戏服务器

hashtag🐋 3. 容器化服务器

hashtag🧪 4. 在本地测试服务器

hashtag☁️ 5. 上传到 Edgegap

hashtag🚀 6. 部署到云端

hashtag👉 下一步

hashtag停止部署

hashtag注入变量

hashtag会话

hashtag优化服务器构建

hashtag自定义服务器镜像

✔️ 准备工作

⚙️ 1. 连接账户

🔧 2. 构建游戏服务器

🐋 3. 容器化服务器

🧪 4. 在本地测试服务器

☁️ 5. 上传到 Edgegap

🚀 6. 部署到云端

👉 下一步

停止部署

注入变量

会话

优化服务器构建

自定义服务器镜像