Superpowers：开源自托管实时协作游戏编辑器的安装与实战

前阵子折腾一款开源实时协作游戏创作工具，名字就叫 Superpowers。听上去像个中二程序员模仿超英电影起的代号，实际上它是一套可以自己部署到服务器上的 Web 游戏创作环境：浏览器打开就能用，直接做 2D 游戏、互动故事、原型和课程案例，成员坐在不同城市也能同时编辑同一个场景。这篇文章把我从安装到第一次跑通项目的完整过程完整记录下来，适合独立开发者、小团队，以及想拿游戏开发做教学的人参考。

安装这类工具最怕的就是文档零散、步骤隐藏、报错全靠猜。Superpowers 的安装其实不算复杂，但也有几个关键坑——尤其是 MongoDB 的安装方式、端口规划、以及多人协作依赖的实时同步机制，搞不明白的话很容易卡住。下面按我的实际顺序一步步拆解。

1. 它到底是什么：一套自带协作能力的浏览器游戏编辑器

1.1 核心组成和工作原理

Superpowers 是免费开源软件。一句话解释它的架构：服务端跑一个 Node.js 应用，负责账号管理、项目文件存储、数据库读写和脚本编译这些事；客户端这里没有任何原生安装包，打开浏览器输入地址就能进入编辑器界面，服务端和浏览器之间通过 WebSocket 做实时双向同步，鼠标拖动、脚本修改、资源上传这些操作几乎瞬间推送到其他协作者的页面上。

项目里的所有内容都存储在 MongoDB 里，包括场景树、角色贴图、音频文件、脚本代码、用户信息和历史版本。这样设计的直接好处是项目不再依赖某一台本地电脑的文件夹，换一台设备登录账号就能接着做，协作者之间也不需要手动拉文件、合并代码。你看到的不是传统引擎那种一条条保存的“工程文件”，而是一个实时同步的数据库记录集合。

内置的创作能力相当完整：有场景编辑器、Actor（场景对象）系统、Sprite 贴图资源、动画、粒子效果、灯光、音频场景，以及核心的 Script 脚本组件。大部分 2D 游戏需要的积木都在里面，不需要像某些引擎那样为了一个小交互去装一堆第三方插件。

1.2 和其他工具比，为什么选它

很多人第一反应是：要做游戏为什么不直接用 Godot、GDevelop 或者 Twine？我整理了一个对比表，方便按场景判断：

这几个工具我都试过，结论很明确：如果只是一个人单机写小游戏，Godot 和 GDevelop 都很好；如果你的需求是“多人同时进入同一个游戏项目编辑场景”，Superpowers 是目前最省心的方案，没有之一。它把“在线文档实时协作”的思路搬到了游戏编辑器里，这在同类开源项目里非常少见。

1.3 适合谁用

按我自己的使用经验，这几类人最容易从中获益：

• 小团队远程做原型：策划、程序、美术可以同时在场景里调整，不用等对方导出文件。
• 游戏或编程教学：学生不用装引擎，给一个浏览器链接就能进项目，环境统一，回收作业也方便。
• 互动叙事和故事原型：内置场景和对话脚本能力，做视觉小说、解谜原型非常合适。
• 企业内部模拟演示：自托管在内网，数据不出公司，适合做培训小游戏。

反之，如果你要做的是大型 3D 游戏、物理仿真深度较高的商业项目，或者重度依赖特定音视频渲染管线，那 Superpowers 并不是合适的选择。评估工具前先想清需求边界，能省下大量试错时间。

2. 安装之前把三件事想清楚：Node、MongoDB 和端口

2.1 为什么要通过 npm 安装

Superpowers 以 npm 包的形式分发，这既是优点也可能是安装时的一个心态误区：它不是那种下载完解压就能跑的绿色软件，而是先搭环境、再装包、再启动服务。

