superpowers自托管指南：搭建实时协作的3D开发环境

1. 认识 superpowers：它不是魔法，是你自己的协作创意工坊

我第一次听到 superpowers 这个名字，是在一个做独立游戏的朋友那里。他跟我说自己搭了一个服务，团队四个人窝在三个城市，浏览器一开，就能在同一块 3D 场景里拖模型、写代码、调灯光，鼠标光标都能看到彼此的移动轨迹。我当时第一反应是：这八成又是什么重量级商业协作平台，一打听才发现，这是个开源项目，可以自己部署。

superpowers 说白了，是一个以浏览器为操作界面的协作式 2D/3D 开发平台。它和传统“装一个厚重编辑器、然后各自开发再合并”的流程完全不同，整个编辑器和运行环境都跑在服务端，客户端只需要一个现代浏览器。打开页面，你能直接开始创建场景、放置物体、编写 TypeScript 脚本，队友只要拿到同一个服务地址，就能实时进入同一个工作区。这种模式放在今天看来，多少有点像是给“创意协作”这件事准备了一个专属的、可以自托管的在线工作台。

这篇文章的目的是把“安装 superpowers”这件事从头到尾讲明白。我会从部署前的选型思路、实际安装过程、第一次操作界面的核心概念，到用 TypeScript 给一个 3D 场景里的角色加上移动逻辑，再到常见的故障排查，按我自己的实操顺序写下来。适合的人群很明确：想自己搭一个协作式可视化开发环境的人，带学生做 3D 入门项目的人，以及独立游戏或小团队想低成本共用一个创作环境的人。如果你只是想找个“在线游戏制作工具”玩玩，那可以直接用公共在线版，不必折腾自托管；如果你想让它成为团队内部稳定可用的基础设施，那这篇文章应该能帮上忙。

我自己踩坑最多的地方，往往不在功能本身，而在“环境怎么搭”和“多人同时编辑时怎么不互相踩脚”这类实际问题上。这些经验，常规教程里很少写，我会在后面专门整理。

2. 安装 superpowers：部署前的思路与选型

2.1 先想清楚：你要源码运行，还是要容器化部署

安装一个服务之前，最忌讳的就是脑子一热直接敲命令。superpowers 的部署方式可以根据团队的使用情况分成三种，我可以直接说结论：

第一种是本地开发机运行。适合你自己一个人体验，或者临时拉个团队试用，打开命令行跑起来，用完就关，没有任何负担。代价是机器不能随便关，别人要访问时，你得把服务绑到局域网 IP 上。

第二种是服务器正式部署。把自己的一台云主机或者家里的迷你主机当作长期服务端，保持 7×24 小时运行，团队随时能连。这种方式的好处是稳定，坏处是你需要对 Linux 环境、进程守护、数据备份稍微有点概念。

第三种是 Docker 容器运行。用容器把服务端、数据目录、网络端口一次性封装好，升级和迁移都方便，非常适合正式环境。如果你所在团队已经习惯用 Docker Compose 管理服务，我强烈推荐这种。

我当时选的是第三种。原因很直接：我不想在一台服务器上留下一堆散落的依赖，而且以后想换机器，直接搬容器配置文件就行，不用重新装环境。很多自托管项目都提供了官方镜像，superpowers 的官方仓库里资料虽然不算丰富，但用容器方式部署是完全可行的。

2.2 服务器环境怎么准备，心里要有数

不管用什么方式装，一台能跑 Node.js 环境的机器是刚需。superpowers 服务端的核心是一个 Node.js 进程，客户端的构建产物也是通过它来提供的，所以你要是连 Node 都没装，那后面什么都起不来。

就我个人测试的经验来说，1 核 2G 内存的入门云主机，跑一个小团队使用的 superpowers 实例已经够用了。你可能会觉得奇怪，一个听着像“游戏引擎”的东西，怎么需求这么低。因为真正的渲染是放在浏览器里做的，服务端主要负责场景数据同步、脚本逻辑运行和静态资源分发，压力并没有想象中那么大。当然，如果你的场景极其复杂，或者同时在线十几个人做协作，建议至少 2 核 4G，硬盘留出 20G 以上，因为模型、纹理这些资源会慢慢累积。

