企业官网建设流程全解析

如果你搜“superpowers”这个词，大概率会跟我当初一样，看到一堆同名概念，但你最终想找的，多半是一个能直接“安装”的软件。我这边要聊的，就是这个在浏览器里跑完整个游戏开发流程的开源平台 Superpowers。它最狠的地方不是某个特效，而是让你和队友打开同一个网址，就能在一个项目里实时协作改场景、改脚本、看效果，从工具层面把游戏开发里“版本管理混乱、联调效率低”的老毛病压下去。

Superpowers 官方定位是自托管（self-hosted）的 HTML5 游戏开发平台，用 TypeScript 写逻辑，2D、3D 都能做，安装方式和普通 Node.js 应用差不多。如果你正在纠结“要不要装、怎么装、装完能干嘛”，这篇文章就把我这几年的实际操作经验全倒出来，从环境准备到三种安装方式，从启动服务到多人协作，再到高频排障，一次讲透。

1. Superpowers 到底在解决什么痛点——一句话和一张表说清楚

1.1 从“一人一个文件凑一起”到“一起改同一个文件”

做游戏，尤其是小团队做游戏，最折磨人的往往不是玩法设计，而是协作流程。传统做法是美术出图、策划配表、程序写逻辑，最后通过 Git 拉分支合代码。听起来正规，实际玩起来，光是“我这边本地跑不起来”“你改的素材我这边没拉下来”“场景文件冲突了”这几件事，就足够把一个下午耗掉。

Superpowers 的逻辑是反过来的。它把项目资源、场景编辑器、代码编辑器、运行预览全部塞进浏览器里，团队所有人访问同一个服务器地址，打开的就是同一个项目。你看得到我鼠标放在哪里，我改完代码你那边立刻就能跑起来。这体验很像几个人同时编辑一篇在线文档，只是这次编辑的不是文字，而是一个完整的游戏项目。

我第一次用这个平台时，最直观的感受是：开会的效率完全变了。以前开会要先把最新构建拉下来、再各自本地跑一遍，现在大家直接对着浏览器里同一个画面说事，改哪里点哪里，改完当场验证。对于 Game Jam、原型验证、教学演示这类需要快速迭代、人员不固定的场景，这个优势非常致命。

1.2 技术底座：TypeScript、Three.js 与 Node.js 各管哪一块

想知道 Superpowers 好不好装、装完怎么调，得先大概知道它内部是怎么组织的。它分为服务端和浏览器端两部分。

服务端是一个 Node.js 应用，负责管理用户账号、保存项目数据、通过 WebSocket 把各个编辑器的操作实时广播给其他协作者。简单说，它就是一个数据库加消息中枢。客户端则是浏览器里跑的编辑器，基于 Three.js 做 3D 渲染，2D 场景也走同一套引擎体系。项目脚本统一用 TypeScript 编写，浏览器端负责实时编译和运行。

这种架构带来的一个直接结果是：你不需要在每台电脑上装任何游戏引擎或 IDE，只需要一台机器跑服务端，其他人全部通过浏览器访问。这也是为什么它特别适合团队固定服务器部署——服务端装一次，所有同事零安装使用。

1.3 它和 Unity、Godot、Phaser 到底差在哪

很多人会问，既然有 Unity、Godot 这么成熟的引擎，为什么还要折腾 Superpowers？我把几个常见方向的差异整理成一张表，你看完自己判断。

结论很明确：Superpowers 不是要替代大型引擎，它解决的完全是另一个层面的问题——让一群人能在一个浏览器页面里“同时动手”。如果你就是想要个能快速协作、免安装、还能跑完一个完整小游戏的工具，它很合适；如果你想做大型商业游戏，还是回去用 Unity 或者 Godot。

2. 安装前的环境准备：版本与工具链有哪些坑

2.1 Node.js 版本选择：官方要求与实测差异

Superpowers 的安装依赖 Node.js。比较早期的官方文档要求的是 Node.js 6.x 那个时代的版本，但你我都清楚，现在谁机器上没个 Node 16 起步。实测下来，我在 Node 16 和 Node 18 上都启动过服务，项目能建、能编辑、能跑。不过要留意，平台里有些老依赖在构建阶段会甩一些警告，多数不影响最终运行，但强迫症看着确实难受。

