> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/zh/web-games.md).

# 网页游戏（JS/TS）- 入门

在 Edgegap 上部署你的第一个 JavaScript 或 TypeScript 专用服务器。这是一份实操指南，包含最小化的 Node.js 模板、上传以及面向浏览器多人游戏的全球部署。

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

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

## ✔️ 准备工作

开始之前，请务必 [在 Edgegap 创建一个免费账户](https://app.edgegap.com/auth/register) （无需信用卡）。你可以 [之后邀请你的团队成员](https://app.edgegap.com/user-settings?tab=organizations)，即使他们还没有 Edgegap 账户。

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

<details>

<summary><a href="https://nodejs.org/en/download">安装 Node.js 22 或更高版本</a></summary>

* [从官方来源安装 Node.js](https://nodejs.org/en/download)，我们建议使用最新的 LTS 版本。
* 通过运行以下命令验证你的安装 `node -v` 在你的命令行中。

</details>

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">安装 Docker Desktop（或 Docker CLI）</a></summary>

* [从官方来源安装 Docker Desktop](https://www.docker.com/products/docker-desktop/) （无需账户）。
* 完成安装后重启计算机。

</details>

{% hint style="info" %}
**对你的服务器构建很有把握？** 跳转到 [#customize-image](#customize-image "mention") 或 [高级功能](https://docs.edgegap.com/zh/learn/advanced-features.md) 了解更多。
{% endhint %}

## ⚙️ 1. 连接账户

JavaScript 服务器不需要引擎插件。我们将使用你的命令行和我们的 [控制面板](https://app.edgegap.com/) 来构建、上传并部署你的服务器。

☑️ 登录我们的控制面板并打开 [容器仓库](https://app.edgegap.com/registry-management/repositories/list)。记下你的 **项目名称** 和 **仓库凭据** （用户名和令牌），你将在接下来的步骤中用到它们。

☑️ 登录 [Edgegap 的容器仓库](https://docs.edgegap.com/zh/learn/advanced-features/edgegap-container-registry.md) ，使用你的仓库项目名称、用户名和令牌通过 Docker 登录：

{% tabs %}
{% tab title="Bash（Linux）" %}

```bash
project='<REGISTRY_PROJECT>';
username='robot$<REGISTRY_ORGANIZATION_ID>+client-push';
token='<REGISTRY_TOKEN>';

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}

{% tab title="PowerShell（Windows）" %}

```powershell
$project = '<REGISTRY_PROJECT>'
$username = 'robot$<REGISTRY_ORGANIZATION_ID>+client-push'
$token = '<REGISTRY_TOKEN>'

echo "$token" | docker login registry.edgegap.com -u "$username" --password-stdin 2>&1
```

{% endtab %}
{% endtabs %}

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

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

## 🔧 2. 构建游戏服务器

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

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

{% tabs %}
{% tab title="TypeScript - node.js 22.18+（推荐）" %}
{% hint style="info" %}
Node.js 22.18+ 可直接运行 TypeScript 文件（会去除注解），无需构建步骤。
{% endhint %}

1. 将 `server.ts` 模板复制到你的项目中（如果你还没有的话）：<br>

   <pre class="language-javascript" data-title="server.ts" data-expandable="true" data-collapsed-line-count="10"><code class="lang-javascript">import http from 'node:http'
   import { WebSocketServer } from 'ws'
   import { DeploymentEnvironment } from '@edgegap/sdk'

   const port = Number(process.env.PORT ?? 7777)
   const deployment = process.env.ARBITRIUM_REQUEST_ID ? DeploymentEnvironment.fromEnv(process.env) : null

   const server = http.createServer((_request: http.IncomingMessage, response: http.ServerResponse) => response.end('ok\n'))
   const wss = new WebSocketServer({ server })

   wss.on('connection', (socket) => {
     console.log(`player connected (${wss.clients.size} online)`)
     socket.on('message', (data) => {
       for (const client of wss.clients) client.send(data.toString())
     })
     socket.on('close', () => console.log(`player left (${wss.clients.size} online)`))
   })

   server.listen(port, '0.0.0.0', () => {
     console.log(`listening on 0.0.0.0:${port}`)
     console.log(deployment ? `deployment ${deployment.requestId} in ${deployment.location?.city}` : 'running locally')
   })

   process.on('SIGTERM', () => {
     for (const client of wss.clients) client.close(1001, 'server stopping')
     server.close(() => process.exit(0))
   })
   </code></pre>
2. 将 `package.json` 到你的项目中（或与现有文件合并）。<br>

   <pre class="language-json" data-title="package.json" data-expandable="true" data-collapsed-line-count="10"><code class="lang-json">{
     "name": "my-game-server",
     "private": true,
     "type": "module",
     "engines": {
       "node": ">=22"
     },
     "scripts": {
       "start": "node server.ts"
     },
     "dependencies": {
       "@edgegap/sdk": "^1.1.0",
       "ws": "^8.18.3"
     }
   }
   </code></pre>
3. 为你的编辑器安装类型定义：<br>

   <pre class="language-bash" data-collapsed-line-count="10"><code class="lang-bash">npm install --save-dev @types/node @types/ws
   </code></pre>

{% hint style="warning" %}
**类型去除仅支持可擦除语法。** 避免使用 `enum`, `namespace`，以及构造函数参数属性，或者 [改为打包你的服务器](#customize-image).
{% endhint %}
{% endtab %}

{% tab title="JavaScript（较早版本的 node.js）" %}

1. 将 `server.js` 模板复制到你的项目中（如果你还没有的话）：<br>

   <pre class="language-javascript" data-title="server.js" data-expandable="true" data-collapsed-line-count="10"><code class="lang-javascript">import http from 'node:http'
   import { WebSocketServer } from 'ws'
   import { DeploymentEnvironment } from '@edgegap/sdk'

   const port = Number(process.env.PORT ?? 7777)
   const deployment = process.env.ARBITRIUM_REQUEST_ID ? DeploymentEnvironment.fromEnv(process.env) : null

   const server = http.createServer((_request, response) => response.end('ok\n'))
   const wss = new WebSocketServer({ server })

   wss.on('connection', (socket) => {
     console.log(`player connected (${wss.clients.size} online)`)
     socket.on('message', (data) => {
       for (const client of wss.clients) client.send(data.toString())
     })
     socket.on('close', () => console.log(`player left (${wss.clients.size} online)`))
   })

   server.listen(port, '0.0.0.0', () => {
     console.log(`listening on 0.0.0.0:${port}`)
     console.log(deployment ? `deployment ${deployment.requestId} in ${deployment.location?.city}` : 'running locally')
   })

   process.on('SIGTERM', () => {
     for (const client of wss.clients) client.close(1001, 'server stopping')
     server.close(() => process.exit(0))
   })
   </code></pre>
2. 将 `package.json` 到你的项目中（或与现有文件合并）。<br>

   <pre class="language-json" data-title="package.json" data-expandable="true" data-collapsed-line-count="10"><code class="lang-json">{
     "name": "my-game-server",
     "private": true,
     "type": "module",
     "engines": {
       "node": ">=22"
     },
     "scripts": {
       "start": "node server.js"
     },
     "dependencies": {
       "@edgegap/sdk": "^1.1.0",
       "ws": "^8.18.3"
     }
   }
   </code></pre>

{% endtab %}
{% endtabs %}

{% hint style="success" %}
`@edgegap/sdk` 是可选的，此模板使用它来读取 [注入变量](#injected-variables) 在 Edgegap 上。使用我们的 [JavaScript SDK](https://docs.edgegap.com/zh/web-games/matchmaking.md) 用于 [#session-automation](#session-automation "mention")，或者接入第三方匹配服务。
{% endhint %}

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

{% code collapsedlinecount="10" %}

```bash
npm install
npm start
```

{% endcode %}

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

{% hint style="success" %}
服务器构建应使用地址 `0.0.0.0` 和端口 `7777`。如果你自定义了端口，请在你的 [应用与版本](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md#port-mapping) 之后指定相同的端口， [#id-5.-upload-to-edgegap](#id-5.-upload-to-edgegap "mention").
{% endhint %}

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

## 🐋 3. 容器化服务器

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

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

{% hint style="info" %}
我们建议观看 [“永远不要本地安装”（视频）](https://www.youtube.com/watch?v=J0NuOlA2xDc\&ab_channel=Coderized). **使用 Docker 不需要使用 Dockerhub**。Docker ≠ Dockerhub。把 Docker 想象成一个编程引擎，把 Dockerhub 想成它的应用商店。
{% endhint %}

☑️ 先在命令行中运行 `docker version` 以确认你已经完成 [#preparation](#preparation "mention").

<details>

<summary><a href="https://www.docker.com/products/docker-desktop/">安装 Docker Desktop（或 Docker CLI）</a></summary>

* [从官方来源安装 Docker Desktop](https://www.docker.com/products/docker-desktop/) （无需账户）。
* 完成安装后重启计算机。

</details>

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

{% tabs %}
{% tab title="TypeScript - node.js 22.18+（推荐）" %}
{% code title="Dockerfile" collapsedlinecount="10" %}

```docker
FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.ts ./
USER node
CMD ["node", "server.ts"]
```

{% endcode %}
{% endtab %}

{% tab title="JavaScript（较早版本的 node.js）" %}
{% code title="Dockerfile" collapsedlinecount="10" %}

```docker
FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.js ./
USER node
CMD ["node", "server.js"]
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% code title=".dockerignore" collapsedlinecount="10" %}

```
node_modules
.git
*.md
```

{% endcode %}

{% hint style="info" %}
**使用 `node`启动你的服务器，而不是 `npm start`.** Edgegap 会发送 `SIGTERM` 当你的部署停止时，只有容器的主进程会收到它——请处理它以实现优雅关闭。
{% endhint %}

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

{% code collapsedlinecount="10" %}

```bash
docker build --platform linux/amd64 \\
  -t registry.edgegap.com/<project>/<game-name>:<tag> .
```

{% endcode %}

* **镜像名称** 是你自定义的唯一标识，用于在发布前标记你的服务器构建。
  * 通常会包含你的游戏名称——例如“my-game-server”。
  * 在前面加上 `registry.edgegap.com/<project>/` ，使用第 [#id-1.-connect-account](#id-1.-connect-account "mention")步中的项目名称，这样你之后就可以上传它。
* **镜像标签** 是指向镜像特定版本的标识符。
  * “构建产物”这个术语有时也用于指代镜像的特定版本。
  * 时间戳是一个很好的默认标签选项，例如 `2026.11.02-16.25.00-UTC` .
* **平台** `linux/amd64` 可确保你的镜像在 Edgegap 服务器上运行，即使你是在 ARM 架构的机器上构建（macOS M1、M2、M3 等）。

{% hint style="danger" %}
:x: **不要覆盖现有标签，也不要使用 `latest`  标签** ——这会部署过时的缓存。\
:white\_check\_mark: **应该始终递增版本标签** 并部署新的构建版本。
{% endhint %}

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

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

## 🧪 4. 本地测试服务器

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

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

{% code collapsedlinecount="10" %}

```bash
docker run -p 7777/tcp registry.edgegap.com/<project>/<game-name>:<tag>
```

{% endcode %}

* `-p {内部端口}/{协议}` 会发布并映射你的服务器端口 `7777` 到一个随机的外部端口。WebSocket 使用 TCP 协议。
* 如果你使用的是 ARM 架构的机器（macOS M1、M2、M3 等），请添加参数 `--platform=linux/amd64` .

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

{% hint style="info" %}
更多详情请参见 Docker Desktop / Containers，或 Docker CLI 命令 `docker ps` .
{% endhint %}

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

* `localhost` 代替服务器 IP，
* 使用 Docker Desktop / Containers 中找到的随机外部端口值。

{% code collapsedlinecount="10" %}

```javascript
const socket = new WebSocket('ws://localhost:<external port>')
socket.onmessage = (event) => console.log('received', event.data)
```

{% endcode %}

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

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2FCDGTUe5ests3DI3u9rTV%2Fimage.png?alt=media&amp;token=8c4799d8-0622-4142-91a5-93fd1816149c" alt=""><figcaption></figcaption></figure>

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

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

## ☁️ 5. 上传到 Edgegap

是时候将您的服务器上线了！既然您的镜像现在可以成功托管玩家，我们就可以将其上传到 Edgegap 并开始在世界任何地方运行。在本指南中，我们将使用 [**Edgegap 的容器注册表**](https://docs.edgegap.com/zh/learn/advanced-features/edgegap-container-registry.md) （镜像的存储）。

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

{% code collapsedlinecount="10" %}

```bash
docker push registry.edgegap.com/<project>/<game-name>:<tag>
```

{% endcode %}

{% hint style="success" %}
在你的机器中查找存储的任何镜像名称和标签 **Docker Desktop / 镜像**.
{% endhint %}

☑️ 等待上传完成，并确认命令行中没有新的错误。完成此步骤后，你的 [构建产物将被上传到 Edgegap 的容器仓库](https://app.edgegap.com/registry-management/repositories/list).

☑️ 打开我们的 [控制面板](https://app.edgegap.com/application-management/applications/list) 并创建一个新的应用。你可以配置以下选项（或保留默认值）：

* **应用名称** 在 Edgegap 上可以与镜像名称一致，也可以自定义。
* **应用版本** 在 Edgegap 上可以与标签一致，也可以自定义。
  * 时间戳也是应用版本名称的一个好选择，例如 `2026.11.02-16.25.00-UTC` .
  * 多个应用版本可以指向同一个镜像标签，例如 `v1.1.0` 和 `dev` .
  * 进一步了解 [应用和版本](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md) 。
* **镜像** 来自步骤 [#id-3.-containerize-server](#id-3.-containerize-server "mention")，选择你的仓库和标签。
* **资源** 0.25 vCPU 和 512 MB 内存就足以开始使用这个模板。

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

* **端口** `7777` 与步骤中的服务器端口相匹配 [#id-2.-build-game-server](#id-2.-build-game-server "mention"),
* **协议** `WS` （WebSocket），
* **TLS 升级** 已启用，
* **名称** `gameport`.

{% hint style="info" %}
**TLS 升级可让浏览器通过安全 WebSocket 连接** (`wss://`。通过 `https://` 提供的页面无法打开不安全的 `ws://` 连接，因此请为浏览器游戏保持启用 TLS 升级。
{% endhint %}

{% hint style="info" %}
免费套餐限制为 2 个应用程序、2 个版本和 10 GB 的容器镜像仓库存储空间。
{% endhint %}

{% hint style="success" %}
**在使用编码代理？** 查看 [MCP 集成](https://docs.edgegap.com/zh/docs/mcp-ji-cheng.md) ，无需离开编辑器即可创建应用、版本和部署。
{% endhint %}

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

## 🚀 6. 部署到云端

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

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

☑️ 一旦准备好，请点击 **部署到云端**，等待达到 [/pages/5e7e2169ca3822647d4607dfc1d3487ebcc0836c#id-3.-deployment-ready](https://docs.edgegap.com/pages/5e7e2169ca3822647d4607dfc1d3487ebcc0836c#id-3.-deployment-ready "mention")。完成此步骤将导致 [一个新的部署被启动](https://app.edgegap.com/deployment-management/deployments/list) 在您的 Edgegap 帐户上。

☑️ 验证控制台输出中没有新的错误。同时确保您的 [部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#container-logs) 没有显示任何错误，并且您的 [部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#container-metrics) 未显示 100% 的资源利用率（vCPU 或内存），否则新的玩家连接可能会被拒绝，或您的服务器可能会陷入重启循环。请参阅下面的故障排除步骤以解决任何问题。

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

{% code collapsedlinecount="10" %}

```javascript
const socket = new WebSocket('wss://<host>:<external port>')
socket.onmessage = (event) => console.log('received', event.data)
```

{% endcode %}

<figure><img src="https://3334189208-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsR0dHSFv9ymoC0DO5G8J%2Fuploads%2Fz9xjzvZwKSIp9IeC9qo8%2Fimage.png?alt=media&amp;token=e3f345ac-848d-4469-b66f-3655cd393cf3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
您在 Edgegap 云上的部署的外部端口将随机选择，以便在潜在攻击者（黑客）造成损害之前减缓并检测到他们。
{% endhint %}

{% hint style="warning" %}
**测试时请禁用 VPN** 以获得更真实的条件并接收一个 [低延迟部署](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#server-placement).
{% endhint %}

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

* 如果您遇到问题， [检查您部署的仪表板日志](https://app.edgegap.com/deployment-management/deployments/list).
* 如果您无法找出问题，我们会在我们的频道等着您， [社区 Discord](https://discord.gg/NgCnkHbsGp) 遇到困难？我们在我们的

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

## 👉 下一步

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

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

{% hint style="info" %}
如果你需要帮助， [请通过 Discord 联系我们](https://discord.gg/MmJf8fWjnt)。关于实时游戏支持，请查看我们的 [工单系统](https://edgegap.atlassian.net/servicedesk/customer/portal/3).
{% endhint %}

### 停止部署

当对局结束（或玩家离开）后，可以停止你的部署以节省成本。 [空置或仅部分填满的部署可能会不必要地增加你的成本！](https://edgegap.com/blog/how-session-fill-rate-affects-your-multiplayer-hosting-costs)

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

{% code collapsedlinecount="10" %}

```javascript
const stopDeployment = () =>
  fetch(deployment.selfStopUrl, {
    method: 'DELETE',
    headers: { authorization: deployment.selfStopToken }
  }) // 示例使用 javascript SDK 读取部署自停止信息
```

{% endcode %}

{% hint style="success" %}
**调用 `stopDeployment` 在对局结束时、所有玩家离开时，或者在** 部署启动后的一段合理时间内没有任何人连接时。
{% endhint %}

{% hint style="warning" %}
连接你的 [端点存储](https://docs.edgegap.com/zh/docs/endpoint-storage.md) 以保存部署日志，否则它们将被删除！
{% endhint %}

### 注入变量

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

* [部署变量](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#injected-environment-variables) - 由 Edgegap 自动提供，
* [匹配变量](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong/matchmaker-in-depth.md#injected-environment-variables) - 在使用 [匹配服务](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md),
* [应用版本变量](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md#injected-variables) - 由你配置的自定义键值对。

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

{% code collapsedlinecount="10" %}

```javascript
import { DeploymentEnvironment } from '@edgegap/sdk'
import { MatchEnvironment } from '@edgegap/sdk/matchmaking'

const deployment = DeploymentEnvironment.fromEnv(process.env)
const match = MatchEnvironment.fromEnv(process.env)
```

{% endcode %}

{% hint style="info" %}
解析过程不会抛出异常，因此同一个服务器可以在本地运行。缺失的变量会以单个警告列出。
{% endhint %}

### 会话自动化

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

{% hint style="warning" %}
**手动启动你的部署并粘贴 URL 和端口，无法满足实时游戏的需求。**
{% endhint %}

自动化以下热门游戏流程： [玩家会话](https://docs.edgegap.com/zh/learn/bian-pai/wan-jia-hui-hua.md) 以及服务器扩缩容，可通过以下任一方式：

{% columns %}
{% column width="33.33333333333333%" %}
[匹配系统](https://docs.edgegap.com/zh/learn/pi-pei-xi-tong.md):

* 竞技游戏
* 按需对局
* 技能评级和/或\
  自定义规则
  {% endcolumn %}

{% column width="33.33333333333333%" %}
[服务器浏览器](https://docs.edgegap.com/zh/learn/fu-wu-qi-liu-lan-qi.md):

* 持久型或社交型
* 长时会话
* 自动分配和/或\
  自定义搜索
  {% endcolumn %}

{% column width="33.33333333333333%" %}
自定义后端：

* 迁移线上游戏
* [使用 v2 API 部署](https://docs.edgegap.com/zh/docs/api/zhuan-yong-fu-wu-qi.md)
* [监控 Webhooks](https://docs.edgegap.com/zh/learn/bian-pai/deployments.md#webhooks)
  {% endcolumn %}
  {% endcolumns %}

{% hint style="success" %}
使用我们的可选功能为你的浏览器游戏添加匹配服务 [JavaScript SDK](https://docs.edgegap.com/zh/web-games/matchmaking.md)，包括组队客户端和服务器回填自动化。
{% endhint %}

### 示例

[从五个使用 Three.js 和权威 Node.js 服务器构建的浏览器多人小游戏中获取灵感。](https://docs.edgegap.com/zh/docs/sample-projects/wang-ye-you-xi/threejs-minigames.md) 包含浏览器端匹配、单个镜像支持多个游戏、队伍分配，以及在对局结束时自动停止的部署。

{% hint style="success" %}
[浏览我们的游戏示例](https://docs.edgegap.com/zh/docs/sample-projects.md) 以获得灵感并增强推进您项目的信心。
{% endhint %}

### 优化使用

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

**更高的 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 [#id-3.-containerize-server](#id-3.-containerize-server "mention") 可以根据构建体积优化、冗余依赖，或更复杂的启动流程进行定制。下面我们将分享一些“自己动手”的技巧和最佳实践。

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

* 像 [esbuild](https://esbuild.github.io/) 这样的打包工具会编译 TypeScript，并将你的代码和依赖合并为一个文件，因此你的最终镜像不需要 `node_modules` 或源文件。随着依赖树变大，节省效果会更明显。
* 使用以下命令安装 esbuild： `npm install --save-dev esbuild` 并将你的 Dockerfile 替换为：

{% code title="Dockerfile" collapsedlinecount="10" %}

```docker
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY server.js ./
RUN npx esbuild server.js --bundle --platform=node --target=node22 --outfile=dist/server.cjs

FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/dist/server.cjs ./
USER node
CMD ["node", "server.cjs"]
```

{% endcode %}

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

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

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

* 在本地测试你的镜像可以为你节省大量等待上传完成的时间。而且它完全免费 ✨，因为不需要任何 Edgegap 资源。
* 在本地测试时，请务必正确设置内部端口：

  ```bash
  docker run \
    -p 7777/udp \
    -e ARBITRIUM_PORTS_MAPPING='{"ports":{"gameport":{"internal":7777}}}' \
    'registry.edgegap.com/<repository>:<tag>'
  ```

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

* `FROM {image}` 是你的基础镜像，我们通常使用长期支持的 Linux，但任何基于 Linux 的基础镜像都可以。这些通常是存储在 Docker Hub 上的公共镜像。Dockerfile 参考文档见此。 [Dockerfile 参考文档见此](https://docs.docker.com/reference/dockerfile/#from).
* `COPY {source} {destination}` 用于将你主机上的 Linux 服务器构建复制到镜像内部，以便之后可以启动它。 [Dockerfile 参考文档见此](https://docs.docker.com/reference/dockerfile/#copy).
* `USER {user}` 应该跟在一个 [useradd (ubuntu) 命令](https://manpages.ubuntu.com/manpages/bionic/man8/useradd.8.html) 之后，最好不要把所有东西都以 `root` 的身份运行，以便更安全。 [Dockerfile 参考文档见此](https://docs.docker.com/reference/dockerfile/#user).
* `CMD {command}` 将是最后一行，很可能会调用一个 `StartServer.sh` 或某种启动脚本，以确保在一切设置完成后你的服务器能够正确初始化。 [Dockerfile 参考文档见此](https://docs.docker.com/reference/dockerfile/#cmd).
* 不要使用 `VOLUME` - 你将无法通过这种方式在 Edgegap 上挂载任何本地存储，请考虑改用我们的 Endpoint Storage 功能并使用 S3 存储桶，参见 [Endpoint Storage](https://docs.edgegap.com/docs/deployment/endpoint-storage),
* `EXPOSE 7777/UDP`  不是必需的！这实际上不会让容器外部访问内部服务器端口，它只是给开发者的一个提示，而该端口需要
  * 在本地测试时通过以下方式发布： `docker run <image> -p 7777/udp` ,
  * 或映射到 [Edgegap Port Mapping](https://docs.edgegap.com/zh/learn/bian-pai/application-and-versions.md#other-parameters-optional).

**尽可能将参数的声明延后到最后一刻。由于服务器构建时间较长，可配置性 > 可组合性。** [**将此方法应用到 Dockerfile 命令中，以更快地构建和上传。**](https://medium.com/@esotericmeans/optimizing-your-dockerfile-dc4b7b527756)

* 场景：你需要定义诸如部署阶段、版本、游戏模式、地图、每台服务器的玩家数量、备份频率或类似的参数。
* 糟糕的方案：为参数的每一种组合都创建一个单独的镜像。你会把所有时间都花在重新构建镜像上，而这种方法带来的好处却非常有限。
* 更好的方案——在需要时再替换配置参数：
  1. 部署参数——在部署前才提供——例如作为环境变量传递的匹配选择器，或者你的自定义会话管理系统在部署时传递环境变量，
  2. 版本参数——在同一应用版本的所有部署中共享——例如部署阶段、制品标签、第三方密钥和端点等；然后
  3. 一个单一镜像——在启动时包含并加载所有配置选项。

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

* Edgegap 部署并非为长时间运行的进程而设计，可能会在运行很久后未经事先通知而被终止。以这种方式运行的数据库（即使是分布式的）也可能被终止，并导致不可逆的数据丢失。如果你需要数据库，请考虑使用第三方 DBaaS。
* 考虑使用我们的 [托管集群](https://app.edgegap.com/cluster-management/clusters/list) 来托管数据库和长时间运行的服务。