这里有必要提一个容易被忽略的点：端口规划。superpowers 服务端默认会监听一个端口，浏览器访问时就是http://你的服务器IP:端口。如果你打算长期用，最好在系统防火墙和安全组里把这个端口放行。我遇到过很多“安装成功但打不开”的案例，排查到最后都是云控制台的安全组规则没配好，纯属低级失误。

Node.js 版本方面，不要装太老的，建议用当前主流 LTS 版本。版本过低会导致某些依赖编译失败，版本过高又可能出现兼容性提示，所以先用 LTS，后面基本省心。

2.3 源码部署实录：从下载到启动

如果你选的是源码方式，操作路径大概是这样的。先从项目官方渠道获取最新的源码包，这里我以常见的 Git 方式为例：

git clone https://github.com/superpowers/superpowers.git cd superpowers

接下来是安装依赖。superpowers 这类项目依赖列表通常很长，我用的是 yarn，因为它在处理这种大型依赖树的时候，比 npm 更容易保持版本一致性。如果项目根目录有yarn.lock，那就说明官方推荐 yarn：

yarn install

依赖装完以后，先别急着启动。你得确认项目里有没有配置文件或者环境变量说明，比如服务端监听端口、数据库地址、静态资源路径。superpowers 的常见配置并不复杂，如果没有特殊需求，默认配置也能跑起来。

然后启动服务端：

npm start

或者某些版本会用yarn start，具体以你拿到的项目说明为准。启动成功后，命令行会显示一行访问地址。我通常会把服务绑定到0.0.0.0，这样局域网内的其他设备也能访问；如果只绑定了127.0.0.1，那就只有服务器本机能打开，其他同事都会一脸懵地跑来问你要地址。

浏览器打开地址，看到一个项目列表页面，就说明服务端基本活了。后面我会专门讲第一次进入后需要做哪些事情。

2.4 Docker 部署：更省心的备份与升级方案

源码部署最大的痛点是升级麻烦。拉新代码、装依赖、重启，三步缺一不可，遇到依赖冲突时更头疼。Docker 方式则可以把这个过程收敛成一个镜像重建操作。

一个比较通用的思路是，自己写一个 Dockerfile，把整个项目打进去。我那次实际用的 Dockerfile 模板大概是这样的：

FROM node:16-buster-slim WORKDIR /app COPY package.json yarn.lock ./ RUN yarn install COPY . . EXPOSE 4237 CMD ["npm", "start"]

里面端口号是按我当时项目监听端口来的，如果你的版本不同，就改成实际端口。构建镜像：

docker build -t my-superpowers .

然后运行容器：

docker run -d --name superpowers \ -p 4237:4237 \ -v superpowers-data:/app/data \ my-superpowers

我特意挂载了一个数据卷，因为项目数据如果全放在容器内部，一旦容器删了，你辛苦搭的几周场景资源就全没了。用-v挂载出来，以后升级只需要重新 build 一个新镜像，再把旧容器替换掉，数据还在，团队的损失可以降到最低。

如果你习惯 Docker Compose，也可以用类似下面这种配置管理：

version: '3' services: superpowers: build: . ports: - "4237:4237" volumes: - superpowers-data:/app/data volumes: superpowers-data:

这些配置不是官方标准模板，而是从实践中总结的通用部署结构，具体文件路径和端口参数要以你拿到手的那份源码为准。但思路是通用的：对外只暴露一个端口，内部数据沉淀到一个持久化目录。

3. 第一次打开 superpowers：界面与核心概念

3.1 从主页进入工作区：三步搞定

服务启动后，我习惯先把自己机器上的浏览器打开，输入http://localhost:4237。第一次看到的界面通常是一个项目列表，里面要么是空的，要么有几套示例项目。我当时是先选了个示例项目打开，因为我更习惯从“能跑的东西”反推它的底層逻辑。

进入项目之后，你会看到一个大工作区。左侧一般是资源面板，中间是场景视图，右侧是属性面板，顶部可能还有运行按钮、停止按钮和项目设置。如果你用过 Unity 或 Godot，对这个布局不会太陌生；如果没有，可以把它想象成“可视化编辑器 + 代码编辑器 + 播放器”三种东西的合体。

打开示例项目后，我建议哪都别乱改，先点一下“运行”按钮，看看它在浏览器里的实际效果。菜单、按钮、运行时提示信息，这些都是让你熟悉这套工作流程的引路人。运行不起来也没关系，大概率是浏览器问题，换 Chrome 或 Edge 试试，基本能解决。