我的建议是别用太新的版本，也别用太旧的版本。稳妥区间是 Node 14 到 Node 18，再大版本如果你不想折腾，建议用 nvm 切一下。Windows 下也可以用 nvm-windows，macOS 和 Linux 直接用 nvm 就行。

# 安装 nvm（macOS/Linux） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash # 装一个稳妥版本 nvm install 16 nvm use 16

装完可以用node -v确认。别小看这一步，我遇到过几个人卡在启动报错，最后发现是 Node 版本太新，个别原生模块编译不过去。

2.2 浏览器、端口与网络环境的硬性条件

服务端跑起来之后，所有人都要通过浏览器访问。浏览器官方推荐 Chromium 内核的浏览器，比如 Chrome、Edge，Firefox 也能用。这套平台依赖 WebSocket 做实时同步，如果你的网络环境里有复杂代理、强隔离防火墙，WebSocket 连接可能会频繁断开。实测最舒服的场景是纯局域网——服务器和开发机在同一个内网，所有人直连 IP 访问，延迟低、连接稳定。

端口方面，Superpowers 默认端口是 4237，没什么特殊含义，就是个普通端口，但容易被其他开发服务占用。后面我会单独讲端口冲突的处理。

2.3 三分钟自检清单

为了避免装到一半才发现问题，我习惯先跑一遍环境自检。你在装之前，把下面这几项过一遍，基本能排掉 90% 的坑。

• Node.js 已安装，版本在 14 到 18 之间
• npm 正常可用，能访问第三方依赖源
• 4237 端口未被占用
• 目标机器磁盘空间至少留 1GB，项目文件会持续增长
• 浏览器建议用 Chrome 或 Edge
• 如果团队多人用，确认每台开发机都能访问服务器的 IP 和端口

检查端口的命令也很简单，Linux/macOS 用lsof -i :4237，Windows 用netstat -ano | findstr 4237。

3. 三种安装方式实测：全局、本地、源码哪个适合你

3.1 全局安装：最适合尝鲜的一条路

如果你是个人想体验一下，或者只是临时搭个环境看看效果，全局安装是最快的一条路。npm 包名就叫superpowers，一条命令装完。

npm install -g superpowers

安装完成后直接执行：

superpowers

服务就会启动，控制台会打印出访问地址，默认是http://localhost:4237。浏览器打开这个地址，首次访问会让你配置管理员账号，之后就进入主界面了。

这种方式的优点是省事，缺点是升级和依赖管理没那么干净。sudo或者管理员权限装的时候如果报权限错误，可以用npm config get prefix查一下安装路径，把全局路径改成当前用户有权限的目录，别硬用管理员权限覆盖。

3.2 本地安装：适合团队固定服务器部署

如果你打算在团队内部长期跑一个协作服务器，我更推荐本地安装。所谓本地安装，就是把命名空间收进项目目录里，所有数据、配置、依赖跟着项目走，备份迁移都清晰。

mkdir superpowers-server cd superpowers-server npm init -y npm install --save-dev superpowers

装好之后，启动命令而不是直接用全局二进制：

npx superpowers

和全局安装的区别是什么？本地安装的版本被锁在package.json里，团队想复现同一套环境就非常方便——把项目目录拷到新服务器，npm install一遍就拉齐版本。我之前做团队服务器就是用这种方式，后面接手的人一看package.json就知道服务端依赖是什么，不用靠脑子记环境。

3.3 源码构建：想研究底层就这么干

第三条路是从 GitHub 拉源码自己构建。适合两种人：一是你想改平台本身的功能，二是你发现安装包跑起来有问题，想看看到底卡在哪个模块。

git clone https://github.com/superpowers/superpowers.git cd superpowers npm install npm run build npm start

源码构建的时间会明显长一些，因为要编译的东西多。构建过程里如果报缺少某某依赖，先别慌，基本都是 Node 版本问题，把版本切回 Node 14 或 16 再构建一次。