npm install -g superpowers会把主程序装到全局目录，之后在任意终端输入superpowers就能启动。这种方式的好处是版本管理统一，升级时一条命令搞定，不依赖某个下载站的镜像是否更新。我建议 Node.js 安装当前 LTS 版本，而不是追逐最新的奇数版本。如果你机器上已经装了多个 Node 版本，最好先用nvm切换到一个确定版本再安装，避免全局包跑到另一个 Node 环境里。

2.2 MongoDB 是项目文件的“仓库”，不是可选项

很多类似的 Web 应用偏向用 SQLite 或 JSON 文件存数据，Superpowers 选择 MongoDB 是为了匹配它特有的协作需求。

项目里的场景结构天然是树状的：场景下面挂 Actor，Actor 下面挂组件和子对象，每个对象还有 transform、材质、脚本参数等字段。MongoDB 的文档模型可以直接用一个嵌套文档表达这颗树，读写时不需要拼装多张关系表。多人同时编辑时，系统会频繁地做局部更新和小范围的并发写，文档数据库在动态字段扩展和快速写入上明显比固定 schema 的表结构更灵活。

所以安装步骤里 MongoDB 不是可选项，缺了它主程序根本起不来。装好之后建议保持 MongoDB 服务监听在localhost:27017，不要把它暴露到公网，否则相当于把整个项目的数据库敞开在互联网上。

2.3 端口规划与对外访问思路

Superpowers 的默认 Web 端口是 4237，不是常见的 3000 或 8080，别习惯性去访问错误的端口。如果只是本机试用，保持默认即可。

如果部署到云服务器或内网 NAS，需要明确三个层面的端口：

• 应用端口 4237：必须对外开放（或通过反向代理转发）。
• MongoDB 27017：禁止对外开放，默认本地监听即可。
• 若用 Nginx 反代：需要处理 WebSocket 升级请求，比普通 HTTP 反代多一段配置。

端口规划这一步容易被新手忽略，尤其是云服务器的“安全组”，很多人服务明明启动了却访问不了，最后发现是阿里云或腾讯云控制台的安全策略没有放行 4237。建议安装之前就用netstat -tlnp | grep 4237确认监听状态，再检查云安全组。

2.4 国内网络下的 npm 源设置

npm 官方源在国内访问速度不稳定，安装大体积依赖时经常卡在进度条上。我个人的习惯是先换成国内镜像源，等需要用官方源再切回：

npm config set registry https://registry.npmmirror.com

设置完之后可以用npm config get registry确认，再执行全局安装，速度提升非常明显。这一步不是必须的，但如果你的网络环境下载缓慢，大概率就是卡在源上。

3. 完整安装实操：Windows、Linux、macOS 一次讲清

3.1 Windows 下最稳的安装路线

我最早就是在 Windows 上装的，当时的教训是“不要想当然地跳过环境依赖”。正确顺序是：

1. 安装 MongoDB Community Server。安装向导里记得勾选“Install MongoD as a Service”，这样它会自动注册成 Windows 服务并开机自启，省去每次手动启动的麻烦。
2. 安装 Node.js LTS，使用自带 MSI 安装包一路默认即可。
3. 打开“以管理员身份运行”的 PowerShell，执行：

npm install -g superpowers

注意：如果不开管理员权限，Windows 上写全局目录时容易报权限错误；如果安装路径包含中文或空格，极少数情况下会引发脚本路径解析问题，建议保持默认安装位置。

4. 执行superpowers，正常启动后终端会打印地址，浏览器自动打开http://localhost:4237。如果浏览器没有自动打开，手动访问也行。

Windows 上最容易翻车的地方是 MongoDB 服务没有真正启动。装好后建议在“服务”面板里找到 MongoDB Server，确认状态是“正在运行”。如果启动失败，多半是安装时选择的数据库路径目录没有创建成功，去C:\data\db看一眼或者重新配置 service 的配置文件。

3.2 Linux（Ubuntu/Debian 系）下的部署过程

