最近后台好几条私信都在问同一件事：想装 Superpowers，到底从哪里下手。说实话，第一次看到这个需求时我也愣了一下，因为 Superpowers 并不是某个官方发布的单一软件，它更像是一个外号——我把手头这套开源工具组合叫成了这个名字。它们组合在一起之后的效果，确实就像给开发环境点了技能树：编辑器、终端、容器、自动化全部打通，日常从改一行代码到起一整套项目，路径短到让人怀疑以前的时间都去哪了。这篇文章就写给那些刚听到这个词、也想把环境武装一遍的人，我会按真实安装顺序把每一步讲清楚，包括命令、配置和踩坑点。如果你已经装了其中一部分，也可以对照查缺补漏。

1. 先说清楚：Superpowers 到底是什么

1.1 名字的由来和边界

Superpowers 一开始只是我自己在本地环境配置文档里写的一个文件夹名，意思是“装完这些，你干活就有超能力了”。后来给同事同步配置时，他们干脆就把整套环境称为 Superpowers，叫顺口了。它不是一个需要去官网下载的客户端，而是一整套可以自由组合的开源工具链，我把它分成四个层级：

每一层都可以单独安装，但真正“超能力”的感觉，来自它们之间的联动。比如在终端里用 zoxide 跳进项目目录、用 fzf 搜索历史命令，然后直接code .打开编辑器，再通过 Dev Container 一键进入隔离好的开发环境。这一串动作在以前至少要开三个窗口、敲十几条命令，现在只需要几秒钟。

1.2 这套组合能解决什么问题，适合谁

如果你经常同时维护两三个项目，大概率经历过这样的崩溃：A 项目要 Node 16，B 项目要 Node 20，每次切换都要改环境变量；或者新同事入职，光配置开发环境就花了两天。Superpowers 的思路就是把“环境”本身变成代码——用 Docker 把运行时隔离，用 VS Code 的配置统一编辑器行为，用终端工具把高频操作压缩成快捷键。这样无论是个人升级还是团队协作，都少了很多“在我电脑上是好的”这种破事。

适合的人群很广：前端、后端、全栈、数据分析，甚至运维都可以按需取用。但如果你只是偶尔写个脚本，没有必要把整套都装齐，挑编辑器层和终端层用起来就够了。这篇文章下面的安装顺序，也是按照“先基础、再编辑器、再终端、再环境”来的，跟着走不会乱。

2. 安装前的准备：把地基打牢固

2.1 先检查系统环境，避免后面白折腾

在动手之前，我强烈建议你先花五分钟确认系统状态，这一步能省掉后面很多莫名其妙的问题。Windows 用户最好先开启 WSL2，因为后面很多终端工具在 Linux 环境下表现更稳定，Docker Desktop 也能直接和 WSL2 集成，不用单独装虚拟机。检查方法很简单：在 PowerShell 里执行wsl --status，如果提示没有发行版，就运行wsl --install -d Ubuntu-22.04装一个。macOS 用户则建议先把 Command Line Tools 装上，执行xcode-select --install即可，不用装完整版 Xcode，省几个 G 磁盘空间。

Linux 用户反而最简单，但要注意发行版的包管理器差异，Debian/Ubuntu 系用apt，CentOS/Fedora 系用dnf。顺手确认一下磁盘剩余空间，整套环境装下来差不多要占用 3-5 GB，主要大头是 Docker 镜像和编辑器缓存。如果磁盘常年飘红，先清理一下再继续。

2.2 安装 Git、Node.js 和包管理器

底层依赖里面，Git 和 Node.js 是无论如何都绕不开的。Git 不用多说，几乎所有工具链都会调用它；Node.js 则是很多命令行工具的运行底座，像 VS Code 的扩展管理器、部分终端工具都依赖 Node 环境。

安装 Git 时要注意一点：不要光用默认选项一路下一步。在 Windows 上安装时，有一个“调整 PATH 环境变量”的选项，务必选“Use Git from the Windows Command Prompt”，否则后面在 PowerShell 里跑git命令会提示找不到。macOS 用户执行brew install git，Linux 用户用apt install git或dnf install git都可以。

