1. 先搞清楚：“superpowers”到底是哪个项目
最近后台收到不少“superpowers 怎么装”的私信，打开搜索页一看，这个词的热度确实上来了。但你搜 superpowers 会看到好几样同名的东西：一套协作式 HTML5 游戏创作框架、一个 VS Code 里的 AI 助手扩展、还有各种叫 Superpowers 的效率小工具。名字一样，方向完全不同，装错地方很容易白折腾。我这篇内容主要围绕大多数人在“想要安装 superpowers”这个语境里真正想装的东西：由 Two Scoops Games 开发并开源的Superpowers——一套免费、可自托管的协作式游戏与互动作品创作平台。
这款工具解决的核心问题是“一群人不用装客户端，打开浏览器就能一起做游戏”。以往做游戏，每个人必须在本地配好引擎和项目版本，改完代码再想办法合并。Superpowers 的做法是把服务器架在自己机器上，所有参与者通过浏览器连进同一个项目，改场景、改脚本、调资源都是实时同步的，体验类似于用在线协作文档做游戏。
什么人适合看这篇文章？如果你是想快速做 2D 游戏原型、想做视觉小说或互动网页作品、甚至只是在学校作业里需要一个“两个人同时改一个游戏项目”的演示环境，这套东西非常值得装一次。本文会从架构原理讲到完整安装实操，再带一个最简单的可运行小项目，最后把我踩过的坑列成清单。先提醒一句：安装本身不难，难的是理解它为什么这样工作。理解之后，遇到问题你能自己判断，而不是到处搜“为什么连不上”。
2. 先看架构：玩不明白的安装全是瞎折腾
很多人在安装 Superpowers 时卡住，根本原因是把它当成一个普通游戏引擎来装。实际上它不是一个“打开就能点运行”的桌面软件，而是一套浏览器客户端 + Node.js 服务端的架构。先把这个搞清楚，后面每一步你都看得懂。
2.1 浏览器只是遥控器，Node 服务端才是大脑
Superpowers 的官方定位是“协作式游戏制作工具”。它的使用方式是：你在一台机器上启动服务端，然后任何人在浏览器里打开服务端地址，就能看到编辑器界面。这个界面长得像一套完整的游戏 IDE，有资源面板、场景编辑区、脚本编辑器和属性面板，但它本身不承担项目存储和逻辑构建的重任。
真正干活的是背后的 Node.js 服务端。项目文件、资源索引、脚本编译、版本状态都由服务端统一管理。用一个生活化的类比：浏览器是餐厅里的点餐平板，服务端是后厨。你在平板上下单、改菜，后厨收到指令后统一排单出菜。如果只盯着点餐平板质疑“为什么没有锅”，方向就错了。
这一点直接解释了为什么 Superpowers 能在浏览器里实现多人协作——不是靠插件把编辑功能塞进浏览器，而是服务端天然支持多客户端连接。每个浏览器窗口都是一个客户端，服务端维护“当前项目应该长什么样”的唯一真相。任何一个人改动，都会广播给其他客户端。
2.2 WebSocket 实时同步：为什么不是保存后才有动静
用过传统版本控制工具的人可能习惯“改完保存再提交”，但 Superpowers 不是这个模型。它的客户端与服务端之间长期维持着一条 WebSocket 连接，所有编辑操作都以增量消息的形式实时推送。
比如你在场景编辑器里把一个角色从坐标（0, 0）拖到（10, 0），客户端并不会等“保存”按钮，而是立刻把这次坐标变化打包成一条消息发给服务端，服务端再广播给同一项目里的其他人。这个过程在网络正常时几乎是零感知延迟。这也是为什么它敢叫“实时协作”，而不是“协同编辑后手动合并”。
在安装和部署时，这个架构带来的直接影响是：如果你打算让局域网里的同事一起用，必须保证服务端的 WebSocket 端口对所有人都可达。不是只开一个网页端口就完事，防火墙策略要同时放行端口的 HTTP 与 WebSocket 通信。我后来在“常见问题”部分会专门讲这种连接失败的处理。
2.3 脚本为什么用 TypeScript 而不是 Lua 或 JavaScript
Superpowers 的脚本层选用了 TypeScript。对于做过 Unity 的人，Lua 是一种轻量脚本选择；对于网页项目，原生 JavaScript 似乎更顺理成章。但 Superpowers 选择 TypeScript 的核心原因是“协作友好”和“类型安全”。
多人同时改一个项目，脚本之间最容易出现“改了接口不影响就没察觉，直到运行崩了才发现”的情况。TypeScript 提供类型检查，任何一个人改了函数签名，其他人还没运行就能在编辑器里看到报错。浏览器本身不认识 TypeScript，服务端会在脚本保存后实时编译成 JavaScript，再推送给所有连接的客户端。这个编译发生在服务端起进程的时候，所以服务端是否正常启动、Node 环境是否健康，直接决定了你在编辑器里写脚本能不能编译通过。安装阶段最值得检查的就是 Node 版本和依赖是否完整，而不是一上来就纠结编辑器里某个按钮找不到。
3. 安装前准备：环境检查与版本选择
先别急着敲命令，我这里把安装前要做的三件事按顺序说清楚。它们看起来基础，但我在帮别人排查时发现，绝大多数“装不上”的问题都出在这一步。
3.1 三种运行方式，先想清楚你要哪一种
Superpowers 实际有三种跑起来的路径：
- 官方 Launcher 客户端：从官网下载对应系统的安装包，装完由 Launcher 自动拉取并启动服务端和客户端。这是最省事的方式，适合只打算做项目、不想碰代码的人。
- 源码构建：从 GitHub 拉取仓库，自己安装 Node 依赖并启动。适合想改平台本身、想自定义服务器行为、或者想在无桌面环境的服务器上运行的人。
- 在线托管版：直接用官方提供的在线服务，不用装任何东西。但项目数据在别人的服务器上，不推荐用来做严肃项目。
我自己的建议很明确：如果你是第一次接触，且主要在本地或个人小团队场景使用，优先走源码构建。原因有三：能看到完整启动日志，出问题容易排查；不受 Launcher 的自动更新绑架；学习架构最好的方式就是直接看代码跑起来。
3.2 环境要求与一条命令自查
源码构建的核心依赖是 Node.js。老版本的 Superpowers 对 Node 版本非常敏感，装太新的 Node 可能出现依赖编译失败。根据我目前测试的经验，建议使用 Node 18 或 20 的 LTS 版本，比较稳。Node 版本管理用nvm，不要直接去官网装固定版，否则以后切换版本很痛苦。
打开终端，先执行这三个命令确认环境：
node -v npm -v git --version三个命令都有输出，且 Node 是两位数的大版本（比如 v18.20.2），基本就算准备好了。接下来确认目标端口没被占用。Superpowers 服务端默认监听 5010 端口，具体端口以当前版本的配置文件为准，但排查方法通用。
macOS 和 Linux 用：
lsof -i :5010Windows 用：
netstat -ano | findstr 5010如果看到有进程占用，可以先检查是不是自己上次没关干净的实例，也可以考虑换端口。换端口的事情后面实操篇我详细说。
3.3 安装路径的两个隐藏坑
第一，路径里不要有中文、空格和特殊符号。这一点听起来像老生常谈，但 npm 的某些依赖在构建原生模块时，遇到非 ASCII 路径真的会莫名失败。我自己就遇到过在“我的文档”下建项目文件夹，结果npm install卡在node-gyp编译的情况。把项目放在~/dev/superpowers或D:\dev\superpowers这种纯英文路径下，能避免一大半问题。
第二，npm 镜像和权限问题。国内用户建议把 npm 源切到可用的镜像源，但不是所有镜像都能正确处理某些原生依赖的二进制下载。切源命令是：
npm config set registry https://registry.npmmirror.com如果安装过程中报权限错误，不要下意识加sudo npm install。正确做法是检查 npm 全局目录的权限，或者用 nvm 安装 Node 后让 npm 把全局包装到用户目录里。加sudo装出来的 node_modules 经常会在后续启动时出现权限不一致的诡异错误，排查起来非常浪费时间。
4. 完整安装实操：从拉代码到打开编辑器
环境检查完毕，下面进入正式安装。我走的是源码构建路线，所有命令都在终端里执行。这里给的是通用步骤，具体仓库分支和启动脚本以后可能调整，遇到差异时以仓库 README 为准。
4.1 拉取主仓库
首先把整个仓库克隆下来：
git clone https://github.com/superpowers/superpowers.git cd superpowers需要注意，这是一个聚合仓库，里面包含了服务端、浏览器客户端以及相关工具包。你不用手动去分别克隆多个仓库，主仓库已经把核心子包组织好了。克隆完成后可以用ls看一下目录结构，重点留意有没有package.json和类似server、app的子目录，这能让你对整个布局有个印象。
4.2 安装依赖
在仓库根目录执行：
npm install这一步会安装聚合仓库自身的依赖，并且按需处理子包依赖。如果网络状况不理想，可能会有几个包反复失败，此时最有效的办法是重试，而不是逐个手动下载。
这里要说明一个常见误区：npm install输出里出现warning不代表失败，也不需要每个都去解决。只有出现error且伴随红色错误栈，或者最终退出码非 0，才需要处理。很多新手看到一堆 warning 就慌了，实际上那些大多是镜像过期、deprecated 提示，不影响服务启动。
如果安装过程中提示缺少某个原生模块的编译环境（比如node-gyp相关错误），在 macOS 上执行xcode-select --install，在 Ubuntu 上安装build-essential，Windows 上需要保证 Visual Studio Build Tools 已安装。把 Node 版本切换到 LTS 通常也能规避不少编译问题。
4.3 启动服务端
依赖装完之后，查看根目录package.json的scripts字段，了解启动命令的定义。最常见的启动方式是在根目录执行：
npm start或者在某些版本里是：
npm run server启动成功的标志不是终端窗口挂起，而是日志里出现类似“Server started on port 5010”的信息。此时打开浏览器，访问：
http://localhost:5010首次打开会看到一个引导页面，让你创建服务端的管理员账号。这个账号只用于管理这台服务器上的项目，不会上传到任何第三方。创建完成后，你可以新建项目、创建世界、进入编辑器。如果你只打算本机使用，到这里安装就算完成了。
4.4 让局域网其他人也能访问
如果你希望同局域网的人也能通过浏览器加入项目，需要让服务端监听对外地址，而不是只监听本机。默认配置通常已经绑定了所有接口，你只需让对方在浏览器里访问你的局域网 IP 加端口：
http://192.168.x.x:5010查局域网 IP 在 macOS 和 Linux 用ipconfig getifaddr en0，Windows 用ipconfig。这一步最常栽跟头的是系统防火墙。Windows 联网时通常会弹出“是否允许此应用通过防火墙”，不小心点了拒绝，外面就永远连不进来。解法是到防火墙设置里把 Node.js 或对应端口设为允许，或者临时关闭防火墙测试连接是否恢复。
4.5 补充：官方 Launcher 的装法
不想碰命令行的朋友可以用官方 Launcher。下载安装后，它会自带一套完整的运行时环境，打开 Launcher 就能看到启动按钮。首次启动它会询问服务端的数据目录位置，建议放在一个空间充足、路径简单的地方，比如D:\superpowers-data。
Launcher 的好处是更新方便，坏处是出了问题时你能看到的日志很少。我用过一段时间，后来还是回到源码方式，因为至少能清楚地看到服务端到底是在哪个环节挂掉。如果你只是尝鲜，Launcher 完全够用；如果你打算把它作为团队工具长期跑，源码方式更值得投入时间。
5. 第一个小项目：30 分钟跑起来一个可移动角色
安装成功只是起点。我知道很多人走到打开编辑器这一步后，看到满屏英文面板反而不知道干什么。这里用一个最简单的 2D 小项目带你走通“建项目—建场景—放角色—写脚本”的完整链路。
5.1 新建项目并认识四个核心面板
在服务端引导页创建一个新项目，命名为一个英文名，比如FirstProject。进入编辑器后，你会看到几个主要区域：项目导航区、场景视图、资源面板、属性面板。新手最容易忽略的按钮是“新建场景”——你不会自动进入一个默认场景，必须手动创建。
点击资源面板里的“新建场景”，命名为MainScene，双击打开。你会发现场景视图里有一个网格区域，这就是你的游戏世界。此时切到项目导航区，找到场景对象，确认当前场景已被设置为启动场景。这一步不设置，后面运行游戏时引擎不知道从哪开始。
5.2 创建一个角色对象
在场景视图中右键，选择“创建 Actor”（创建游戏对象）。把它命名为Player。接着在属性面板中给这个 Actor 添加一个Sprite组件，这样才能让它显示为一个可见的图片对象。Superpowers 自带了一些基础素材资源，你可以在资源面板里找到，也可以自己导入一张简单的 PNG 图片。
把图片拖到 Sprite 组件对应的资源槽里，场景视图中应该会立刻显示出这个小角色。此时你可以用鼠标在场景里拖动它，观察属性面板里坐标和旋转值的变化。这就是 Superpowers 里所有对象的基本逻辑：Actor 是容器，组件赋予它能力，脚本负责控制行为。
5.3 写一个最简单的移动脚本
在资源面板新建一个脚本资源，命名为Movement，双击打开脚本编辑器。写入下面这段代码：
class Movement extends Sup.Behavior { speed = 3; update() { const dt = Sup.Input.getDeltaTime(); if (Sup.Input.isDown("LEFT")) this.actor.moveLeft(this.speed * dt); if (Sup.Input.isDown("RIGHT")) this.actor.moveRight(this.speed * dt); if (Sup.Input.isDown("UP")) this.actor.moveUp(this.speed * dt); if (Sup.Input.isDown("DOWN")) this.actor.moveDown(this.speed * dt); } } Sup.registerBehavior(Movement);这段代码的逻辑很简单：每帧调用update，检测方向键，按方向乘以速度再乘以帧间时间，得到相对位移。Sup.Input.getDeltaTime()是关键，它拿到了两帧之间的真实时间差，这样速度就不会被帧率波动影响。不同版本的 API 可能有细微差异，但整体模式一致。
脚本保存后，回到场景视图，选中PlayerActor，在属性面板添加Behavior组件，把刚才写好的Movement脚本挂上去。到这里，你已经完成了“给角色装配脚本”这个动作。
5.4 运行与实时协作测试
点击编辑器顶部的运行按钮，此时应该会在新页面里启动游戏。按方向键，你的人物就动起来了。如果角色没出现，优先检查 Sprite 组件是否没绑对图片，以及场景是否被设为启动场景。
协作测试更有意思：在同一台机器上再打开一个浏览器窗口，访问同一个localhost:5010项目地址，你会发现第二个人也能同时看到资源面板里的改动。你在第一个窗口里把角色拖到右上角，第二个窗口几乎同时能看到角色位置变化。这种实时同步效果就是 Superpowers 最核心的卖点，值得给团队演示一次。
我自己测试时发现，多人同时在同一个场景里拖动同一个 Actor 时，会出现“抢方向盘”一样的抖动。这不算 bug，而是协作文档的常见行为。实际使用时建议分工：一个人负责场景摆放，另一个人负责脚本和数据表，避免碰同一个对象。
6. 常用问题排查与避坑记录
这部分是真正花时间换来的经验。我把安装和使用过程中最高频的问题整理成了一个速查表，附带具体处理思路。遇到问题时先对照表格，解决不了再去看日志。
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 启动后页面打不开 | 服务端未启动成功或端口被占用 | 查终端日志，确认监听端口；用lsof/netstat看端口占用 |
| npm install 失败 | 网络波动或镜像源不稳定 | 切换 npm 源后重试；不要加 sudo 安装 |
| 脚本保存后编辑器报编译错误 | TypeScript 语法问题或 API 版本差异 | 看错误提示定位行号；查阅当前版本的 API 文档 |
| 浏览器打开后一直空白加载 | 浏览器缓存了旧版本客户端 | 强制刷新（Cmd+Shift+R / Ctrl+Shift+R）或清除缓存 |
| 局域网设备连不上 | 防火墙未放行端口 | 手动放行 Node.js，或临时关闭防火墙测试 |
| 脚本运行后角色不动 | Behavior 没绑定到 Actor | 回到场景选中 Actor，属性面板里确认挂载了脚本 |
| 多人协作时改动冲突 | 两个人同时改同一个对象 | 约定分工，避免同时编辑同一个 Actor 或场景 |
如果你遇到页面能打开但始终显示连接中，最值得怀疑的是 WebSocket 握手被阻断。这种情况一般不是代码问题，而是网络层面把升级协议拦了。最简单的验证方法是在同一台机器上用另一个浏览器访问，如果正常，那就是跨设备的网络问题。
还有两个中国用户特别容易踩的坑值得单独说。第一个是项目路径含中文导致的编译失败，前面已经强调过。第二个是编辑器里输入中文脚本注释时，偶尔会出现输入法把符号自动改成全角的情况。全角括号、全角分号在 TypeScript 里都是非法字符，报错会让你以为是自己逻辑写错了。经验是脚本里先不写中文注释，等熟悉语法后再加。
另外，我建议养成一个习惯：每次修改结构性的东西（比如调整项目目录、升级 Node 版本）之前，备份服务端的数据目录。Superpowers 把项目数据直接存在服务器上，不像传统引擎那样每个项目自带完整工程文件。数据目录一旦损坏，恢复的成本很高。我的做法是写了一个简单的定时任务，每天把数据目录同步到一个备份盘。
7. 最后分享我的实际体会与后续方向
玩了一小段时间 Superpowers 之后，我的感受是：它不适合作为重型商业游戏引擎的替代品，但在“快速原型、团队协作、教学演示”这几个维度上非常好用。如果你带着“我要做个商业级 3D 大作”的期待来装，大概率会失望；但如果你只是想验证一个玩法、做一次趣味互动、或者让几个朋友同时体验一把做游戏的过程，它比传统引擎顺手得多。
我个人的建议很简单：别先刷一遍文档再动手。建一个空项目，把场景、资源、脚本、行为组件全部拖一遍，哪怕做出来的东西很蠢也没关系。踩过几个坑之后再回头看架构说明，很多之前不理解的问题会一下子串起来。这种“先跑起来再理解”的路径，我用在好几个新工具上，都比从头啃文档高效。
后续你可以继续深挖几个方向。第一是研究服务端数据目录的结构，理解项目文件是如何被组织的，这对备份和迁移很有帮助。第二是尝试自己部署到公网服务器上，配合域名和 HTTPS 让外网伙伴加入项目。第三是探索脚本里更多 API，比如碰撞检测、动画播放和音效控制，这些是让原型变得有趣的起点。任何一个小方向都能单独写篇文章，但先把基础装好、跑通、弄明白机制，后面的路就顺了。
安装这件事本身不复杂，但架构认知是关键。希望这篇内容帮你少走弯路，顺利跑起你的第一个 Superpowers 项目。