Linux 服务器部署是 Superpowers 最实用的场景，装好之后团队所有人通过浏览器访问，体验接近 SaaS。我的步骤：

先装 MongoDB，用官方 apt 源：

curl -fsSL https://www.mongodb.org/static/pgp/server-6.0.asc | sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-6.0.gpg echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] http://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list sudo apt update sudo apt install -y mongodb-org

然后把 MongoDB 设置成开机自启并启动：

sudo systemctl enable mongod sudo systemctl start mongod

Node 部分我推荐用 nvm 管理版本，避免系统包管理器自带的 Node 版本过旧：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts

最后安装并启动：

npm install -g superpowers superpowers

到这里，Superpowers 就监听在 4237 端口了。如果希望它作为后台服务稳定运行，可以写一个 systemd service 文件，内容大致如下：

[Unit] Description=Superpowers Server After=network.target mongod.service [Service] ExecStart=/usr/bin/superpowers Restart=always RestartSec=5 Environment=NODE_ENV=production [Install] WantedBy=multi-user.target

提示：systemd 文件里的 ExecStart 路径以which superpowers输出为准，不同安装方法路径可能不同。

Linux 部署还需要特别注意防火墙。如果用 UFW，执行sudo ufw allow 4237/tcp即可。不要顺手放开 27017，MongoDB 只需要本地访问。

3.3 macOS 上的快速安装

macOS 和 Linux 思路类似，但包管理更简单。先用 Homebrew 安装 MongoDB：

brew tap mongodb/brew brew install mongodb-community brew services start mongodb-community

Node 同样建议用 nvm 安装 LTS，然后执行npm install -g superpowers。之后在终端运行superpowers，浏览器访问http://localhost:4237。

macOS 上唯一要留神的是环境变量，如果你用 zsh，nvm 自动写入的是~/.zshrc，新开的终端窗口才能识别nvm命令。如果在终端里敲nvm提示命令找不到，先source ~/.zshrc。

3.4 安装完成后如何验证一切正常

光看终端输出还不够，我用三个命令和一次页面操作来确认系统健康：

systemctl status mongod

netstat -tlnp | grep 4237

curl -I http://127.0.0.1:4237

• MongoDB 服务必须是 active（running）；
• 4237 端口存在监听进程；
• curl 返回 HTTP 200 或 302 之类的响应都算正常，说明 Web 服务已经能接受请求。

之后在浏览器里注册第一个账号，这个账号拥有管理员权限。注册成功、能进入主页，安装流程才算真正结束。

4. 第一次打开 Superpowers：做一个能动的互动小玩意

4.1 注册账号与创建项目

首次访问http://localhost:4237会看到注册页面。第一个注册的账号是管理员，后续创建项目、管理用户都靠这个身份，所以密码别设得太随意。

注意：如果服务部署在公网上，任何人都能在注册页面创建账号并进入你的服务器。我见过有人开着默认配置放在公网上，结果被别人塞了一堆垃圾项目。理性做法是让 Team 协作时用内网，或通过 Nginx 加访问认证后再暴露到公网。

登录后点击创建新项目，项目类型建议选空白项目，等熟悉了再尝试带模板的示例。Superpowers 项目和传统游戏工程不一样的地方在于：它没有“打开文件”这一说，所有项目都在线保存，登录账号后从项目列表进入即可。

4.2 场景编辑器里的基础操作

进入项目后，界面主要分为三块：左下角是资源浏览器，中央是场景视图，右侧是属性检查器。别被和普通 IDE 稍有不同的操作习惯吓到，逻辑其实是一致的。

创建一个最小可玩场景按下面几步：

1. 新建一个场景，双击进入。
2. 在场景中创建一个 Camera Actor，它是玩家看世界的“眼睛”，没有相机的场景运行起来只会是一片空白。
3. 创建一个 Sprite Actor，这个对象通常会挂一张图片作为游戏中的物体。
4. 从资源管理器里拖入一张 PNG 到 Sprite Actor 的资源槽位，图片就显示在场景中了。
5. 在右侧属性面板里调整位置（X、Y、Z）和缩放，让物体出现在相机视野中。