我自己只在排查一个扩展加载问题时走过源码构建，说实话，对绝大多数用户来说不是必须，但如果你喜欢折腾，这条路能让你对这个平台的内部结构有更完整的认识。

3.4 三种方式横向对比与我的选择

如果让我只推荐一个：团队用，选本地安装；个人尝鲜，全局安装足够。源码构建属于折腾型需求，普通用户不必碰。

4. 启动服务与创建第一个 2D 项目

4.1 启动命令与默认配置说明

启动命令很简单，就是superpowers或者npx superpowers。首次启动后，服务端会把基础配置和用户数据写到启动目录或用户目录下的数据文件中。不同版本路径不完全一样，我本地实测是在~/Superpowers之类的目录里，Linux 系统下主要是~/.superpowers这样的隐藏目录。你可以在启动日志里看到它在读哪个路径。

如果你要修改默认端口，可以在启动时加参数指定，也可以在配置文件里改。我习惯在配置里固定端口，避免同事每次访问都要问是不是换了端口。

superpowers --port 8080

浏览器访问http://localhost:8080，其他机器访问http://你的IP:8080。如果访问不了，先查服务器防火墙有没有放行对应端口，这个问题在后面排障章节会细说。

4.2 在浏览器里创建第一个 2D 项目

首次打开页面，会让你创建一个管理员账号。这个账号是超级用户，负责管理项目、用户和权限。创建完进入主界面，左边是项目列表，右边是操作区。

新建项目时，要选项目类型。这里有一个容易忽略的点：2D 和 3D 项目依赖不同的扩展模块。有些构建版本会默认装好官方扩展，没有的话需要在扩展管理里找到对应的 2D/3D 扩展并启用。我建议先建一个 2D 项目练手，资源、对象、脚本关系比较直观。

建好项目进入编辑器，你会看到场景视图、资源面板、对象层级面板和脚本面板。在资源面板里新建一个场景，双击进入场景编辑，然后在场景里添加一个 Sprite 对象，给它指定一张图片或者一个默认的图形资源，就得到了我们说的“角色”。

4.3 小试牛刀：给角色写一个移动脚本

场景里有了角色，接着就要让它动起来。在资源面板里新建一个脚本资源，Superpowers 的脚本是 TypeScript 编写的，基本结构像这样：

class MoveBehavior extends Sup.Behavior { speed: number = 0.05; update() { this.actor.move(0, this.speed); } } Sup.registerBehavior(MoveBehavior);

把这段脚本挂到角色对象上，启动预览，角色就会在场景里持续移动。update方法每帧调用，this.actor.move是引擎提供的位移方法。speed变量可以直接在编辑器的属性面板里调，不用重新改代码——这个机制对设计同学非常友好，改数值就像调音量一样顺手。

预览运行后，如果没看到效果，先检查脚本有没有保存、有没有挂到场景对象上，这种问题 90% 是操作步骤没到位，不是代码写错。

5. 多人实时协作：这才是安装它的真正动机

5.1 实时协作的底层逻辑：WebSocket 与操作同步

Superpowers 的多人协作机制，拆开来看其实不复杂。服务端维护一个 WebSocket 连接池，每个编辑器操作都会打包成一条消息广播给同一项目里的其他人。你的同事在拖一个精灵位置、在改一行代码、在资源管理器里新增图片，这些操作会以非常细的粒度实时同步到每个人的界面上。

体验上最接近的就是在线文档。你能看到其他人的鼠标和选中状态，能感觉到“他不是在等我保存，而是在和我同时修改同一个文件”。对于游戏项目这种资源类型多、修改频率高、对象间依赖关系复杂的东西，这种细粒度同步比 Git 来回合并要顺手得多。

5.2 局域网团队服务器的搭建步骤

团队协作之前，先把服务器环境搭好。我用本地安装方式演示一遍：

1. 在服务器上完成 Node.js 环境安装和本地项目初始化
2. 启动npx superpowers服务
3. 查一下服务器内网 IP，Linux 下用ip addr，Windows 用ipconfig
4. 同事浏览器访问http://服务器IP:4237
5. 首次访问需要注册账号，管理员在后台把账号加入项目并分配编辑权限
6. 所有人在同一项目上开始工作