3.2 理解场景、资源与Actor的关系

上手 superpowers 之前，有几个高频概念必须先弄清楚，否则后面操作会像无头苍蝇一样。

第一个是“场景”。场景就是游戏或应用里的一块独立空间，一个项目里可以有多个场景，不同场景之间可以通过脚本来切换。我习惯把它理解成“一套房子的各个房间”，客厅、卧室、厨房都是独立空间，但共享水电网络。

第二个是“资源”。模型、贴图、声音、脚本文件，统统属于资源。资源面板就像仓库，你可以把做好的 fbx 动画、png 纹理、音频素材都丢进去，然后在场景里引用它们。

第三个是“Actor”。Actor 是场景中所有实体的统称。你可以把 Actor 理解为“一个有名字的空盒子”，刚开始它什么都没有。你需要往这个空盒子上挂“组件”，比如网格渲染组件让它显示形状，光源组件让它发光，脚本组件让它有行为逻辑。

很多科班教程一上来就讲组件系统，容易把人绕晕。我的理解方式是：场景是舞台，Actor 是舞台上的演员，组件是演员身上的装备和台词，脚本则是演员的行动逻辑。这样的比喻可能不精确，但足以帮你快速建立心智模型。

3.3 别急着手写代码，先试着拖一个方块出来

我第一次上手，做了个很无聊的事：在场景里创建了一个方块，然后到处拖拽，观察坐标是怎么变的。这个过程看着很小白，但非常值得。

点场景里的空白处，创建一个新的 Actor，然后在属性面板找到它的变换组件（Transform），设置它的位置、旋转和缩放。位置就是它在空间里离原点多远，旋转决定它朝向哪边，缩放决定它是大是小。把这三个值拖一下，场景视图里物体会立刻跟着变化，这种即时反馈能让你迅速建立“属性改变 → 结果改变”的直觉。

接着在这个 Actor 上添加网格渲染组件，你会看到方块变成一个有颜色的实体。再添加一个点光源，调整颜色和强度，你会发现方块表面开始有了明暗变化。这时候你基本已经理解 superpowers 的“组件是功能的载体”这一设计逻辑了。

如果你在这一步什么都没做出来，先检查是不是把组件加错了。比如你想在 3D 场景里显示物体，却用了 2D 场景的组件，那当然不行。创建项目的时候分清楚“3D 项目”和“2D 项目”，后面操作就会少很多低级问题。

3.4 多人协作是它的灵魂

单独一个人用 superpowers，它只是一个不错的网页版编辑器。但真正的得分点在于“多人实时协作”。

当你的服务端部署好之后，只要把服务地址发给队友，他们打开浏览器就能进入同一个项目。你会看到他们的光标、视角、选中对象都是实时共享的。这背后其实是服务端维护了一个共享模型，每个人在编辑器里的操作都会广播给其他人，再通过状态同步保证各方看到的内容一致。

这种机制对团队来说非常舒服。以前我们做原型，改一版传给另一个人看，中间还有“导出、截图、传网盘”这些环节。现在只要大家都在编辑器里，你拖一下模型，他那边马上就能看到，沟通成本直接砍掉了一大截。

不过协作也有要注意的地方：别同时改同一个脚本文件。虽然编辑器做了同步，但多人在同一文件里互相覆盖修改，还是会产生混乱。我后来形成的工作习惯是：场景搭建阶段大家随意动，写代码阶段一人负责一个文件，碰事前先语音说一句，避免撞车。

4. 用 superpowers 做一个可以跑的 3D 小场景

4.1 搭场景：从灯光到地面，先让画面有手势

折腾完基础概念，我想让你跟着我做一个能跑起来的小场景。目的不是做一个完整的游戏，而是把“创建、编写、运行”这条完整链路走一遍，之后你想扩展成什么方向，都会顺手很多。

新建一个 3D 项目，然后先做三件事：开灯、铺地、放一个主角。开灯的理由很朴素：没有光，场景里全是黑的，什么都看不见。创建一个点光源或方向光，把方向和强度调一下，让场景亮起来。铺地则是为了避免视觉上没有参考系，可以创建一个巨型薄长方体，或者用平面组件也行，重点是有个东西让你知道“地面在哪”。

然后创建一个立方体 Actor，把它当作主角。名字我一般会改成一个有意义的，比如“Player”，而不是留着默认名字。这一步看似不重要，其实后面脚本要用它，名字一乱，逻辑就不好找了。