Node.js 安装我建议用版本管理工具而不是直接装官网包。Windows 和 macOS 上可以用nvm-windows或nvm，Linux 上直接用nvm。为什么？因为后面跑不同项目时会频繁切换 Node 版本，如果直接装了固定版本，遇到老项目要降级就很痛苦。装完 nvm 后，执行nvm install --lts装当前长期支持版，再nvm alias default把它设为默认。这样以后项目需要什么版本，一条命令就能切。

包管理器方面，Windows 上我默认用 winget 或 Scoop，macOS 用 Homebrew，Linux 用系统包管理器。这里不强制统一，但建议你至少留一个能命令行安装软件的工具，因为后面的工具几乎都能通过它装。

3. 编辑器层：VS Code 与核心扩展

3.1 安装 VS Code 和首选项设置

编辑器层我没有纠结太多，VS Code 依然是目前扩展生态最丰富、跨平台最一致的编辑器。别在官网下载页犹豫半天，直接命令行装：Windows 上winget install Microsoft.VisualStudioCode，macOS 上brew install --cask visual-studio-code，Linux 可以下载 deb/rpm 包或者用 snap。

装完先不要急着找各种花哨主题，第一步是登录设置同步。用好 VS Code 的 Settings Sync 功能，注册一个账号就能把设置、扩展、快捷键全量同步。这个功能看似不起眼，但你在两台电脑之间切换时会感激它。我见过太多人电脑坏了之后，花一整天把扩展重新装一遍，那体验确实谈不上超能力。

3.2 我留下的 7 个扩展及为什么留着

扩展装上容易，装上之后半年不清理才是最常见的状态。我试过装几十个扩展，最后反而卡得不行。目前保留的这 7 个，都是日常高频使用、开了就不想关的：

这些扩展的选择标准是一致的：它们都在“减少上下文切换”这条线上。比如 Error Lens 让你不用切到终端看红字；GitLens 让你不用频繁运行git blame；Live Share 则是帮我远程调试的利器。装的时候用ext install命令，比如code --install-extension esbenp.prettier-vscode，也可以在扩展面板里搜索安装。

3.3 settings.json 里的私藏配置

扩展装完，真正的功夫在配置。默认的 VS Code 其实只能发挥三成功力，下面这段settings.json是我目前在用的精简版，每一行都有明确目的：

{ "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit" }, "editor.minimap.enabled": false, "editor.renderWhitespace": "boundary", "files.eol": "\n", "files.exclude": { "**/node_modules": true, "**/.git": true, "**/dist": true }, "git.autofetch": true, "terminal.integrated.fontFamily": "Cascadia Code", "typescript.updateImportsOnFileMove.enabled": "always", "search.useIgnoreFiles": true }

这里最容易被忽略的是files.exclude。把node_modules从文件树里隐藏掉之后，编辑器左边栏瞬间清爽，搜索也会更快。updateImportsOnFileMove.enabled是 TypeScript 项目移动文件时的自动修正 import 路径，强烈建议开着，不然手动改路径改到怀疑人生。eol统一成\n，是为了避免团队里 Windows 和 macOS 混用时换行符不一致造成的诡异 diff。

4. 终端层：让命令行真正起飞

4.1 先挑一个顺手的终端外壳

编辑器再强，终端依然是绕不开的主战场。Windows 上我推荐 Windows Terminal，搭配 PowerShell 7 使用，不要再用系统自带的古老 PowerShell 5。macOS 上 iTerm2 依然是老牌王者，但如果你懒得折腾，直接用系统自带 Terminal 也问题不大。Linux 用户建议用 Tilix 或者直接终端加 tmux。

终端外壳的选择其实比表面看起来重要得多。它决定了你能否用快捷键在多个标签页之间横跳、能否自定义配色、能否让各种命令行工具高亮输出。Windows Terminal 的设置里有一个“默认终端应用程序”的选项，记得把 Windows Terminal 设为默认，否则每次在 VS Code 里调出终端，打开的可能是老窗口。

4.2 四件套：fzf、ripgrep、bat、zoxide

