For the complete documentation index, see llms.txt. This page is also available as Markdown.

网页游戏(JS/TS)- 入门

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

本指南使用一个最小化的 Node.js WebSocket 服务器模板,它适用于任何浏览器游戏客户端——Three.js、Babylon.js、PlayCanvas、Phaser,或你自己的引擎。使用 Colyseus 等框架构建的服务器,或运行在 Bun 和 Deno 上的服务器,都遵循相同步骤。

✔️ 准备工作

开始之前,请务必 在 Edgegap 创建一个免费账户 (无需信用卡)。你可以 之后邀请你的团队成员,即使他们还没有 Edgegap 账户。

在你的开发机器上配置一些基本内容:

安装 Node.js 22 或更高版本
  • 从官方来源安装 Node.js,我们建议使用最新的 LTS 版本。

  • 通过运行以下命令验证你的安装 node -v 在你的命令行中。

安装 Docker Desktop(或 Docker CLI)

对你的服务器构建很有把握? 跳转到 Web Games 或 高级功能 了解更多。

⚙️ 1. 连接账户

JavaScript 服务器不需要引擎插件。我们将使用你的命令行和我们的 控制面板 来构建、上传并部署你的服务器。

☑️ 登录我们的控制面板并打开 容器仓库。记下你的 项目名称 和 仓库凭据 (用户名和令牌),你将在接下来的步骤中用到它们。

☑️ 登录 Edgegap 的容器仓库 ,使用你的仓库项目名称、用户名和令牌通过 Docker 登录:

☑️ 确认你看到 登录成功 在你的命令行中。

✅ 现在你可以进行下一步。

🔧 2. 构建游戏服务器

无论你使用的是 Windows、Mac 还是 Linux 机器,你的 服务器都将在 Linux 运行时上运行,因为如今大多数云服务提供商(包括 Edgegap)都运行在 Linux 上。好消息是——JavaScript 是跨平台的,因此无需进行交叉编译,而且 Docker 会在下一步为 Linux 安装你的依赖。

☑️ 为你的服务器创建一个新文件夹,并包含两个文件。 这个最小模板接受 WebSocket 连接,并将每条消息转发给所有已连接的玩家。后续再用你的游戏逻辑替换这个转发逻辑。

Node.js 22.18+ 可直接运行 TypeScript 文件(会去除注解),无需构建步骤。

  1. 将 server.ts 模板复制到你的项目中(如果你还没有的话):

  2. 将 package.json 到你的项目中(或与现有文件合并)。

  3. 为你的编辑器安装类型定义:

  1. 将 server.js 模板复制到你的项目中(如果你还没有的话):

  2. 将 package.json 到你的项目中(或与现有文件合并)。

☑️ 安装依赖并在本地启动你的服务器:

☑️ 确认你看到 listening on 0.0.0.0:7777 和 在本地运行 ,然后使用以下命令停止你的服务器: Ctrl+C.

✅ 现在你可以进行下一步。

🐋 3. 容器化服务器

在一个开发者团队中工作意味着要共享代码。当出现问题时,您最不想听到的就是“在我的机器上可以运行”。游戏服务器必须能够在任何机器上可靠运行,因为成功的游戏服务器会在世界各地成千上万台服务器机器上运行。

为了帮助使您的服务器可靠,我们使用 Docker —— 一种虚拟化软件,确保您的所有服务器代码依赖项直到操作系统级别始终完全相同,无论服务器如何或在哪里启动。

我们建议观看 “永远不要本地安装”(视频). 使用 Docker 不需要使用 Dockerhub。Docker ≠ Dockerhub。把 Docker 想象成一个编程引擎,把 Dockerhub 想成它的应用商店。

☑️ 先在命令行中运行 docker version 以确认你已经完成 Web Games.

安装 Docker Desktop(或 Docker CLI)

☑️ 在你的服务器文件夹中添加一个 Dockerfile 和一个 .dockerignore 文件,这是你的镜像配方:

使用 node启动你的服务器,而不是 npm start. Edgegap 会发送 SIGTERM 当你的部署停止时,只有容器的主进程会收到它——请处理它以实现优雅关闭。

