“superpowers”这个词如果你最近在创客圈子、编程教学群或者游戏开发爱好者群里转一圈很可能会看到有人问“想要安装superpowers”“superpowers怎么用”之类的话。我第一次看到这个名词的时候第一反应是“这八成是个什么新出的效率工具或者健身课程”结果点进去才发现这其实是一个开源项目一套支持多人实时协作的创意编程环境英文名就是 Superpowers。简单说它就是一个可以让你在浏览器里做游戏、做交互应用、写代码还能邀请其他人一起同步操作的平台。服务端跑在你自己的电脑上客户端就是浏览器别人访问你的服务地址就能实时一块创作。说实话这类“一起写代码”的工具现在不少但 Superpowers 特别的地方在于它的定位很明确不追求做工业级的复杂 IDE而是把“协作、轻量、拿来就能用”做到极致。它尤其适合三种场景一是在学校里给学生上编程课老师开一个服务全班都连进来不用每台机器配环境二是在创客空间或工作室里几个小伙伴一起做游戏原型边做边互相看效果三是我个人最喜欢的一点它非常适合做“快速想法验证”写个简单交互、搭个 3D 场景基本是开箱即用。下面我就从我怎么拆解这个项目、到实际动手装、再到遇到的那些坑完整地跟你说一遍。1. 这个东西到底是什么Superpowers 的核心能力与应用场景拆解很多人一上来就急着找安装命令我觉得反而应该先花两分钟搞清楚这个软件的设计思路否则你装完之后大概率只会打开一个空白页面然后不知道要干嘛。我第一次用的时候也犯过这个毛病启动成功后就盯着浏览器发呆后来把它的核心逻辑理清了才真正觉得这工具很值。1.1 从一个“编辑器”变成一个“环境”Superpowers 不是传统意义上的“安装一个软件”它更像是一套完整的工作环境。它底层是 Node.js 写的一个服务端负责保存项目文件、运行服务器端脚本、管理多个用户的连接前端是跑在浏览器里的编辑器所以你不需要在每台机器上装客户端。这个“服务端 浏览器端”的架构是理解整个项目的一把钥匙。我第一次用的时候只知道敲npm start看到终端里弹出一行 “Starting server” 的日志就以为已经搞定了结果浏览器打开 127.0.0.1 才发现还需要创建账号。后来才明白服务端启动成功只是第一步后续的用户管理、项目创建都在 Web 界面里完成。也正因为是多用户架构它天然就支持协作不像传统 IDE 那样“单人单机”。1.2 三大核心编辑器与典型玩法Superpowers 里最主要的工作区有三大块2D 场景编辑器、3D 场景编辑器和脚本编辑器。你可以把它理解成一个剪辑软件里的不同工作区2D 和 3D 场景编辑器用来摆对象、调位置、搞层级关系脚本编辑器用来写逻辑。它默认支持 TypeScript 风格的代码编辑也支持可视化编程的方式来搭简单逻辑这对新手非常友好。实际上很多游戏工具都允许你用代码控制场景但 Superpowers 把这个流程做得特别顺你在 3D 场景编辑器里放一个立方体切到脚本编辑器里立刻能引用到这个对象改一个属性切回场景就能看到变化。我见过一个很典型的应用案例一个老师在班上开了一节“做一个小迷宫”的课他用 Superpowers 搭了一个简单的 3D 迷宫框架然后每个学生通过浏览器访问同一个服务地址各自创建自己的项目脚本拖动小球、编写移动逻辑互相还能看到别人的进展。学生们不需要装任何游戏开发环境只要有浏览器就行这个优势在现场教学里非常明显。1.3 服务器端脚本让协作从“分工”变成“同屏”除了常规的客户端逻辑Superpowers 还允许你创建服务器端脚本。这一点是它和很多本地运行的小工具最大的不同。客户端脚本负责每个浏览器里看到的画面逻辑而服务器端脚本跑在 Node 服务里可以用来做全局状态同步、消息广播、计分板这类只有服务器能实现的功能。我第一次接触这个概念的时候有点蒙后来想通了只要项目里需要一个所有用户共享的数据源就必须用服务器端脚本。比如你想做一个多人答题的互动页面每人浏览器上的倒计时要一致那倒计时的逻辑就得放服务器端如果只是各自飞机大战那写客户端脚本就够了。弄懂这个分层后面排查问题的时候也轻松许多。2. 安装前的准备环境选型与版本取舍“安装”这个词听起来很简单但如果你直接去 GitHub 拉代码然后npm install在 2024 年这个环境下大概率会碰到颜色不一样的错误提示。Superpowers 这个项目“年纪不小”更新节奏相对慢所以在动手之前先把环境选好很重要。这一步我没有好好准备结果途中浪费了将近一个小时在修依赖问题。2.1 Node.js 与 Git绕不开的前置依赖Superpowers 是一个基于 Node.js 的项目所以你的电脑上必须先装 Node.js 和 npmGit 则不是必须但强烈建议后面拉代码更新都用得上。这里有个关键点版本别一味追新。老项目在最新版 Node 上很容易出现原生模块编译失败的问题因为很多依赖包没跟上。我个人的建议是优先选择 10.x 或者 12.x 这种当时主流的 LTS 版本如果你本来机器上已经是 18 或者 20 这种高版本先别急着卸可以装一个 nvmNode Version Manager来做多版本切换装完 Superpowers 再切回去也不影响其他项目。装好了 Node 和 Git基本就算准备好了。Windows 用户建议把 Git 的“Use Git from the Windows Command Prompt”这个选项选上否则后面在命令行里敲git会提示找不到命令。2.2 Windows / macOS / Linux 三平台差异这套东西在三个平台上都能跑但各有各的小脾气。Windows 上最常遇到的问题是原生模块编译环境不齐全比如缺少 Visual Studio Build Tools 或者 Python导致 npm 在编译某些依赖的时候直接报错。macOS 上相对顺利一些但如果你是用 Apple Silicon 芯片的老朋友某些老模块可能没有对应架构的预编译包同样会走编译流程。Linux 服务器上跑是最省心的基本装好 Node 和 Git 就没事了这也是它比较适合部署在教室一台共用机器上的原因。我的建议很简单如果你只打算在自己电脑上体验一下哪个平台都无所谓如果你打算给别人提供访问那优先考虑拿一台 Linux 的小机器专跑这个服务稳定而且不会把你日常开发环境搅乱。2.3 端口与网络先想清楚访问路径再说默认情况下Superpowers 的服务端口是 4239启动成功后本机浏览器访问http//127.0.0.14239就能进入登录界面。如果你只想自己一个人玩到这里就结束了。但你要是打算让局域网里的人一起访问就必须考虑两个问题端口有没有被其他程序占用以及服务监听地址是不是只绑定了本机。这两点我在后面会详细讲这里先提个醒动手之前规划好“谁来访问、是同一个 Wi-Fi 下还是不同网络”能省掉很多不必要的麻烦。我就是一开始没想明白结果装好后在手机上怎么都打不开折腾半天才发现是监听地址的问题。3. 安装实操从拉取代码到浏览器打开的第一张画面好现在进入正题。这部分我给你一份我实际验证过的操作流程每个步骤后面我会顺带解释为什么这么做而不只是丢给你一坨命令。后面我遇到的问题和排查我也会原原本本写下来毕竟这东西光说不练是没用的。3.1 获取项目文件git clone 还是下载压缩包获取 Superpowers 源码有两种常见办法到 GitHub 项目页面下载 zip 包或者用 Git 克隆仓库。我给新手的建议是直接用 git clone因为后面你想更新项目、切分支、看改动记录都方便很多也方便你保留自己的本地修改。命令很简单git clone --depth 1 https//github.com/superpowers/superpowers.git加--depth 1的意思是只拉取最新的一个提交记录不会把整个历史都下载下来速度会快很多而且体积也小。如果你只是尝个鲜下载 zip 完全没问题不过如果下载完解压到一半文件缺失、或者文件路径太长导致 Windows 解压失败那就老实回到 git clone 路线吧。3.2 安装依赖npm install 背后的那些细节进入项目目录然后执行cd superpowers npm install这一步是整个安装流程里最容易出幺蛾子的环节。npm install 会把项目依赖的全部第三方包下载到本地node_modules文件夹如果网络不稳定这个过程中很容易出现超时、卡住或者静默失败的问题。我第一次装的时候npm 卡在一个叫node-sass的包上半天不动最后给我报了一堆编译错误我当时就愣了。解决办法有几个优先级可以排一下第一把 npm 的源切换到国内镜像比如 npmmirror 镜像站因为很多包的默认下载源在国外速度经常感人切换命令是npm config set registry https//registry.npmmirror.com装完依赖可以再切回官方源第二如果切换完还是报编译错误大概率是 Node 版本太新导致老模块不兼容这时候用 nvm 切换到 Node 12 的 LTS 版本删掉node_modules文件夹重新执行npm install基本能解决。第三如果你看到的是 Python、Visual Studio、C 构建工具相关的报错那跟代码本身没关系是系统缺编译环境Windows 用户装上 VS Build ToolsmacOS 用户装一下 Xcode Command Line Tools然后重试就行。这一关过了后面的路就好走了。3.3 启动与验证npm start 后到底发生了什么依赖装完之后执行npm start正常情况下终端会输出类似这样的日志Starting Superpowers server... Server is running at http//127.0.0.14239这时候打开浏览器访问http//127.0.0.14239第一次会看到一个创建管理员账号的界面。你填一个用户名和密码然后登录进去就正式进入 Superpowers 的工作台了。我在这里给你提个醒这一步设置的管理员账号别随手乱填因为后续的权限管理、项目配置都是以这个账号为基础的。我有一次为了测试随便输个 test/123456结果后面在系统设置里想改管理员信息还得翻半天文档特别后悔。第一次进入工作台后你看到的界面上会有一个创建项目的入口。先新建一个空项目看看里面的场景编辑器和脚本编辑器能不能正常打开能不能往场景里拖一个物体能不能在脚本里写一行console.log然后在控制台里看到输出。都正常了才说明安装是完整的而不是只“启动了服务”。这个验证步骤看起来基础实则很关键因为很多机器上 npm install 是带着半失败的依赖糊弄过去的表面能启动进去一操作就白屏。4. 多人协作与局域网部署把 Superpowers 真正用起来单机玩通了Superpowers 真正精彩的一半才刚刚开始。它最明显的优势是多人实时协作但这个优势能不能发挥出来取决于你怎么部署和配置网络。这一章我讲的是“从自己电脑用”到“让一群人用”的完整路径。4.1 绑定 IP 与端口让其他设备也能连进来前面说了默认服务只监听127.0.0.1这意味着只有你本机能访问其他设备在浏览器里输入你的机器 IP 是打不开的。要允许局域网访问你需要在项目配置里找到服务器监听的地址把它改成0.0.0.0然后重启服务。0.0.0.0的意思是监听本机所有网卡这样别人可以通过你的局域网 IP 访问如果你只希望某个具体网卡的设备能访问就填那个网卡对应的 IP。这个配置在哪个文件里不同版本略有差异但一般都在项目根目录或者配置文件里有一个server相关的字段。改完之后先用另一台手机连同一个 Wi-Fi在浏览器里输入http//你的局域网IP4239能看到登录界面就说明成功了。这里有一个很容易漏掉的操作Windows 防火墙会默认拦截这个端口的外部连接第一次被拦截时系统会弹出询问是否允许访问的窗口一定要点允许如果没弹出来就需要手动在防火墙里给 Node 或者对应端口放行。macOS 上偶尔也会有类似的网络权限问题在“系统设置 网络”里允许相关进程接入即可。这里我再强调一个细节局域网访问和“公网访问”是两个概念。我这里说的都是局域网场景比如学校机房、同一办公室 Wi-Fi。如果想让不同城市的人访问那就涉及到更多网络配置和服务器部署问题了不是这篇文章的重点。我自己一直把 Superpowers 用在同一个局域网的小场景里这个场景是最适合新手落地的。4.2 项目管理与数据备份storage 目录不能乱动Superpowers 里创建的每个项目都保存在项目的storage目录下项目里的场景、脚本、素材配置基本都落在这一坨文件里。理解这个消息很重要因为它的备份逻辑和普通“复制文件夹”不太一样。我强烈建议你不要在服务运行的时候手动去 storage 目录里拷贝文件因为运行中可能还有数据没有完全落盘直接复制容易复制出一份残缺的项目。正确的做法是先停掉服务再整个把storage目录压缩备份。恢复的时候也一样把备份的 storage 目录覆盖回去然后启动服务项目就回来了。这一点真的救过我一次有一次我临时换电脑没有通过导出功能而是直接按着“感觉”把整个项目文件夹复制走结果启动后发现项目列表是空的后来一看才知道少复制了一个带时间戳的子目录。所以现在我的习惯是涉及 storage 的拷贝或恢复一律先停服务、再整目录操作、然后启动服务三步缺一不可。4.3 实战场景一场小型的游戏开发教学课说一个我实际组织过的活动方便你理解这些东西串起来是什么样子的。上次我在一个小型社区工作坊带了一场两小时的“做一个小球滚动游戏”活动准备了大约八台电脑和若干手机、平板。我先在一台 Linux 笔记本上启动 Superpowers 服务把监听地址改成0.0.0.0然后把这台笔记本的局域网 IP 写在一张白纸上。参加的人打开浏览器输入这个 IP 就能进入同一个服务各自注册账号、创建项目。我作为管理员可以在系统界面看到在线用户列表也能在需要的时候直接打开某个用户的项目看看进度。整场活动下来最直观的感受是对于一个两小时的工作坊来说Superpowers 最大的价值不是“功能强大”而是“零安装、零环境配置、开个浏览器就能开始创作”。这对非技术背景的参与者特别重要因为大多数人不会想在活动前先装一遍 Node.js 和依赖包。5. 常见问题与排查技巧实录这部分可以说是我写这篇文章最想分享的精华部分。Superpowers 本身不复杂网上能找到的教程也多数停在“启动成功”这一步。但真正动手用起来之后你会遇到一堆跟代码逻辑无关的环境问题这里我把最常见的情况和排查思路整理成一个速查表方便你对照。现象可能原因排查与解决办法npm install 一直卡住或者报错网络下载慢、依赖源在国外切换 npm 镜像源后重试必要时删除 node_modules 后再 installnpm install 报 node-gyp 编译失败Node 版本过新、缺少编译环境用 nvm 切到 Node 12 或 10装好编译工具后重试启动后本机能访问其他设备访问不了服务监听 127.0.0.1 或防火墙拦截把监听地址改成 0.0.0.0检查防火墙放行相关端口端口 4239 被占用之前启动的服务没停干净找到进程杀掉或改用其他端口启动打不开项目列表服务没完全启动或者浏览器缓存旧刷新页面确认终端日志没有报错必要时重启服务多人同时编辑但看不到对方用户未登录或 WebSocket 连接异常重新登录刷新浏览器页面检查是否有多个服务进程5.1 端口被占用改端口还是杀进程如果你启动服务时终端提示端口 4239 被占用常见原因是上一轮服务没正常退出。Windows 下可以在命令行运行netstat -ano | findstr 4239查看占用端口的进程号然后去任务管理器结束对应进程macOS / Linux 用lsof -i 4239查看 PID再kill -9 PID干掉它。如果你不想杀进程改端口也可以在配置里找到端口号改成 4240后面访问就用新端口。我的习惯是能杀就杀因为改端口之后我还得换一个访问地址有点不划算。5.2 npm install 失败先看镜像和版本这个是我踩过最深的坑也几乎是用这个项目的必经之路。除了前面提到的换镜像和切 Node 版本我再补充一个检查项安装完依赖之后看看node_modules里面有没有个别包没有完整下载下来最典型的特征是启动服务时报某个模块找不到。遇到这种情况简单粗暴的办法就是删掉node_modules重新执行npm install。别老想着精准修复那个坏掉的包对于这种老项目全量重装往往比修修补补更快更干净。5.3 启动后浏览器打不开先分“本机”还是“局域网”问题浏览器打不开第一件事不是怀疑服务挂没挂而是分清楚“打不开的什么地址”。如果是http//127.0.0.14239打不开大概率是服务本身没启动成功回终端看有没有报错如果是http//你的局域网IP4239打不开那问题多半出在网络层面。用手机连同一个 Wi-Fi 访问如果还不行八成是监听地址或防火墙问题。这个排查顺序能让你少走很多弯路我给不少人解决过类似问题有人折腾了半天最后发现是手机和电脑不在同一个网段。5.4 我踩过的几个坑与最终结论最后总结几条我个人的血泪经验第一备份时永远先停服第二高版本 Node 不是不能用但遇到问题请先想到版本兼容第三第一遍跑通之后别急着把服务挂后台先在浏览器里完整创建一次项目、写个简单脚本再离开。这样做的好处是你能在环境还热乎的时候发现潜在的依赖残缺问题而不是等要用的时候才傻眼。Superpowers 这个项目给我最大的感觉是它不是一个“装完就跑”的玩具而是一套可以长期摆在工作室角落里的创作工具。它不追求炫酷的界面也没打算取代主流游戏引擎但在“一群人一起开一个网页马上开始做点什么”这件事上目前我还没有找到比它更顺手的方案。如果你只是在网上看到一句话“想要安装 superpowers”那么希望这篇文章能让你一次装通并且真正把它用起来。