★ FEATURED ARTICLE 最近有两个朋友几乎同时来问我同一个问题Superpowers 到底怎么安装一个说“我下载了个压缩包双击没反应”另一个说“npm 装完找不到命令”。我第一反应是他们多半搜到了不同的东西。Superpowers 这个名字在开源社区里被好几个项目共用但最贴近“想要安装 superpowers”这个搜索意图的应该是那个开源的、基于浏览器的协作式 HTML5 游戏开发环境。它不是一个普通 App不会给你一个安装包双击完成而是跑在 Node.js 上的一套本地服务装好之后用浏览器打开就能开始做游戏。这篇记录就围绕这个项目展开安装前要准备什么、我实际执行了哪些命令、第一次启动要注意什么以及我在装它时踩过的一组比较典型的坑。适合自己动手写过一点网页、又从来没试过 Web 游戏开发工具的人参考。哪怕你最后不打算长期用把这一整套流程走一遍对理解“开源 Web 工具怎么装”也有帮助。1. 先弄明白 Superpowers 定位再动手也不迟1.1 它不是游戏是“做游戏的工作台”很多人第一次听到 Superpowers以为是某种超级英雄题材的游戏。其实它是一个面向 HTML5 游戏开发的开源环境核心思路很反直觉开发工具本身跑在浏览器里。你在自己电脑上启动一个本地服务然后打开浏览器访问这个服务就能进入项目管理界面、编辑场景、写脚本、实时看预览。更特别的是它从设计上就支持多人协作别人不用装任何客户端只要在同一个网络里打开同一个地址就能和你一起编辑同一个项目。我用一个生活化的类比来解释大部分游戏引擎像是一台带全套工具的车间你要走进车间才能干活Superpowers 更像是把车间搬到了网页里任何有浏览器的人通过地址就能进到这个虚拟车间里一起动工。所以它的“安装”本质上不是安装一个桌面软件而是搭起一台服务再通过浏览器接入。这个定位决定了后面所有步骤的走向。1.2 它和 Unity、Godot 的主要区别同样是做游戏Superpowers 跟主流的 Unity、Godot 走的是完全不同的路线。我做了一个简单的对比方便你判断它适不适合自己对比项SuperpowersUnity / Godot使用方式浏览器访问本地服务桌面 IDE多人协作原生支持实时协作主要单机部分协作方案要额外配置上手曲线可视化编辑加上少量脚本编辑器本身就有一定学习成本资源占用浏览器为主比较轻编辑器本身较重发布目标HTML5 网页为主多平台原生应用典型场景Game Jam、教学、快速原型完整游戏项目、跨平台发行如果你的目标是做一个小游戏快速验证玩法然后发一个网页链接给朋友试玩Superpowers 是顺手的。如果你想把游戏打包成安卓应用或者 Steam 上的桌面游戏那还是老老实实用 Unity 或 Godot。1.3 谁适合装谁可能装了也吃灰我实际装完并玩过一段时间之后对它的适用人群有很明确的判断。适合装的人通常符合下面至少一条想体验“在浏览器里做游戏”不打算上来就学一套重型引擎。有一个固定小团队想远程一起改同一个游戏场景不想频繁地用网盘传工程文件。电脑配置一般跑不动 Unity 这种大块头。做编程或者游戏设计相关的教学需要一个低门槛、能多人同时进来的演示环境。不太建议装的人也有几种目标是做大型 3D 游戏需要复杂的物理系统和完整的资源管线Superpowers 会显得吃力。完全不想碰代码希望所有逻辑都用图形化拖拽完成。Superpowers 虽然有可视化部分但写脚本还是绕不开的。想找一个“装完就能立刻导出到手机”的工具它的导出方向主要还是网页。另外提醒一句市面上搜索“superpowers 安装包”可能会找到一些个人重新打包的版本。我的建议是优先从 GitHub 仓库获取第三方打包经常缺少依赖或者捆绑了不该有的东西。1.4 别把“安装”想得太重我见过不少人在安装这一步就卡住了其实是被“安装”这两个字带偏了。它不需要写入注册表不需要配置系统环境变量也不需要安装驱动程序。你需要做的核心事情只有三件装好 Node.js把项目代码拉下来然后启动服务。后面的问题都会围绕这三件事展开。想清楚这一点接下来就顺了。2. 安装前必须确认的三件事环境、浏览器与端口既然把话说在前面了安装过程不复杂但准备工作里面有几个细节特别容易被忽略。我把它们单独列出来讲是因为我身边至少有两个人是在这一步上栽了跟头导致后面报错的时候绕了很久。2.1 Node.js 必须装而且版本别太激进Superpowers 的服务端是用 JavaScript 写的运行在 Node.js 上所以第一步就是把 Node.js 准备好。这里有个大坑并不是 Node.js 版本越新越好。有些依赖包在老版本上编译过换到太新的 Node 上反而会报错。我建议装 LTS 长期支持版也就是各大系统包管理器默认推荐的稳定版而不是最新版。装完之后打开终端确认一下node -v npm -v这两个命令能正常输出版本号说明 Node.js 和 npm 都就绪了。如果没有输出先检查是不是安装路径没加到环境变量里。2.2 Git 不是必须的但它能帮你省事严格来说你也可以直接在 GitHub 页面下载 ZIP 压缩包然后解压使用不装 Git 也能装完。但我还是推荐先装 Git原因很简单你之后想更新版本就不用重新下载整个压缩包直接在项目目录里执行git pull就能拉取最新改动。确认一下 Git 是否已经存在git --version如果没有Windows 上装 Git for WindowsmacOS 上可以直接用 HomebrewLinux 上一般一条包管理命令就解决了。2.3 浏览器最好选 Chromium 系注意 WebGL 开关既然开发环境跑在浏览器里浏览器本身就成了“工作台”。我实测下来的经验是优先用 Chrome 或 Edge也就是 Chromium 系浏览器兼容性最稳。Firefox 也能跑但在一些细节上不如 Chromium 系省心。另外还要注意 WebGL。WebGL 简单说就是网页调用显卡绘制画面的通道Superpowers 的 3D 预览和部分 2D 渲染会用到它。如果你发现打开场景之后是一片空白或者黑屏大概率不是程序坏了而是浏览器禁用了 WebGL。怎么检查在浏览器地址栏输入chrome://gpu或者edge://gpu查看 WebGL 那一行是否是“Hardware accelerated”。如果显示“Software only”说明显卡加速没生效去浏览器设置里把“硬件加速”打开然后重启并刷新页面。2.4 端口、防火墙和局域网访问服务启动之后会监听一个本地端口你在浏览器输入http://localhost:端口号就能访问。这里有一个容易忽略的点如果你只是想在本机体验那什么都不用管但如果你想发给同一个小伙伴一起协作或者部署到一台服务器上就涉及端口和防火墙。我遇到过的典型情境是启动日志明明打印了地址手机在同一 WiFi 下却打不开。最后排查下来是系统防火墙默认阻止了非本机连接。解决办法很简单在防火墙规则里放行这个端口或者干脆允许 Node.js 进程对外通信。如果我们需要检查端口占用在 Linux 或 macOS 上可以用lsof -i :端口号Windows 命令行里用netstat -ano | findstr 端口号这里我不写死具体端口号因为不同版本和配置启动的端口可能不同。最可靠的判断依据是启动日志它通常会在启动成功后打印当前服务的访问地址你以那个地址为准就行。3. 从源码把 Superpowers 跑起来的完整过程环境准备完毕下面就是实际安装的重头戏。我用的是目前最通用也最好排查问题的源码安装方式过程就四步拉取代码、安装依赖、启动服务、浏览器打开。3.1 拉取项目代码先在本地准备一个干净的目录专门放这个项目。我习惯这么做而不是直接放到桌面或者下载文件夹里mkdir -p ~/dev/superpowers-lab cd ~/dev/superpowers-lab git clone https://github.com/superpowers/superpowers.git cd superpowers这里有一个忠告项目路径里尽量不要有中文和空格。虽然现代 Node.js 对中文路径的兼容性比以前好很多但一旦某个原生依赖编译失败排查起来就会很痛苦。我经历过一次最后把项目挪到全英文路径下才顺利装完所以推荐一开始就规避。拉取完成后先看一眼目录结构确认package.json文件存在。这个文件就是整个安装流程的“施工图”里面记录了项目需要哪些依赖以及执行哪些命令来启动。3.2 安装依赖npm install 这一步为什么这么久紧接着执行npm install这条命令做的事情简单理解就是把项目需要的所有第三方库全部下载到本地的node_modules目录里。之所以第一次运行会花掉不少时间是因为依赖数量多、体积大而且每个人的网络环境不同。这里有个小技巧如果发现下载速度很慢或者反复出现某个包下载失败可以临时把 npm 的镜像源切换到国内镜像npm config set registry https://registry.npmmirror.com安装完成之后如果想恢复官方默认源再执行npm config set registry https://registry.npmjs.org这个操作只改变 npm 下载依赖的来源不影响项目本身的代码逻辑所以不用担心。如果npm install过程中报错了先别急着重复执行。把报错信息截图或者复制下来然后区分一下是不是权限问题。我在后面专门写了一段排错记录这里先不展开。3.3 启动服务并看懂日志依赖安装成功后启动服务通常在项目目录里执行npm start如果提示找不到start脚本说明这个版本的项目可能用了其他的启动约定。你可以先查看一下脚本定义npm run这个命令会列出所有可用的脚本看看有没有dev、serve或者类似的启动项。也可以直接打开项目的package.json和README.md以里面的说明为准。启动成功之后终端里一般会打印出类似这样的信息一个本地地址、当前监听的端口有时还会有一个供局域网访问的地址。我第一次看到的时候有点意外因为它没有弹出一个独立窗口而是就这么“静静地”跑在那里。不要关掉这个终端一旦关闭服务也就停了。3.4 浏览器打开地址完成初始化复制终端里的地址在浏览器里打开。第一次访问的时候正常的体验是进入一个初始化引导有的版本会让你创建管理员账号有的版本会直接进入项目管理界面这取决于你拉取到的版本。我的建议是如果它让你设置管理员账号认真设一个强度足够的密码。因为后面如果你要把这个服务开放给局域网同事一起协作没有密码的保护等于把开发环境裸奔在网络上。初始化完成之后你就应该能看到一个可以创建项目的界面了。到这里安装阶段就算正式结束。后面我还会说怎么判断这个安装到底算不算成功而不只是“表面能打开”。4. 首次启动后的验证与项目创建做到这一步才算装好很多人以为看到登录页就是装好了结果进去之后开始创建项目时又被一堆字段和概念绕晕。所以这一章我专门讲“装好之后怎么验证、怎么做第一个项目”这才是判断安装是否真正成功的标准。4.1 创建项目时该怎么选进入项目管理界面之后一般会有一个“创建项目”的按钮。点进去之后会看到项目名称、项目类型、模板之类的选项。根据我的经验如果只是验证安装选一个空白模板就够了不要选那些包含大量示例资源的模板否则加载很慢。项目类型通常有 2D 和 3D 之分看你最终想做哪种形式的游戏。项目名称建议用英文小写和连字符例如my-first-game不要用中文名称避免后续路径或导出出现问题。这一段的底层逻辑是项目名会成为工程路径的一部分而很多工具链在遇到中文路径时表现不那么稳定。宁可一开始用英文省掉后面一堆麻烦。4.2 理解“场景、对象、脚本”这套基础结构创建完项目进入编辑器之后你会看到三个核心概念场景、对象和脚本。这套结构跟 Unity 有点像但又更轻量。场景就是你的游戏世界里面摆着各种对象比如一个玩家角色、一个地面、一个光源。对象是场景里的实体它们可以挂上不同的组件比如渲染组件让它显示出来碰撞组件让它参与物理效果。脚本则用来定义行为比如按方向键移动角色。我自己的习惯是先不加脚本先在场景里摆一个简单物体看看预览区能不能正常显示出来。这一步能同时验证两件事渲染链路是否正常、浏览器是否支持 WebGL。如果预览区能正常显示出一个立方体或者一个平面那基本可以确定安装是成功的。如果这里显示空白那就回到前面说的 WebGL 检查步骤。4.3 多人协作的入口在哪里Superpowers 的活字号招牌是协作。通常你可以在项目管理界面或者编辑器的某个区域里看到一个“邀请”或“成员”相关的入口。它一般会生成一个链接把链接发给其他人对方用浏览器打开就能进入同一个项目。我第一次用这个功能的时候有一个非常重要的认知修正所有参与者在同一个项目里修改不需要每个人都有一套完整本地环境。也就是说你已经装好的这台机器相当于一台小服务器其他人只是“游客”用浏览器进来协同工作。如果你只是自己一个人玩这功能可能用不上太久但如果你有一个两三人的小团队这个特性真的会很省心至少告别了用微信传压缩包、手动同步版本的日子。4.4 验证导出功能是否可用安装成功的另一个硬指标是能够把项目导出成一个网页。一般来说编辑器里会有一个“导出”或者“构建”按钮点击之后会生成一个包含index.html和一堆资源文件的目录。导出完成后可以这样验证进入导出目录启动一个静态文件服务cd 导出目录路径 python3 -m http.server 8080然后浏览器访问http://localhost:8080如果能正常进入游戏或场景预览就说明整个开发、构建、发布的链路都已经打通了。这条链路打通的意义很大意味着你做的原型可以分分钟发给任何人试玩而对方不需要安装任何软件。5. 安装和启动期间我踩过的坑以及对应的修复思路说实话第一次安装这种开源项目一次成功是运气遇到报错才是常态。这一章我把自己实际踩过、以及帮朋友排查时遇到的几个典型问题整理出来重点不是直接给答案而是还原排查思路。如果你之后遇到类似报错可以沿着同样的链路往下查。5.1 报错 EADDRINUSE端口被占用有一次我执行启动命令终端直接报了一串EADDRINUSE。这个错误通俗讲就是“端口已经被别的程序占用了”。我先冷静下来没去乱改配置而是用命令查了一下占用情况lsof -i :端口号输出显示占用的进程是一个之前没关干净的本地服务。于是我把那个旧进程停掉再重新启动 Superpowers问题就解决了。排查思路很简单端口被占住的本质是“先来后到”要么杀掉旧进程要么换一个新端口。改端口不是不行但很多时候会连带改配置文件所以我的第一选择还是清理旧进程。5.2 npm 一直卡在理想状态不动了还有一次执行npm install之后进度条卡了很久完全没有进展。我看了一眼 npm 的日志发现是在下载某个大包的时候网络跟不上。这次我没死等而是直接中断了安装把镜像切换到了国内镜像然后重新执行一遍。第二次明显顺畅很多几分钟内就完成了。以后你遇到 npm 卡住的问题先不要怀疑代码十有八九是网络层面的问题。可以反复尝试也可以换镜像也可以清一下 npm 缓存npm cache clean --force这些手段按顺序试基本能解决绝大多数“卡死不前进”的情况。5.3 报错 node-gyp 编译失败少了一堆构建工具这是我朋友遇到的最狠的报错。Windows 环境下执行npm install时某个依赖需要编译原生代码结果提示node-gyp相关错误还扯出一堆“找不到 Python”“找不到 C 编译器”之类的字眼。这个问题的本质是npm 下载的依赖里有一部分不是现成的二进制而是需要在本地现场编译编译过程又依赖系统级的构建工具链。解决办法在 Windows 上最直接的就是安装 Visual Studio Build Tools或者直接安装“桌面开发 C”相关的组件。macOS 上一般是装 Xcode Command Line Tools 就能解决xcode-select --installLinux 上则要确保装了build-essential之类的开发工具包。装好构建工具之后重新执行一次安装多半就过了。这种问题不是 Superpowers 特有的任何含有原生依赖的 Node.js 项目都可能遇到遇到不用慌属于路径依赖问题不属于逻辑问题。5.4 服务启动成功但局域网内打不开这个问题在协作场景下特别常见。我当时把终端里的地址发给同一个 WiFi 下的同事结果显示无法连接。我把问题拆成两层来排查服务是否监听了对外地址有些服务默认只监听127.0.0.1也就是只允许本机访问这种情况下需要去配置文件里改成监听0.0.0.0让其他设备也可以访问。防火墙是否放行了端口就算服务监听了对外地址系统防火墙也可能把外部请求挡掉。我当时的处理方法是去防火墙规则里放行对应端口然后重试。如果你是部署在云服务器上还要注意云平台的安全组规则那个和系统防火墙是两套机制都要放行端口才能对外提供服务。这里必须加一个安全提醒一旦让服务监听对外地址等于你的开发环境暴露在网络上。如果默认没有任何登录认证别人猜到了你的地址就能进入项目。我自己的原则是临时协作从不开公网只在可信局域网内开放真要长期对外部署先把认证和密码机制搞定再说。6. 装好之后怎样让这个环境真正“有超能力”安装跑通只是起点怎么让它产生实际价值才是重点。我用了几天之后总结出几个实实在在有帮助的习惯分享给你。6.1 用版本管理工具保护你的作品Superpowers 的项目数据本质上就是磁盘上的一堆文件。既然是文件就应该纳入版本管理。我的习惯是建一个独立的 Git 仓库来跟踪项目目录每次完成一个重要改动就打一个标签或者提交一次。这样做的理由很简单编辑器虽然可以做撤销但撤销只是内存层面的操作一旦误删整个项目目录或者某个版本改坏了想回退Git 就是你最后的救命稻草。我对自己的要求是做到“随时可以回到昨天的版本”。这个习惯比任何功能都更能给你安全感。6.2 插件和扩展不要一次装太多Superpowers 有插件机制可以扩展不少功能这很诱人。但根据我的经验开发环境本身追求的是“稳定”而插件越多互相之间兼容性问题就越明显启动速度也会变慢。我后来给自己定了一个规矩只装当前项目真正需要的插件装之前先看它维护活跃度装完立刻重启一次服务确认没有异常。这样能避免很多“说不清道不明”的怪问题。6.3 资源占用比想象中高勤关标签页由于整个开发过程都在浏览器里浏览器本身就成了耗内存大户。我当时一边开编辑器一边开预览还开着好几个参考文档标签页电脑风扇直接起飞然后编辑器开始有卡顿感。后来我学乖了不用的预览窗口及时关掉编辑器和文档尽量分多个窗口而不是堆在同一个窗口的多个标签页里。打开监测工具看一眼内存占用你会很直观地发现哪些标签页是大头。如果你的开发场景对性能敏感还有一个思路把服务跑在一台小服务器上本地浏览器只负责操作界面。这样压力就从你的个人电脑转移到了服务器笔记本体验会好很多。6.4 从本地到长期协作别忽略安全策略如果你打算从“本地自嗨”升级到“小团队长期协作”有一点必须当回事安全。Superpowers 的本职是开发工具不是一套完善的多租户系统。开放公网访问的时候默认的认证能力可能撑不住恶意访问所以你必须自己补上安全策略。我能想到的保守方案包括不把服务直接暴露到公网需要外网访问时用安全的远程通道连入局域网再使用。如果必须对外提供服务先确认登录密码复杂度同时配置防火墙只允许特定 IP 段访问。定期备份项目目录到另一个存储位置防止因为安全事件导致数据丢失。这一章不会直接教你产品级的部署方案但至少能帮你意识到开发工具的便利性和安全性往往是跷跷板便利越多安全责任越大。我个人在安装过程中最深的体会是第一次跑通的最小路径其实非常短git clone、npm install、npm start三步而已五分钟到半小时内就能看到界面。之前所有让我觉得“这东西很难装”的念头都是被“安装”这个词吓出来的。希望这篇记录也能帮你顺利走完这条路。
阅读完成 · 觉得有帮助？