☑️ 构建你的镜像,选择一个镜像名称和标签:

  • 镜像名称 是你自定义的唯一标识,用于在发布前标记你的服务器构建。

    • 通常会包含你的游戏名称——例如“my-game-server”。

    • 在前面加上 registry.edgegap.com/<project>/ ,使用第 Web Games步中的项目名称,这样你之后就可以上传它。

  • 镜像标签 是指向镜像特定版本的标识符。

    • “构建产物”这个术语有时也用于指代镜像的特定版本。

    • 时间戳是一个很好的默认标签选项,例如 2026.11.02-16.25.00-UTC .

  • 平台 linux/amd64 可确保你的镜像在 Edgegap 服务器上运行,即使你是在 ARM 架构的机器上构建(macOS M1、M2、M3 等)。

☑️ 等待构建完成,并确认命令行中没有新的错误。完成此步骤后,你的 本地机器上将出现一个新镜像。你可以在 Docker Desktop 中的 Local(默认)下的 Images 选项卡里查看,或者通过运行以下命令在 Docker CLI 中验证: docker images .

✅ 现在你可以进行下一步。

🧪 4. 本地测试服务器

让我们先在本地(在你的机器上)尝试部署并连接游戏客户端,以确保服务器映像在我们上传和部署(可能需要一些时间)之前能正常工作。

☑️ 从你的镜像启动一个新容器:

  • -p {内部端口}/{协议} 会发布并映射你的服务器端口 7777 到一个随机的外部端口。WebSocket 使用 TCP 协议。

  • 如果你使用的是 ARM 架构的机器(macOS M1、M2、M3 等),请添加参数 --platform=linux/amd64 .

☑️ 确认你看到 listening on 0.0.0.0:7777 到你的命令行中。完成此步骤后,你的 新容器将被启动 在你的开发机器上。

更多详情请参见 Docker Desktop / Containers,或 Docker CLI 命令 docker ps .

☑️ 现在是时候 将游戏客户端连接到你本地的 Docker 容器 ,以验证你的服务器镜像是否正常工作。打开两个浏览器标签页,在每个标签页中打开开发者工具控制台(F12),并使用以下方式连接到你的容器:

  • localhost 代替服务器 IP,

  • 使用 Docker Desktop / Containers 中找到的随机外部端口值。

☑️ 在一个标签页中发送消息 socket.send('hello') 并确认两个标签页都输出 received hello.

☑️ 一旦你确认可以连接到本地服务器容器并且能够正常游戏,就可以删除该容器 🗑️ 以释放机器上的资源供其他程序使用。

✅ 现在你可以进行下一步。

☁️ 5. 上传到 Edgegap

是时候将您的服务器上线了!既然您的镜像现在可以成功托管玩家,我们就可以将其上传到 Edgegap 并开始在世界任何地方运行。在本指南中,我们将使用 Edgegap 的容器注册表 (镜像的存储)。

☑️ 将你的镜像上传到 Edgegap 的容器仓库:

☑️ 等待上传完成,并确认命令行中没有新的错误。完成此步骤后,你的 构建产物将被上传到 Edgegap 的容器仓库.

☑️ 打开我们的 控制面板 并创建一个新的应用。你可以配置以下选项(或保留默认值):

  • 应用名称 在 Edgegap 上可以与镜像名称一致,也可以自定义。

  • 应用版本 在 Edgegap 上可以与标签一致,也可以自定义。

    • 时间戳也是应用版本名称的一个好选择,例如 2026.11.02-16.25.00-UTC .

    • 多个应用版本可以指向同一个镜像标签,例如 v1.1.0 和 dev .

    • 进一步了解 应用和版本 。

  • 镜像 来自步骤 Web Games,选择你的仓库和标签。

  • 资源 0.25 vCPU 和 512 MB 内存就足以开始使用这个模板。

☑️ 现在系统会提示你为新的应用版本定义一个端口:

  • 端口 7777 与步骤中的服务器端口相匹配 Web Games,

  • 协议 WS (WebSocket),

  • TLS 升级 已启用,

  • 名称 gameport.