把场景保存好，点运行，你至少应该能看到一个被光照亮、站在地上的方块。到这一步，编辑器层面的操作就没问题了。

4.2 用 TypeScript 给 Actor 添加行为

superpowers 的脚本组件支持 TypeScript。你不用被这个名词吓到，它本质上就是带类型提示的 JavaScript，写法和普通前端脚本几乎一致。

创建一个脚本资源，把它挂到 Player 这个 Actor 上。脚本启动后，你可以先从最简单的逻辑开始：让方块按键盘方向键移动。我当时写的核心逻辑是这样的伪代码思路：

• 在update事件里检测键盘输入；
• 根据方向改变 Actor 的位置；
• 判断边界，别让方块掉出地面范围。

放到实际代码语境里，你需要拿到当前 Actor 的位置，加上一个“位移量”，然后赋值回去。位移量 = 速度 × 时间增量。时间增量这个概念，老手都会强调，因为它能保证游戏在不同帧率下移动速度一致，不会出现性能好的机器上飞一样、性能差的机器上爬一样的情况。

写完脚本后，回到编辑器点“运行”，你的方块就应该能跟着键盘动起来了。如果没反应，优先检查脚本是不是挂错 Actor 了，以及事件名是否拼写正确。这类问题占新手调试里的七成。

4.3 让角色动起来之后，再想想视角怎么跟着走

角色能移动之后，马上就会遇到一个新需求：镜头要跟着角色跑。如果不跟，按一下按键，角色瞬间跑出屏幕，你都不知道它去哪了。

在 superpowers 里处理镜头跟随的常规做法，是让镜头 Actor 和角色建立关系，或者挂一个专门控制镜头的脚本。最简单的一种方式，是每帧把镜头的位置设置为角色位置加上一个固定偏移。这样镜头永远固定在角色斜后方，移动起来很像第三人称视角。

这个过程中你会接触到另一个核心概念：坐标系的变换。角色移动是世界坐标下的移动（“世界坐标系”指整个场景的全局坐标），镜头偏移则是相对角色的偏移。理解这两者的区别后，不管是做第一人称还是第三人称，你的思路都会清晰得多。

我当时在这个环节卡了很久，原因是角色的移动方向没考虑旋转。角色转到左边，按“前进键”却还是沿着世界坐标的 Z 轴移动，看起来就像角色在横着走。后来把移动方向改成基于角色自身朝向的局部坐标系，问题才解决。这个坑我记得很清楚，后面专门写进排查部分。

4.4 把做好的场景分享出去：导出和部署思路

自己本地能跑，和能让别人也打开，这是两回事。superpowers 的项目最终可以构建成可发布的网页应用，构建产物是一堆静态文件。你可以把这些文件放到任何支持静态托管的服务上，也可以直接让服务端继续提供预览地址。

我一般会在项目完成到稳定可演示的程度后，先给同事发一个服务端链接，让他们在浏览器里直接打开。这种实时预览的方式效率很高，因为不需要他们装任何东西。

如果你想进一步把作品变成一个独立的在线页面，比如挂到自己的个人网站里，那就要了解项目构建命令。具体命令取决于官方文档，不同版本会有差异，我通常的做法是到项目源码目录下的构建脚本或说明文件里找，很少凭记忆硬敲。构建产物生成后，整个目录就是一个可用的网页应用，复制到任意服务器就能跑。

这里有个经验值得分享：发布前一定要清掉调试信息和未使用资源。我见过有人把几百 MB 的原始素材全塞进发布包，结果页面加载慢到让人失去耐心。精简之后，加载速度完全不是一个档次。

5. 实际运行中的高频问题与排查建议

5.1 浏览器打不开服务页面，先查端口和安全组

“服务端明明启动了，但浏览器访问不到”，这是安装类的自托管工具里最常见的求助内容，superpowers 也不例外。

先把问题拆成几个环节：服务端是否真的在监听端口，我们可以在服务器上直接访问本地地址。如果本机curl http://127.0.0.1:4237能返回内容，说明服务端本身是好的；如果本机都访问不了，那就检查启动日志，看是不是报错后进程已经退出了。

本机访问正常，但局域网或公网访问不了，那问题大概率在防火墙和云安全组。很多云主机默认只放行了 80 和 443 端口，自定义端口一律不通。安全组规则里增加一条：放行 TCP 端口4237（改成你的实际端口）即可。