一个容易忽略的点：场景坐标的 Z 轴默认是纵深方向，2D 游戏中通常把所有物体放同一平面，然后通过移动相机来实现画面视角切换。刚开始做调整时，如果画面里看不到刚创建的物体，优先检查它是否真的在相机视野范围内，而不是怀疑引擎坏了。

4.3 用 TypeScript 写一小段移动控制脚本

颜值先不管，先让物体“动起来”才算摸到门道。在资源浏览器中新建一个脚本文件，Superpowers 支持 TypeScript 语法，写完后把脚本组件拖到目标 Actor 上，运行项目就能看到行为生效。

一个非常基础的键盘控制脚本示例：

class PlayerBehavior extends Sup.Behavior { speed = 0.1; update() { if (Sup.Input.isKeyDown("LEFT")) { this.actor.move(-this.speed, 0, 0); } if (Sup.Input.isKeyDown("RIGHT")) { this.actor.move(this.speed, 0, 0); } if (Sup.Input.isKeyDown("UP")) { this.actor.move(0, this.speed, 0); } if (Sup.Input.isKeyDown("DOWN")) { this.actor.move(0, -this.speed, 0); } } } Sup.registerBehavior(PlayerBehavior);

这段脚本拆开来讲：

• class PlayerBehavior extends Sup.Behavior：定义一个行为类，脚本挂到 Actor 上以后，引擎会在这个 Actor 的每个逻辑帧调用update。
• speed：每秒位移量，实际上决定移动快慢的值，这里用的是每帧移动 0.1 世界单位，具体手感要进预览里调整。
• Sup.Input.isKeyDown：查询键盘按键状态，返回布尔值。
• actor.move：让当前 Actor 沿指定方向移动，修改的是本地坐标。

写完脚本后记得保存，保存快捷键一般是 Ctrl+S。然后点击编辑器顶部的“运行/预览”按钮，弹出窗口里按方向键就能看到物体移动。注意脚本保存后通常需要重新运行项目才会生效，别改了脚本不做任何操作就干等。

4.4 多人实时协作：邀请协作者进入同一个项目

这是 Superpowers 最亮眼的功能。把当前项目的链接发给另一个注册用户，对方登录后打开链接，就能进入同一个项目。此时你们两个人的场景视口是同步的：我在场景里拖一个 actor，你那边几乎同时看到；我改脚本里的某个数字，你也立刻能看到变化。

这种同步机制对团队的迭代方式影响很大。传统工作流里，美术改完贴图、程序员改完脚本地图再打包测试，信息在不同人手里流转会产生大量版本混乱。Superpowers 直接把整个项目当作一个共享文档处理，协作者之间的最新状态就是项目当前状态，不需要额外沟通“我改完了，你那边拉一下”。

协作时如果担心改坏东西，可以利用项目历史/快照功能，把出问题前的版本恢复回来。我在实际操作中习惯每隔一个阶段手动创建一次快照，相当于存档点，遇到灵感岔路或者误删资源时能快速回退。

5. 坑都替你们踩过一遍：高发问题与排查清单

5.1 MongoDB 启动失败或连接不上

现象：运行superpowers后终端提示数据库连接失败，或者页面一直转圈进不去。

排查顺序先看 MongoDB 进程是否存在：

systemctl status mongod

如果 not running，Windows 上打开服务管理界面检查 MongoDB Server 服务；Linux 上用journalctl -u mongod | tail -50看日志。最常见的原因是 MongoDB 数据目录没有权限或未创建，官方默认路径是/var/lib/mongodb。解决方式：

sudo mkdir -p /var/lib/mongodb sudo chown mongodb:mongodb /var/lib/mongodb sudo systemctl restart mongod