TLS 升级可让浏览器通过安全 WebSocket 连接 (wss://。通过 https:// 提供的页面无法打开不安全的 ws:// 连接,因此请为浏览器游戏保持启用 TLS 升级。

免费套餐限制为 2 个应用程序、2 个版本和 10 GB 的容器镜像仓库存储空间。

✅ 现在你可以进行下一步。

🚀 6. 部署到云端

这是本指南的最后一步,完成后您将在 Edgegap 云上部署一个服务器,来自世界任何地方的玩家都可以连接到该服务器。

☑️ 选择一个应用程序和版本 从先前的步骤部署。

☑️ 一旦准备好,请点击 部署到云端,等待达到 部署。完成此步骤将导致 一个新的部署被启动 在您的 Edgegap 帐户上。

☑️ 验证控制台输出中没有新的错误。同时确保您的 部署 没有显示任何错误,并且您的 部署 未显示 100% 的资源利用率(vCPU 或内存),否则新的玩家连接可能会被拒绝,或您的服务器可能会陷入重启循环。请参阅下面的故障排除步骤以解决任何问题。

☑️ 现在我们将执行最后的测试,并且 将你的游戏客户端连接到云端部署。获取你的 部署主机 ,用它代替服务器 IP,以及 外部端口 的 gameport,然后从浏览器控制台使用安全 WebSocket 连接:

您在 Edgegap 云上的部署的外部端口将随机选择,以便在潜在攻击者(黑客)造成损害之前减缓并检测到他们。

☑️ 一旦您确认可以无问题连接到您的部署并完成测试, 停止您的部署 以释放您账户中的容量用于下一次构建。

🙌 恭喜您在 Edgegap 上完成首次部署!如果您想了解更多,请继续阅读。

👉 下一步

一旦你有了可用的客户端/服务器设置,请确保 保存你的项目副本 (使用诸如 git 之类的版本控制软件),以便在遇到问题时总能追溯你的步骤。

继续阅读以了解更多与服务器生命周期和可发现性相关的主题。

如果你需要帮助, 请通过 Discord 联系我们。关于实时游戏支持,请查看我们的 工单系统.

停止部署

当对局结束(或玩家离开)后,可以停止你的部署以节省成本。 空置或仅部分填满的部署可能会不必要地增加你的成本!

从你的服务器代码中停止部署,Edgegap 然后会发送 SIGTERM 到你的服务器:

注入变量

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

使用 process.env读取任意变量,或者使用我们可选的 SDK 将它们解析为有类型的对象:

解析过程不会抛出异常,因此同一个服务器可以在本地运行。缺失的变量会以单个警告列出。

会话自动化

在与开发人员或 QA 团队测试新构建时,通常会跳过会话步骤,玩家直接连接到部署,同时对与会话相关的功能进行硬编码或禁用。这使开发迭代更快,并将会话副作用与服务器功能隔离开来。

自动化以下热门游戏流程: 玩家会话 以及服务器扩缩容,可通过以下任一方式:

匹配系统:

  • 竞技游戏

  • 按需对局

  • 技能评级和/或 自定义规则

服务器浏览器:

  • 持久型或社交型

  • 长时会话

  • 自动分配和/或 自定义搜索

自定义后端:

示例

从五个使用 Three.js 和权威 Node.js 服务器构建的浏览器多人小游戏中获取灵感。 包含浏览器端匹配、单个镜像支持多个游戏、队伍分配,以及在对局结束时自动停止的部署。

优化使用

以下是一些帮助你开始优化服务器使用的技巧:

更高的 tick 频率意味着更多更新,需要更多 CPU 资源和数据外传流量。

  • 浏览器游戏通常以每秒 30-60 tick 进行模拟,并以 10-20 Hz 向玩家发送状态,客户端在更新之间进行插值。我们的 Three.js 示例每秒发送 20 次更新。

  • Node.js 在单线程上运行你的游戏循环,因此缓慢的 tick 会延迟所有玩家的消息。如果你的游戏每场对局有很多玩家(10+)、复杂的物理模拟,或很多机器人对手/队友,请格外小心。使用以下命令分析你的服务器: node --cpu-prof 来找出热点。

  • JSON 消息易于调试,二进制消息(ArrayBuffer)可减少频繁状态更新时的数据外传。

如何选择合适的网络协议?先让它工作,再让它变好。

  • 浏览器无法打开原始 UDP 或 TCP 连接,只能使用 WebSocket、WebRTC 和 WebTransport。WebSocket 是一个很好的默认选择,能在最广泛的设备和网络上提供兼容性。

  • 一些快节奏游戏可能希望尝试使用 WebRTC 数据通道或 WebTransport 来实现不可靠传输,但这肯定需要额外的开发工作。请问问自己,这对你的目标受众是否至关重要。

  • 谨慎选择你的投入方向,游戏开发从不缺少挑战。

自定义镜像

你在步骤中的 Dockerfile Web Games 可以根据构建体积优化、冗余依赖,或更复杂的启动流程进行定制。下面我们将分享一些“自己动手”的技巧和最佳实践。

使用多阶段构建将你的服务器打包为单个文件。

  • 像 esbuild 这样的打包工具会编译 TypeScript,并将你的代码和依赖合并为一个文件,因此你的最终镜像不需要 node_modules 或源文件。随着依赖树变大,节省效果会更明显。

  • 使用以下命令安装 esbuild: npm install --save-dev esbuild 并将你的 Dockerfile 替换为:

始终确保你使用的是一个可正常运行的服务器构建版本。

  • 在断定某个问题与自定义 Dockerfile 有关之前,请确保你的服务器构建能够启动,并且游戏引擎中的构建过程没有抛出任何异常或错误。

上传前务必先在本地测试。

  • 在本地测试你的镜像可以为你节省大量等待上传完成的时间。而且它完全免费 ✨,因为不需要任何 Edgegap 资源。

  • 在本地测试时,请务必正确设置内部端口:

确保你已经掌握了基础内容。每个 Dockerfile 都需要一些基本的必需命令:

  • FROM {image} 是你的基础镜像,我们通常使用长期支持的 Linux,但任何基于 Linux 的基础镜像都可以。这些通常是存储在 Docker Hub 上的公共镜像。Dockerfile 参考文档见此。 Dockerfile 参考文档见此.

  • COPY {source} {destination} 用于将你主机上的 Linux 服务器构建复制到镜像内部,以便之后可以启动它。 Dockerfile 参考文档见此.

  • USER {user} 应该跟在一个 useradd (ubuntu) 命令 之后,最好不要把所有东西都以 root 的身份运行,以便更安全。 Dockerfile 参考文档见此.

  • CMD {command} 将是最后一行,很可能会调用一个 StartServer.sh 或某种启动脚本,以确保在一切设置完成后你的服务器能够正确初始化。 Dockerfile 参考文档见此.

  • 不要使用 VOLUME - 你将无法通过这种方式在 Edgegap 上挂载任何本地存储,请考虑改用我们的 Endpoint Storage 功能并使用 S3 存储桶,参见 Endpoint Storage,

  • EXPOSE 7777/UDP 不是必需的!这实际上不会让容器外部访问内部服务器端口,它只是给开发者的一个提示,而该端口需要

    • 在本地测试时通过以下方式发布: docker run <image> -p 7777/udp ,

    • 或映射到 Edgegap Port Mapping.

尽可能将参数的声明延后到最后一刻。由于服务器构建时间较长,可配置性 > 可组合性。 将此方法应用到 Dockerfile 命令中,以更快地构建和上传。

  • 场景:你需要定义诸如部署阶段、版本、游戏模式、地图、每台服务器的玩家数量、备份频率或类似的参数。

  • 糟糕的方案:为参数的每一种组合都创建一个单独的镜像。你会把所有时间都花在重新构建镜像上,而这种方法带来的好处却非常有限。

  • 更好的方案——在需要时再替换配置参数:

    1. 部署参数——在部署前才提供——例如作为环境变量传递的匹配选择器,或者你的自定义会话管理系统在部署时传递环境变量,

    2. 版本参数——在同一应用版本的所有部署中共享——例如部署阶段、制品标签、第三方密钥和端点等;然后

    3. 一个单一镜像——在启动时包含并加载所有配置选项。

不要在 Edgegap 部署中运行数据库。

  • Edgegap 部署并非为长时间运行的进程而设计,可能会在运行很久后未经事先通知而被终止。以这种方式运行的数据库(即使是分布式的)也可能被终止,并导致不可逆的数据丢失。如果你需要数据库,请考虑使用第三方 DBaaS。

  • 考虑使用我们的 托管集群 来托管数据库和长时间运行的服务。

最后更新于

这有帮助吗?