这一步最容易失败的地方是网络层面。服务器防火墙如果开了，记得放行对应端口，Windows 上有时候还需要在专用网络设置里开启“文件共享和打印”以外的规则。我踩过一次坑：服务明明起了，同事就是访问不了，最后发现是云服务商安全组规则没加，纯局域网测试根本发现不了。

5.3 多人同时编辑时冲突了怎么办

听起来“实时同步”就不应该有冲突，实际上当两个人同时修改同一个对象的同一个属性时，还是有覆盖的可能。Superpowers 的做法和其他协作文档类似——后到的写入会覆盖先到的结果。但因为它有操作级同步，冲突往往只发生在非常精确的同一毫秒级操作上，实际遇到频率很低。

真碰上了也别慌。平台会保留一定历史版本数据，理论上可以通过备份恢复。更重要的是养成习惯：场景里的宏观结构调整，比如删除对象、改层级关系，提前在群里打个招呼；脚本文件尽量分工到人，两人同时改一个文件就是自找麻烦。协作工具解决的是流程摩擦，不解决人的分工问题。

6. 高频问题与排障记录：从安装到运行我踩过的坑

6.1 npm 安装失败与下载慢的通用解法

装这个过程，第一道坎往往不是平台本身，而是 npm 的下载速度和网络稳定性。如果你机器在国内或者公司网络环境一般，npm install -g superpowers卡半天是常态。

通用解法是换 npm 源，把官方源切到国内镜像，速度会快很多。

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

装完可以再切回去，或者直接留着也行，看个人习惯。如果装了中断、报 ENOENT、EACCES 这类错误，大多是缓存损坏或权限问题，依次试：

npm cache clean --force # 权限问题则重设全局目录 npm config set prefix "$HOME/.npm-global"

别一上来就想着卸载重装 Node，先清理缓存和检查权限，多数问题能解决。

6.2 数据备份：Superpowers 的项目存在哪里

这个平台的用户数据、项目数据和配置信息都存在服务端本地文件里，而不是数据库里。所以备份思路很简单：把服务端的数据目录整体复制一份就够了。

不同版本路径不完全一样，我见过两种情况，一种是服务启动目录下直接生成数据文件夹，一种是在用户主目录下。稳妥做法是启动时看一眼控制台日志，它会告诉你数据目录具体在哪。我定期做备份的方式就是写个 cron 任务，把整个数据目录打包压缩加密存到另一台机器。项目做大了再后悔没备份就晚了，这个习惯值得养成。

6.3 端口占用与页面打不开

页面打不开最典型的原因就是端口被占用。superpowers启动时如果提示端口被占用，要么换端口，要么找出占用进程处理掉。排查命令：

lsof -i :4237

拿到进程 PID 之后，确认是不是你的其他开发服务，能停就停，不能停就换端口启动。换完端口记得让同事也换地址访问，不然他们打开的还是老地址，自然连不上。

6.4 新版 Node.js 下的兼容性警告

这个平台的一些依赖比较老，在过新的 Node.js 版本下构建或启动时，偶尔会提示error: unknown option或者某模块编译失败。如果你自认环境没问题，遇到这类报错，第一反应应该是切 Node 版本，而不是去改源码。

我目前用的方案是 Node 16，跑这个平台基本顺滑。如果你必须用 Node 20 以上的版本，也能跑，但要做好心理准备会多一些杂音。Windows 上如果遇到编译报错，大概率是缺少 Python 或者 C++ 构建工具链，安装 VS Build Tools 可以解决大部分原生模块编译问题。

整体来说，Superpowers 不算一个文档完善、社区活跃的主流工具，但它把一个很前卫的协作理念真正落地了，而且安装过程比起 Espruino 那一类折腾型开发者工具来说，已经算温和。我到现在还会偶尔启动它，不是为了长期在上面开发商业项目，而是每当团队新朋友问“有没有一个工具能让我们边讨论边改游戏”时，我仍然会第一个把它推过去。装一次十分钟，就算最后不用，也能刷新一次你对浏览器能力上限的认知，不亏。