Windows 场景则去安装目录下查看mongod.cfg，确保dbPath指向的目录存在且当前用户有写权限。

5.2 浏览器访问不了 4237 端口

本地启动但访问不了，优先查端口监听：

netstat -tlnp | grep 4237

如果监听地址是127.0.0.1:4237，那说明服务只允许本机访问，外网无法进入。反向代理或云服务器部署时需要监听0.0.0.0；如果服务本身写死了监听地址，建议放在 Nginx 后面，让 Nginx 统一对外监听。

云服务器用户还要检查安全组入方向是否放行 TCP 4237。这个排查点看起来很低级，但我因为忘了放行端口白折腾了半小时，写在这里提醒各位。

5.3 多人协作掉线或状态不同步

现象：协作者偶尔操作无响应，刷新后又能看到对方改动，但实时光标不移动。

通常原因是 WebSocket 连接被中间网络设备中断。本地网络环境下基本不会出现，跨公网协作时比较常见。如果使用了 Nginx 反代，Nginx 默认对 WebSocket 的支持需要额外配置 Upgrade 头，不能直接套普通静态站点配置。建议在 server 配置块中增加：

proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";

这段配置的作用是告诉上游服务：客户端想保持长连接，不要按普通 HTTP 请求处理，这样 WebSocket 才能稳定穿透反向代理。

5.4 数据备份与升级注意事项

Superpowers 把项目文件都放在 MongoDB 里，所以备份策略非常直接，不需要去复制某台电脑的工程文件夹。

常用备份使用 MongoDB 自带工具：

mongodump --out /backup/superpowers_$(date +%Y%m%d)

恢复：

mongorestore /backup/superpowers_20250401

提示：升级 Superpowers 前务必先执行一次mongodump。虽然 npm 升级通常不会触碰数据库，但养成备份习惯能让你在任何升级事故中全身而退。

版本升级执行：

npm install -g superpowers@latest

然后在原目录下重新启动superpowers。如果升级后页面样式或脚本报错，优先清一次浏览器缓存，Web 编辑器升级后偶尔会因为旧缓存资源没刷新导致界面异常。

5.5 性能与安全层面的几个建议

最后聊两个容易被忽视的生产级配置：

• 尽量使用 HTTPS。如果通过公网访问编辑器，明文 HTTP 会让密码和项目数据在网络链路上裸奔。Nginx 配好证书后把 4237 反代出去即可。
• 不要在 MongoDB 27017 端口上做任何暴露。MongoDB 默认不加密，且很多用户不会修改默认账号，公网裸奔等于把数据库送人。
• 场景资源不要一次性导入超大图片或音频，编辑器不是专门的资源管理系统，动辄几十 MB 的文件会拖慢场景加载和同步速度。单张贴图控制在 2MB 以内是合理范围。
• 定期清理不再使用的项目和账号。项目多了以后 MongoDB 的数据量增长会变得非常快，备份和恢复的耗时会明显增加。

我在实际部署中最深的体会是：Superpowers 的定位不是和商业级引擎拼渲染能力，而是提供一种“低摩擦”的协作创作方式。把它跑在一台服务器上，给团队所有人一个浏览器链接，对方不需要装任何游戏引擎，不需要理解 Git 分支合并，打开页面就能上手改场景、写脚本。如果你需要搭一个教学实训环境、做远程原型协作，这套工具值得认真试试。

最后再分享一个小技巧：协作之前先在项目里约定好“谁主要管场景、谁主要写脚本”，虽然编辑器支持多人同时改同一个对象，但两个人都去拖动同一个 Actor 的属性面板还是会产生互相覆盖的体验。配合历史快照功能，给每个关键版本打一个存档点，能让协作过程稳得多。安装过程中如果卡在某个报错上，记录一下终端里那条具体的错误信息，对照上面几个模块去定位，基本都能在几分钟内找到症结。