这四件工具可以说是我本地环境里性价比最高的投资。用生活化的方式解释：ripgrep 是“代码里的搜索引擎”，比传统 grep 快很多；fzf 是“模糊匹配器”，你能用它快速在文件列表、历史命令里筛选；bat 是 grep 输出的“美容师”，带语法高亮和行号；zoxide 是“目录记忆神器”，你只要能模糊记起某个路径关键字，它就把你送过去。

安装命令很简单：

# macOS brew install fzf ripgrep bat zoxide # Debian/Ubuntu sudo apt install fzf ripgrep bat

装完还需要在 shell 配置文件里加初始化代码。zsh 用户如果用了 oh-my-zsh，可以把zoxide的初始化加在.zshrc末尾；PowerShell 用户则要装一个 PSReadLine 的预测模块。这里有一步最容易被漏掉：fzf 在 zsh 下要记得source /usr/share/doc/fzf/examples/key-bindings.zsh，否则按Ctrl+R不会弹出历史命令模糊搜索界面。

4.3 把高频操作交给 alias 和函数

工具装好只是第一步，真正提高效率的是把它们串起来。我给自己定义了下面这几条 alias，都是高频操作：

alias zz='zoxide' alias gs='git status -sb' alias gl='git log --oneline --graph --all -20' alias cat='bat' alias rgf='rg --files | fzf --preview "bat --color=always {}" --preview-window=right:60%'

其中rgf是我用得最多的一个函数式 alias：把项目里所有文件名交给 fzf，选中之后右侧直接预览文件内容，回车就打开编辑器。这个流程替代了我在文件树里一层一层点击的习惯，跨目录移动时尤其好用。你不需要照抄这些，但建议从自己最高频的三个动作出发，给它们各自做一个别名。

5. 环境层：Docker 与项目隔离

5.1 为什么一定要用容器隔离

很多人对 Docker 的第一反应是“重”，但其实真正重的是一堆项目依赖互相打架。前端项目要 Node 16，后端项目要 Node 20，数据库版本还不一样，这时候你在本地直接装一个全局 Node，很快就会被折腾到心态崩。Docker 的思路是把每个项目的运行时、依赖、服务全部装进独立的小箱子，各自互不干扰，还能源目录打包带走。

装完 Docker 之后，我强烈建议你做一个验证：跑一个最小的 hello world 容器，确认整个链路是通的。命令是docker run --rm hello-world。如果命令行卡住，大概率是网络拉取镜像的问题，优先检查配置的镜像加速，而不是直接重装 Docker。

5.2 Dev Container：让 VS Code 直接进容器

Docker 本身解决的是“环境隔离”，而 Dev Container 解决的是“在隔离环境里写代码”。它们的协作逻辑是：项目根目录放一个.devcontainer/devcontainer.json，VS Code 检测到之后弹窗提示“Reopen in Container”，点一下，整个编辑器就重新连接到容器里了，本机只需要一个纯净的 VS Code。

一个最小配置长这样：

{ "name": "superpowers-dev", "image": "mcr.microsoft.com/devcontainers/typescript-node:18", "forwardPorts": [3000], "postCreateCommand": "npm install", "customizations": { "vscode": { "extensions": ["esbenp.prettier-vscode", "dbaeumer.vscode-eslint"] } } }

这里面的postCreateCommand值得多说一句：它会在容器创建后自动装上项目依赖，通过这个机制，新同事把仓库 clone 下来，一键进入容器后不用再手动跑npm install，省掉了很多“你先把环境装一下”的沟通成本。同时扩展列表也可以跟着项目走，你在 VS Code 市场装了什么扩展，容器里就会自动装什么。

5.3 端口、数据卷和常见配置细节

容器开发中容易踩的坑有三个：端口、数据卷、持久化。forwardPorts只是把容器里的端口暴露到你本机，但它不会自动解决端口冲突。如果你本机已经有服务占了 3000 端口，容器还是会启动失败或端口映射异常，所以我习惯在启动之前先lsof -i :3000检查一下占用。数据卷方面，postCreateCommand里跑完npm install之后，依赖实际上存在容器内部，一旦重建容器就要重新安装，因此我通常会把 node_modules 之外的数据目录用 volume 挂载到本机，防止容器重建时丢数据。

