最近有朋友来找我问有没有什么能自己部署、又能让团队实时一起写代码的轻量工具。我第一反应就想到了 Superpowers 这个老牌开源项目。别一听 superpowers 就以为是讲超级英雄超能力放到开发工具圈里它其实是一套开源的实时多人协作编程环境。你把它装到自己的电脑或者服务器上所有人只要打开浏览器就能进到同一个工作区里一边写 HTML/CSS/JS一边实时看到对方的每一次输入还能顺手打字交流。这套东西解决什么问题往大了说是异地结对编程、线上教学、头脑风暴式代码演示最好的那一档往实际里说就是你在自己局域网里搭一个“带人写代码”的专用空间不依赖任何商业平台数据都在自己手里。我当年第一次拿它给远程的学员讲课打开一个页面就能看到我在屏幕上的每一次改动连光标位置都是同步的那种体验放在现在也不算过时。这篇文章不讲虚的就从“想安装 Superpowers”这个理由出发把从下载、启动到实际用得起来这整条路走一遍最后附上我踩过的坑适合刚接触自托管协作工具、以及想在内部网络里快速搭建协作环境的同学参考。1. Superpowers 是什么先搞清楚这个工具的本质1.1 一句话讲清它的定位Superpowers 是一个基于 Node.js 编写的开源实时协作平台用大白话说就是一台跑在你电脑上的“协作服务器”。它跟普通的在线代码编辑器不一样核心不是“远程存代码”而是“实时同步每一次编辑”——你在浏览器里写一个字符屏幕对面的人立刻就看到了这种同步不是靠刷新页面而是靠 WebSocket 把操作指令实时推给所有连接者所以双方的光标、选区、输入内容全部是真正意义上的“活”的。它的界面也很直接打开就是一个项目管理列表你可以创建多个项目每个项目里可以放页面、脚本、样式表还带一个轻量的代码编辑器和聊天面板。因为整个前端都能在浏览器里跑人多人少都不需要装客户端管理层只需要部署一份服务端。1.2 它和常规协作工具的区别在哪现在一说多人协作写代码大家脑子里的选项不外乎腾讯文档、石墨文档这类办公文档或者一些代码托管平台的在线 IDE。这些产品的思路是“云端开文件”由平台托管账号、托管存储、托管计算。Superpowers 的思路完全是另一条路它的服务端就是一堆可执行文件谁部署谁掌握数据协作的范围也完全由你自己控制或者说让你真正拥有那个“白板”。从实际体验来分Superpowers 更接近“共享桌面式写码”而不是“多人编辑同一个 Git 仓库”。它不强调分支、合并、冲突解决只强调你我都看着同一块屏幕谁都能上手改。我当时的感受是用这种工具做教学效果比任何录屏和共享屏幕都自然因为学员自己也可以动手改了立刻能看到结果。1.3 运行它需要什么样的环境Superpowers 是 Node.js 项目所以最核心的环境要求就是装好 Node.js版本不需要追求最新官方长期以来支持的版本足够稳。我自己测试时用的是 LTS 版Node 10 到 Node 18 都跑过只要别太老基本都不会在启动阶段出问题。内存方面它启动之后占用的资源不高我实测过在 1 核 1G 的云服务器上跑带两三个人同时写代码仍然很流畅。如果你只是在本地 Windows 或 Mac 上临时用那就更没压力了几千个并发的 WebSocket 连接才会明显吃资源日常团队协作完全够用。存储方面它会生成一个数据目录存放项目文件和用户账号所以你至少要留个几百 MB 给这套系统存东西。还有一个容易被忽略的点是网络。既然是浏览器访问那么部署的那台机器必须有可用的网络端口默认情况下是 4237。如果你在云服务上装记得在安全组里头放行这个端口如果你在公司内网装那就省事多了内网的所有设备都能直接访问连外网都省了。2. 安装前的准备先把坑踩明白2.1 软硬件需求没那么玄很多人一听到“自托管”就先慌了一下总觉得得配一台性能很强的服务器。这个误解我一开始也有后来发现真没那么夸张。Superpowers 的服务端其实就是一个 Node 进程加一个静态资源服务它主要负责转发消息和保存项目数据真正的编译渲染工作都在浏览器端做所以对服务端的压力并没那么大。以我的实测结果来做参考一台双核 2G 内存的 Linux 服务器跑 Superpowers 的同时还能在上面跑个小博客人均使用状态下网络带宽也就几百 KB 级别。如果你只是本地一个人用那随便一台旧笔记本装上 Linux 或 Windows 就能搞定连装系统的门槛都没有。真正要说有“门槛”的是系统里那段网络必须稳定毕竟是实时写代码万一网络抖动还是会导致连接短暂中断。2.2 去哪下载选哪个版本Superpowers 的官方安装包里带一个“服务器程序”和一套“客户端资源”官网或者项目发布页面会按平台打好压缩包Windows、macOS、Linux 都有对应版本。下载的时候建议优先选对应版本年份最新的发布版不要下载带 dev 标识的开发构建版生产环境最要紧的是稳开发版常常没有经过完整的回归测试跑起来容易踩到莫名其妙的坑。这里要特别提醒一句很多用户习惯去 GitHub 的仓库直接 clone 源代码来跑我前面折腾过一趟发现源代码里的依赖和构建步骤比预编译包复杂得多。如果你只是想用起来别跟自己过不去直接下载官方在发布区提供的预编译压缩包解压之后就能执行省去自己安装一堆构建依赖的麻烦。我自己的建议是能用二进制包就绝不从源码现编译把时间留给后续调通流程上面。2.3 目录摆放与权限设置下载好压缩包之后很多人会顺手把它解压到 “下载” 文件夹里这个习惯在临时测试时没问题但如果你打算天天拿它做协作平台建议单独找一个专门的目录来放。比如在 Linux 服务器上可以放在/opt/superpowers或~/superpowers在 Windows 上可以放在D:\tools\superpowers。这样做的好处是升级、备份、看日志都集中在一个地方不容易漏。权限上如果你是 Linux 服务器不要直接拿 root 跑服务因为项目会生成数据文件root 跑出来的文件权限很麻烦后面要备份或者迁移都得转换属主。稳妥的做法是新建一个普通系统用户然后把目录授权给这个用户再用这个用户启动。其实这也是自托管服务绕不开的一个原则服务权限收得越紧出状况时越容易处理。3. 安装实操全过程从下载到浏览器打开3.1 解压与目录结构说明拿到压缩包后先把文件放到目标目录然后解压。Windows 用户右键“解压到当前文件夹”即可Linux 下用tar命令mkdir -p /opt/superpowers tar -xzf superpowers-*.tar.gz -C /opt/superpowers --strip-components1 cd /opt/superpowers解压完成后你能看到里面有几个核心文件一个直接可执行的服务端二进制一套前端资源的目录可能还附带示例项目和说明文档。服务端二进制名字就是superpowers在 Windows 下对应Superpowers.exe之类的文件直接运行它就行。首次运行时程序会检查目录下有没有配置文件如果没有就会用默认配置生成一份并在所在目录初始化一个数据目录。说白了它自己就把基础环境搭好了不需要你手动建表或者初始化数据库。3.2 启动服务一条命令的事启动过程比想象中还省事。先进入安装目录然后在命令行里执行./superpowers如果你是在 Windows 上直接双击Superpowers.exe或在命令行里输入它的文件名效果是一样的。启动后终端里会滚动输出一些日志正常情况下会显示 “listening” 或者类似监听地址的信息并告诉你端口号。默认端口是4237这个数字不算常见而且默认绑定的监听地址是需要你自己确认的。如果是在本机用浏览器打开http://localhost:4237就进去了如果是在局域网服务器上需要确认监听地址不是只有127.0.0.1否则别的机器访问不到。如果默认端口被占用你可以带参数指定新端口运行常见做法是./superpowers --port 8080别问我为什么会预先提这个我第一次部署时 4237 端口跟我正在跑的另一服务撞了当时慌了几分钟才想到查日志经验都是在这些小坑里磨出来的。3.3 浏览器访问与初识管理界面服务启动后打开浏览器访问地址你看到的页面会引导你创建管理员账号。这一步很关键它决定后续谁能创建项目、谁能设置空间权限。建议账号名和密码都别用太简单的组合因为一旦服务暴露到外网弱口令账号很容易被人扫描到配合默认端口一起尝试登录我见过不止一次了。登录进去之后你会看到主界面里有创建项目的入口以及几个示例项目。这时候先别急着删示例打开一个看看代码和运行效果能帮你快速建立对这个平台的感知左边是项目文件树中间是编辑区右边是聊天和协作成员列表。所有改动都会自动保存到服务器数据目录里不需要手动点保存按钮这一点对新人来说要多适应一下因为和传统 IDE 的习惯不一样。4. 上手使用真正让它跑起来干活4.1 创建空间和项目Superpowers 里头的“空间”可以理解成一个隔离的工作区一个空间里可以有多个项目不同空间的账号和项目数据彼此不互通。如果你要带多个团队或者给不同班级开课建议按团队或班级各自建独立空间这样权限清晰管理上也不会互相干扰。创建项目时系统会给你一批模板比如纯 HTML 页面、带样式的基础项目、还有包含简单动画的创意项目。选择模板只是起步之后你随时可以新建文件、调整目录、引入外部库。我的建议是选择最基础的模板起步因为协作过程中大家可能会往里面加各种第三方库基础模板的目录结构最不容易产生混乱。项目创建好之后你会得到一个项目链接。把这个链接发给别人他们登录进来后就能看到同一个项目。这里要提一下权限设计管理员可以设置参与者是“能编辑”还是“只能看”做演示场景时不妨把多数人设为只读留给主操作人修改权限避免课堂上被乱改。4.2 多人在线协作的正确姿势当两个人同时打开同一个项目时屏幕上会显示双方的光标位置你输入文字时对方的界面会同步滚动。这种体验对没经历过云端协作的人来说很惊艳但几个人的光标本就是真实可见的如果同屏人数多了建议不要同时抢着改同一行原因很简单实时协作工具的冲突处理虽然能防止崩溃但没法真正解决“逻辑上两个人改到同一个地方”的心智分歧。我自己的习惯是一个人主写其他人负责读代码加提建议。要动手的地方先在聊天区喊一声或者就地留个注释避免多人同时操作同一个文件。毕竟 Superpowers 的定位是“协作白板”不是 Git它不是用来管理分支冲突的别拿它干不擅长的事。各人写各自的文件再互相 review反而是很流畅的节奏。4.3 写代码时常用的操作捷径Superpowers 内置的编辑器跟现代 IDE 相比虽然轻量但常用快捷键大部分都在CtrlS在这里没有保存含义因为自动保存但仍会触发某些面板刷新建议养好习惯去编写代码CtrlSpace可以触发补全CtrlZ撤销也正常工作。此外在编辑 HTML 时右上角的按钮可以直接刷新预览区域这个操作很适合教学演示。除了快捷键聊天区也支持简单标记可以在讨论时做重点提示。我习惯在项目根目录放一个README.txt或者todo.md把当天要改的点和分工写在里面所有人都能在同一个编辑器里实时更新比口头说清楚多了。5. 常见问题与排查技巧实录5.1 启动报错端口被占用怎么办这是我最先遇到也是最容易解决的问题。启动时如果日志提示地址或端口已被占用不要急着到处找进程执行下面这条命令看看谁占了端口Linux 示例lsof -i :4237如果确实有其他服务占用了端口你有两个选择干掉那个进程或者让 Superpowers 换一个端口。我倾向于换端口毕竟破坏别的服务容易引起更大的麻烦。用--port参数换好之后访问地址也要跟着变而且如果配置里写死了服务地址记得一并改掉。5.2 浏览器页面空白或一直转圈页面能打开但一直是加载状态十次里有八次是 WebSocket 连接失败。这种情况在“服务端放在别的机器上但访问地址填了 localhost”时尤其常见。你从自己电脑访问服务器上的服务地址必须填服务器的内网 IP 或域名不能填localhost。另外如果你是在公司网络环境还要确认网关有没有拦截非标准端口的 WebSocket 流量这个排查起来不容易可以试试换个端口来规避。另外浏览器版本的兼容性也要考虑。太老旧的浏览器对 ES6 和 WebSocket 支持不完整会导致部分功能异常。建议让团队成员统一用最新版 Chrome 或 Edge能省掉很多玄学问题。5.3 中文输入和字符编码问题Superpowers 对中文的支持整体没问题但如果你在 Windows 记事本里编辑过配置文件再粘进项目可能会出现中文乱码。这类问题多半是编码不统一造成的项目文件默认是 UTF-8记事本默认可能带着旧格式解决办法是写代码时注意保存编码格式为 UTF-8或者在粘贴之前先经过一次纯文本清洗。还有一种情况是编辑器里中文输入法状态跟快捷键冲突。这是我没怎么深究过的但碰到过几次表现是按某些组合键时输入法直接把编辑器的快捷键吃掉了。遇到这种问题我通常是先切回英文输入法再操作快捷键操作完再切回中文虽然笨但管用。5.4 协作时权限和保存的坑有些用户会问其他人改代码之后改了的东西会不会自动帮我保存答案是会的所有编辑操作都会实时写进服务端的数据目录里。但这里就引出另一个坑如果两个人在同一时间对同一个文件做了结构性的删除和重写可能会出现文件历史被覆盖的混乱。这个不是系统 bug而是协作场景天然存在的风险。想避免这种情况最好的办法是养成“多文件分工”的习惯每个参与者负责独立文件不要扎堆处理同一个文件。要是真担心改坏了基础结构可以先在本地把完整副本备份一份再开协作给自己留条后路。备份的方法很简单就是把数据目录整个复制一份。6. 进阶玩法与实际应用场景6.1 利用内置模板快速起步Superpowers 自带的模板不是给你凑数的它基本覆盖了从空白 HTML 到带特效演示的常见起点。比如我想给团队展示一个交互式动画直接新建一个带动画的模板改几个参数就能变成现成的演示稿。所以遇到新需求时先看看模板列表里有没有接近的用它起步比自己从零搭目录省太多时间。模板的好处还在于它本身就是一个最佳实践参考。如果你刚接触这套工具完全可以把模板里的代码一行行拆开读一遍看看它怎么组织样式、怎么挂脚本、怎么跑动画这个过程能让你很快理解 Superpowers 项目结构的推荐玩法。6.2 备份与版本管理思路既然数据都在自己手里备份就得自己操心了。你可以定期把整个数据目录打成压缩包也可以用计划任务定时复制到别的地方。我自己习惯每天晚上用一条简单的tar命令把数据目录打包再加上保留最近 7 份的策略真出问题也能恢复到某个时间点。如果你还想配合 Git 做版本管理也不冲突。Superpowers 项目里很多代码本身可以用 Git 记录你只要保证服务进程在操作期间没有同时对外写文件即可不然可能在 Git 工作区里遇到“文件被外部改动”的提示。稳妥的做法是把 Git 版本管理设在项目数据目录之外另建同步脚本而不是强行让 Git 接管实时变动的目录。6.3 在局域网内给小伙伴们开放访问本地部署的 Superpowers 最实用的场景就是团队内网合用。服务器启动后修改监听配置让它绑定到内网 IP 或0.0.0.0然后其他小伙伴用浏览器输入http://服务器IP:4237就能加入。如果你的网络里有路由器隔离或防火墙放行对应端口即可。如果服务器在上云环境安全组和防火墙是两层都放行才访问得通。这里我不建议把服务裸奔到公网再配弱密码毕竟协作工具里存的代码可能是内部资料好歹加一层访问控制或者用网络层面的白名单限制来源 IP成本低且效果好。写在最后的一点实在话Superpowers 是我试用过的自托管协作工具里上手门槛比较低的一个。它不追求像大型云平台那样复杂的权限体系也不打算替代 Git 这类版本管理工具它的定位就是“让一群人在同一块屏幕上舒服地写代码”。如果你正好需要教一批人入门前端或者带小团队做实时头脑风暴式的原型开发花一个下午把它部署起来绝对能省下后面很多开视频会议、来回发截图的功夫。我个人在实践中最受益的反而是它那种“所见即所改”的实感。有一次我带两个徒弟改一个页面样式三个人同时在线我调整间距他们立刻说“这个间距合适了”那种即时反馈让我觉得协作工具就应该是这个感觉。后面我又试着用它组织过一次远程代码评审把待评审文件放进去让大家边看边批注效率也比邮件来回发高了不少。如果看完这篇你也想去部署一个试试提醒一句安装只是第一步真正让它发挥价值的是你愿不愿意把日常的写代码场景搬一部分进去。不用求大先从两个人一起改一个 HTML 页面开始你会很快摸到它顺手的地方也会慢慢发现哪些流程不能靠它做。到时候再回来调整自己的协作方式也不迟。
最近有朋友来找我问有没有什么能自己部署、又能让团队实时一起写代码的轻量工具。我第一反应就想到了 Superpowers 这个老牌开源项目。别一听 superpowers 就以为是讲超级英雄超能力放到开发工具圈里它其实是一套开源的实时多人协作编程环境。你把它装到自己的电脑或者服务器上所有人只要打开浏览器就能进到同一个工作区里一边写 HTML/CSS/JS一边实时看到对方的每一次输入还能顺手打字交流。这套东西解决什么问题往大了说是异地结对编程、线上教学、头脑风暴式代码演示最好的那一档往实际里说就是你在自己局域网里搭一个“带人写代码”的专用空间不依赖任何商业平台数据都在自己手里。我当年第一次拿它给远程的学员讲课打开一个页面就能看到我在屏幕上的每一次改动连光标位置都是同步的那种体验放在现在也不算过时。这篇文章不讲虚的就从“想安装 Superpowers”这个理由出发把从下载、启动到实际用得起来这整条路走一遍最后附上我踩过的坑适合刚接触自托管协作工具、以及想在内部网络里快速搭建协作环境的同学参考。1. Superpowers 是什么先搞清楚这个工具的本质1.1 一句话讲清它的定位Superpowers 是一个基于 Node.js 编写的开源实时协作平台用大白话说就是一台跑在你电脑上的“协作服务器”。它跟普通的在线代码编辑器不一样核心不是“远程存代码”而是“实时同步每一次编辑”——你在浏览器里写一个字符屏幕对面的人立刻就看到了这种同步不是靠刷新页面而是靠 WebSocket 把操作指令实时推给所有连接者所以双方的光标、选区、输入内容全部是真正意义上的“活”的。它的界面也很直接打开就是一个项目管理列表你可以创建多个项目每个项目里可以放页面、脚本、样式表还带一个轻量的代码编辑器和聊天面板。因为整个前端都能在浏览器里跑人多人少都不需要装客户端管理层只需要部署一份服务端。1.2 它和常规协作工具的区别在哪现在一说多人协作写代码大家脑子里的选项不外乎腾讯文档、石墨文档这类办公文档或者一些代码托管平台的在线 IDE。这些产品的思路是“云端开文件”由平台托管账号、托管存储、托管计算。Superpowers 的思路完全是另一条路它的服务端就是一堆可执行文件谁部署谁掌握数据协作的范围也完全由你自己控制或者说让你真正拥有那个“白板”。从实际体验来分Superpowers 更接近“共享桌面式写码”而不是“多人编辑同一个 Git 仓库”。它不强调分支、合并、冲突解决只强调你我都看着同一块屏幕谁都能上手改。我当时的感受是用这种工具做教学效果比任何录屏和共享屏幕都自然因为学员自己也可以动手改了立刻能看到结果。1.3 运行它需要什么样的环境Superpowers 是 Node.js 项目所以最核心的环境要求就是装好 Node.js版本不需要追求最新官方长期以来支持的版本足够稳。我自己测试时用的是 LTS 版Node 10 到 Node 18 都跑过只要别太老基本都不会在启动阶段出问题。内存方面它启动之后占用的资源不高我实测过在 1 核 1G 的云服务器上跑带两三个人同时写代码仍然很流畅。如果你只是在本地 Windows 或 Mac 上临时用那就更没压力了几千个并发的 WebSocket 连接才会明显吃资源日常团队协作完全够用。存储方面它会生成一个数据目录存放项目文件和用户账号所以你至少要留个几百 MB 给这套系统存东西。还有一个容易被忽略的点是网络。既然是浏览器访问那么部署的那台机器必须有可用的网络端口默认情况下是 4237。如果你在云服务上装记得在安全组里头放行这个端口如果你在公司内网装那就省事多了内网的所有设备都能直接访问连外网都省了。2. 安装前的准备先把坑踩明白2.1 软硬件需求没那么玄很多人一听到“自托管”就先慌了一下总觉得得配一台性能很强的服务器。这个误解我一开始也有后来发现真没那么夸张。Superpowers 的服务端其实就是一个 Node 进程加一个静态资源服务它主要负责转发消息和保存项目数据真正的编译渲染工作都在浏览器端做所以对服务端的压力并没那么大。以我的实测结果来做参考一台双核 2G 内存的 Linux 服务器跑 Superpowers 的同时还能在上面跑个小博客人均使用状态下网络带宽也就几百 KB 级别。如果你只是本地一个人用那随便一台旧笔记本装上 Linux 或 Windows 就能搞定连装系统的门槛都没有。真正要说有“门槛”的是系统里那段网络必须稳定毕竟是实时写代码万一网络抖动还是会导致连接短暂中断。2.2 去哪下载选哪个版本Superpowers 的官方安装包里带一个“服务器程序”和一套“客户端资源”官网或者项目发布页面会按平台打好压缩包Windows、macOS、Linux 都有对应版本。下载的时候建议优先选对应版本年份最新的发布版不要下载带 dev 标识的开发构建版生产环境最要紧的是稳开发版常常没有经过完整的回归测试跑起来容易踩到莫名其妙的坑。这里要特别提醒一句很多用户习惯去 GitHub 的仓库直接 clone 源代码来跑我前面折腾过一趟发现源代码里的依赖和构建步骤比预编译包复杂得多。如果你只是想用起来别跟自己过不去直接下载官方在发布区提供的预编译压缩包解压之后就能执行省去自己安装一堆构建依赖的麻烦。我自己的建议是能用二进制包就绝不从源码现编译把时间留给后续调通流程上面。2.3 目录摆放与权限设置下载好压缩包之后很多人会顺手把它解压到 “下载” 文件夹里这个习惯在临时测试时没问题但如果你打算天天拿它做协作平台建议单独找一个专门的目录来放。比如在 Linux 服务器上可以放在/opt/superpowers或~/superpowers在 Windows 上可以放在D:\tools\superpowers。这样做的好处是升级、备份、看日志都集中在一个地方不容易漏。权限上如果你是 Linux 服务器不要直接拿 root 跑服务因为项目会生成数据文件root 跑出来的文件权限很麻烦后面要备份或者迁移都得转换属主。稳妥的做法是新建一个普通系统用户然后把目录授权给这个用户再用这个用户启动。其实这也是自托管服务绕不开的一个原则服务权限收得越紧出状况时越容易处理。3. 安装实操全过程从下载到浏览器打开3.1 解压与目录结构说明拿到压缩包后先把文件放到目标目录然后解压。Windows 用户右键“解压到当前文件夹”即可Linux 下用tar命令mkdir -p /opt/superpowers tar -xzf superpowers-*.tar.gz -C /opt/superpowers --strip-components1 cd /opt/superpowers解压完成后你能看到里面有几个核心文件一个直接可执行的服务端二进制一套前端资源的目录可能还附带示例项目和说明文档。服务端二进制名字就是superpowers在 Windows 下对应Superpowers.exe之类的文件直接运行它就行。首次运行时程序会检查目录下有没有配置文件如果没有就会用默认配置生成一份并在所在目录初始化一个数据目录。说白了它自己就把基础环境搭好了不需要你手动建表或者初始化数据库。3.2 启动服务一条命令的事启动过程比想象中还省事。先进入安装目录然后在命令行里执行./superpowers如果你是在 Windows 上直接双击Superpowers.exe或在命令行里输入它的文件名效果是一样的。启动后终端里会滚动输出一些日志正常情况下会显示 “listening” 或者类似监听地址的信息并告诉你端口号。默认端口是4237这个数字不算常见而且默认绑定的监听地址是需要你自己确认的。如果是在本机用浏览器打开http://localhost:4237就进去了如果是在局域网服务器上需要确认监听地址不是只有127.0.0.1否则别的机器访问不到。如果默认端口被占用你可以带参数指定新端口运行常见做法是./superpowers --port 8080别问我为什么会预先提这个我第一次部署时 4237 端口跟我正在跑的另一服务撞了当时慌了几分钟才想到查日志经验都是在这些小坑里磨出来的。3.3 浏览器访问与初识管理界面服务启动后打开浏览器访问地址你看到的页面会引导你创建管理员账号。这一步很关键它决定后续谁能创建项目、谁能设置空间权限。建议账号名和密码都别用太简单的组合因为一旦服务暴露到外网弱口令账号很容易被人扫描到配合默认端口一起尝试登录我见过不止一次了。登录进去之后你会看到主界面里有创建项目的入口以及几个示例项目。这时候先别急着删示例打开一个看看代码和运行效果能帮你快速建立对这个平台的感知左边是项目文件树中间是编辑区右边是聊天和协作成员列表。所有改动都会自动保存到服务器数据目录里不需要手动点保存按钮这一点对新人来说要多适应一下因为和传统 IDE 的习惯不一样。4. 上手使用真正让它跑起来干活4.1 创建空间和项目Superpowers 里头的“空间”可以理解成一个隔离的工作区一个空间里可以有多个项目不同空间的账号和项目数据彼此不互通。如果你要带多个团队或者给不同班级开课建议按团队或班级各自建独立空间这样权限清晰管理上也不会互相干扰。创建项目时系统会给你一批模板比如纯 HTML 页面、带样式的基础项目、还有包含简单动画的创意项目。选择模板只是起步之后你随时可以新建文件、调整目录、引入外部库。我的建议是选择最基础的模板起步因为协作过程中大家可能会往里面加各种第三方库基础模板的目录结构最不容易产生混乱。项目创建好之后你会得到一个项目链接。把这个链接发给别人他们登录进来后就能看到同一个项目。这里要提一下权限设计管理员可以设置参与者是“能编辑”还是“只能看”做演示场景时不妨把多数人设为只读留给主操作人修改权限避免课堂上被乱改。4.2 多人在线协作的正确姿势当两个人同时打开同一个项目时屏幕上会显示双方的光标位置你输入文字时对方的界面会同步滚动。这种体验对没经历过云端协作的人来说很惊艳但几个人的光标本就是真实可见的如果同屏人数多了建议不要同时抢着改同一行原因很简单实时协作工具的冲突处理虽然能防止崩溃但没法真正解决“逻辑上两个人改到同一个地方”的心智分歧。我自己的习惯是一个人主写其他人负责读代码加提建议。要动手的地方先在聊天区喊一声或者就地留个注释避免多人同时操作同一个文件。毕竟 Superpowers 的定位是“协作白板”不是 Git它不是用来管理分支冲突的别拿它干不擅长的事。各人写各自的文件再互相 review反而是很流畅的节奏。4.3 写代码时常用的操作捷径Superpowers 内置的编辑器跟现代 IDE 相比虽然轻量但常用快捷键大部分都在CtrlS在这里没有保存含义因为自动保存但仍会触发某些面板刷新建议养好习惯去编写代码CtrlSpace可以触发补全CtrlZ撤销也正常工作。此外在编辑 HTML 时右上角的按钮可以直接刷新预览区域这个操作很适合教学演示。除了快捷键聊天区也支持简单标记可以在讨论时做重点提示。我习惯在项目根目录放一个README.txt或者todo.md把当天要改的点和分工写在里面所有人都能在同一个编辑器里实时更新比口头说清楚多了。5. 常见问题与排查技巧实录5.1 启动报错端口被占用怎么办这是我最先遇到也是最容易解决的问题。启动时如果日志提示地址或端口已被占用不要急着到处找进程执行下面这条命令看看谁占了端口Linux 示例lsof -i :4237如果确实有其他服务占用了端口你有两个选择干掉那个进程或者让 Superpowers 换一个端口。我倾向于换端口毕竟破坏别的服务容易引起更大的麻烦。用--port参数换好之后访问地址也要跟着变而且如果配置里写死了服务地址记得一并改掉。5.2 浏览器页面空白或一直转圈页面能打开但一直是加载状态十次里有八次是 WebSocket 连接失败。这种情况在“服务端放在别的机器上但访问地址填了 localhost”时尤其常见。你从自己电脑访问服务器上的服务地址必须填服务器的内网 IP 或域名不能填localhost。另外如果你是在公司网络环境还要确认网关有没有拦截非标准端口的 WebSocket 流量这个排查起来不容易可以试试换个端口来规避。另外浏览器版本的兼容性也要考虑。太老旧的浏览器对 ES6 和 WebSocket 支持不完整会导致部分功能异常。建议让团队成员统一用最新版 Chrome 或 Edge能省掉很多玄学问题。5.3 中文输入和字符编码问题Superpowers 对中文的支持整体没问题但如果你在 Windows 记事本里编辑过配置文件再粘进项目可能会出现中文乱码。这类问题多半是编码不统一造成的项目文件默认是 UTF-8记事本默认可能带着旧格式解决办法是写代码时注意保存编码格式为 UTF-8或者在粘贴之前先经过一次纯文本清洗。还有一种情况是编辑器里中文输入法状态跟快捷键冲突。这是我没怎么深究过的但碰到过几次表现是按某些组合键时输入法直接把编辑器的快捷键吃掉了。遇到这种问题我通常是先切回英文输入法再操作快捷键操作完再切回中文虽然笨但管用。5.4 协作时权限和保存的坑有些用户会问其他人改代码之后改了的东西会不会自动帮我保存答案是会的所有编辑操作都会实时写进服务端的数据目录里。但这里就引出另一个坑如果两个人在同一时间对同一个文件做了结构性的删除和重写可能会出现文件历史被覆盖的混乱。这个不是系统 bug而是协作场景天然存在的风险。想避免这种情况最好的办法是养成“多文件分工”的习惯每个参与者负责独立文件不要扎堆处理同一个文件。要是真担心改坏了基础结构可以先在本地把完整副本备份一份再开协作给自己留条后路。备份的方法很简单就是把数据目录整个复制一份。6. 进阶玩法与实际应用场景6.1 利用内置模板快速起步Superpowers 自带的模板不是给你凑数的它基本覆盖了从空白 HTML 到带特效演示的常见起点。比如我想给团队展示一个交互式动画直接新建一个带动画的模板改几个参数就能变成现成的演示稿。所以遇到新需求时先看看模板列表里有没有接近的用它起步比自己从零搭目录省太多时间。模板的好处还在于它本身就是一个最佳实践参考。如果你刚接触这套工具完全可以把模板里的代码一行行拆开读一遍看看它怎么组织样式、怎么挂脚本、怎么跑动画这个过程能让你很快理解 Superpowers 项目结构的推荐玩法。6.2 备份与版本管理思路既然数据都在自己手里备份就得自己操心了。你可以定期把整个数据目录打成压缩包也可以用计划任务定时复制到别的地方。我自己习惯每天晚上用一条简单的tar命令把数据目录打包再加上保留最近 7 份的策略真出问题也能恢复到某个时间点。如果你还想配合 Git 做版本管理也不冲突。Superpowers 项目里很多代码本身可以用 Git 记录你只要保证服务进程在操作期间没有同时对外写文件即可不然可能在 Git 工作区里遇到“文件被外部改动”的提示。稳妥的做法是把 Git 版本管理设在项目数据目录之外另建同步脚本而不是强行让 Git 接管实时变动的目录。6.3 在局域网内给小伙伴们开放访问本地部署的 Superpowers 最实用的场景就是团队内网合用。服务器启动后修改监听配置让它绑定到内网 IP 或0.0.0.0然后其他小伙伴用浏览器输入http://服务器IP:4237就能加入。如果你的网络里有路由器隔离或防火墙放行对应端口即可。如果服务器在上云环境安全组和防火墙是两层都放行才访问得通。这里我不建议把服务裸奔到公网再配弱密码毕竟协作工具里存的代码可能是内部资料好歹加一层访问控制或者用网络层面的白名单限制来源 IP成本低且效果好。写在最后的一点实在话Superpowers 是我试用过的自托管协作工具里上手门槛比较低的一个。它不追求像大型云平台那样复杂的权限体系也不打算替代 Git 这类版本管理工具它的定位就是“让一群人在同一块屏幕上舒服地写代码”。如果你正好需要教一批人入门前端或者带小团队做实时头脑风暴式的原型开发花一个下午把它部署起来绝对能省下后面很多开视频会议、来回发截图的功夫。我个人在实践中最受益的反而是它那种“所见即所改”的实感。有一次我带两个徒弟改一个页面样式三个人同时在线我调整间距他们立刻说“这个间距合适了”那种即时反馈让我觉得协作工具就应该是这个感觉。后面我又试着用它组织过一次远程代码评审把待评审文件放进去让大家边看边批注效率也比邮件来回发高了不少。如果看完这篇你也想去部署一个试试提醒一句安装只是第一步真正让它发挥价值的是你愿不愿意把日常的写代码场景搬一部分进去。不用求大先从两个人一起改一个 HTML 页面开始你会很快摸到它顺手的地方也会慢慢发现哪些流程不能靠它做。到时候再回来调整自己的协作方式也不迟。