还有一种隐蔽情况：服务绑定的地址不是0.0.0.0，而是127.0.0.1。这就等于服务只对服务器自己开放，外部网络自然进不来。启动配置里把监听地址改成0.0.0.0，重启后再试，通常都能解决。

5.2 场景一复杂就卡顿，先分清是服务端还是浏览器的问题

有人一碰到卡顿就怀疑是服务器性能不行，其实多数时候压力都在浏览器端。superpowers 的渲染是在浏览器本地执行的，一个复杂场景里如果有大量高模、动态光照、实时阴影，再怎么堆服务器配置也救不了浏览器端的渲染压力。

排查思路是这样：先看运行状态里的 CPU 占用。如果你在场景里拖动物体都很流畅，但点“运行”之后特别卡，那瓶颈通常在渲染逻辑，比如模型面数太高、光源数量太多、角色脚本里有高频运算。优先精简资源：把不需要实时光照的地方改成烘焙贴图，把距离镜头很远的物体降低显示精度。

如果连编辑器操作都卡，那才需要考虑服务端性能或网络延迟。服务端卡多表现在操作响应延迟，而不是渲染帧率低。这两者容易混淆，我建议出现卡顿不要急着加钱升级配置，先定位卡在哪一端。

5.3 依赖安装失败，常见问题和处理路径

源码部署时，yarn install跑一半报错，这种问题几乎每个人都遇到过。依赖安装失败的常见原因就那么几类：网络不稳定、Node 版本不兼容、某些原生模块需要编译却缺少构建工具。

网络不稳定这个好理解，项目依赖来自不同渠道，下载中途断流就会失败。可重跑一次安装命令，或者配置镜像源，能解决大半问题。Node 版本不兼容则需要看你拿到的是哪个版本的项目，有的项目要求特定大版本，装个版本管理工具切换到对应版本就好了。原生模块编译失败，一般会在日志里提示缺python或make之类，装上对应系统工具包，再重试即可。

这里我给一个建议：不要一报错就跑去问“怎么解决某一条具体报错”，先把完整日志读一遍。很多时候报错原因在日志中上部就写明了，只是被一长串堆栈信息盖住，你不往前翻就看不到。

5.4 多人协作不同步：先看服务器连接和文件冲突

多人协作时，最常见的场景是“一个人动，另一个人看不到变化”。这种情况通常不是编辑器本身坏了，而是双方其实没连到同一个服务端。有人可能连的是localhost，有人连的是局域网 IP，虽然界面看起来一样，但不是同一个世界。

确认方法很简单：让所有人都看一眼同一个物体，改一下它的位置，看其他人那边有没有跟着变。如果全都不变，多半是连错了服务地址；如果部分能变、部分不能变，那就是个别成员的浏览器缓存或连接出了问题，刷新页面重新进入即可。

另一个问题是多人同时编辑同一个脚本文件，导致互相覆盖。我在项目里会提前约定好脚本文件的所有者，谁负责哪个逻辑，谁就有该文件的编辑权。不要图方便，大家都挤在一个文件里改，救急一时，后面 merge 起来想哭。

可以做个简单的问题速查表：

6. 写在最后：真实使用后的几点体会

如果你也准备安装 superpowers，我个人最想强调的一句话是：别把它默认成“游戏引擎”，它是一个“协作环境”。它的价值不在于渲染效果能跟商业引擎比肩，而在于“一群人围着同一个场景实时修改”的磁场效应。我们团队用它做完过一个小型 3D 展示页面，技术复杂度不算高，但约定速成的协作体验让人印象深刻。

第二点体会是，部署这事本身不难，难的是把使用规则定下来。安装方式千篇一律，但项目命名规范、场景资源分类、脚本文件归属，这些都得提前约好。我那时候没有强调，结果几个人一天生产了一堆叫untitled-1、untitled-2的资源，后期整理到崩溃。

最后再分享一个从实践中悟到的小技巧：尽量让团队成员都从“新建一个最小项目”开始熟悉，而不是一上来就打开复杂的示例项目。复杂示例会让你迷失在细节里，反而没法建立一套自己的思路。从一个有灯、有地面、有一个能移动的方块开始，跑通整个流程，再一步步往里面加东西。你会发现，所谓的“超级能力”，其实都是一个个小循环串联起来的熟能生巧。