我的建议是：如果只是写代码，把整个项目目录挂载进容器就够了；如果有数据库或缓存数据需要保留，再单独挂数据卷。这样隔离性和持久性基本都能兼顾。

6. 常见问题与排查技巧实录

6.1 扩展装了但不生效

这类问题十次里有八次是配置文件冲突。比如你同时装了 Prettier 和某个格式化扩展，settings.json里没指定defaultFormatter，编辑器就会随机挑一个，导致你按下Shift+Alt+F发现代码被格式化成了另一种风格。解决办法是在settings.json里显式指定每个文件类型的默认格式化工具，并且到扩展管理器里禁用其他同类扩展。

另一种可能是扩展装在“用户”级但项目里有.vscode/settings.json覆盖了它。排查的时候不要东猜西猜，直接打开命令面板，输入Developer: Print Settings，看实际生效的是哪一层配置。这条命令能直接输出最终合并结果，避开“我明明设置了但没用”的盲区。

6.2 终端启动慢、命令找不到

终端启动慢通常不是单一原因。最常见的是 shell 配置文件里加载了太多东西，比如每个终端都初始化 oh-my-zsh 的几十个插件，还有nvm、zoxide、fzf的初始化脚本。我建议做一次减法：把不常用的插件全部移除，nvm加上--no-use参数延后加载，让初始化只保留核心的东西。这样每次开新终端省下的一两秒钟，日积月累其实非常可观。

命令找不到则大概率是 PATH 没有配置好。Windows 用户最容易遇到这种问题，原因是安装工具时没有把安装目录写入用户 PATH。用where命令在 Windows、which在 mac/Linux 上，能直接看出你到底调用了哪个路径下的程序。排查原则就一条：先确认命令的真实路径，再确认 PATH 顺序，最后确认别名有没有覆盖系统命令。

6.3 Docker 权限异常和端口冲突

Linux 上装完 Docker，第一次跑docker ps可能会提示 permission denied。这不是 Docker 坏了，而是当前用户没有加入 docker 用户组的问题。用sudo usermod -aG docker $USER把用户加进去，然后重新登录一次即可。macOS 和 Windows 上的 Docker Desktop 相对省心，但偶尔也会出现进程没退干净导致的端口占用，这时直接重启 Docker Desktop 进程组往往比手动杀掉容器更快。

端口冲突是最容易误判的一类问题。容器内明明在 3000 端口跑着服务，但浏览器打开页面却是另一个应用。原因无非是本机 3000 端口被某个旧进程占用，而 Docker 反复映射失败。排查命令我每次都推荐这三步：lsof -i :3000查看本机占用，docker ps -a查看容器状态，docker logs 容器名看日志里有没有端口 bind 失败。把这三步走完，八成问题都能定位。

6.4 配置漂移与团队同步

配置漂移是指：你新装了一台机器，凭记忆把设置重配一遍，结果和原来的环境差了很多。这个问题的根治方法是把配置本身纳入版本管理。我会把 VS Code 的settings.json、extensions.json、终端初始化脚本，甚至.devcontainer配置都放进项目仓库或单独的 dotfiles 仓库里。新机器拿到之后，一条脚本拉下来复制到对应位置，十分钟内就能恢复八成生产力。

如果你在团队里推广这套环境，我建议先不要一次迁移所有项目。挑一个维护频率最高的项目试点，跑通之后再逐步复制到其他项目。原因在于，每个人的工作流差异其实比想象中大，直接命令式地让所有人改环境，反而会引起反感。先让愿意尝鲜的人用起来，等大家看到了实际收益，环境统一就会自然发生。

7. 收尾：一点个人体会

这套 Superpowers 环境我前后折腾了两年，期间重装过三次系统，也换过两台主力电脑。最深的体会是：工具链好不好用，不在于装得多，而在于有多少操作被你真正记进了肌肉记忆。我当前每天高频使用的工具其实不超过十个，但每一个都处在“不用思考就能用”的状态。配置同步这件事，从第一次系统崩溃之后我就养成了习惯，现在新电脑到手，基本是回车键敲几下的功夫就能进入工作状态。如果你也想给自己配一套，建议从终端四件套开始，感受几天之后再加容器层，一次只加一个工具，用顺手了再引入下一个。