别再对着 PID 猜服务：用 ports 按项目定位并安全释放本地开发端口
本地开发里最熟悉也最容易处理粗暴的一类报错，是 address already in use。前端想占用 3000 端口、API 想监听 8000，终端只告诉你端口已经被使用。接着通常是 lsof -i :3000，得到一个 node 和一个 PID；再执行 kill -9。问题在于：PID 是操作系统的视角，不是项目的视角。它可能是昨天忘记关闭的 Next.js，也可能是正在运行的数据库，甚至可能是 Docker 端口代理。
刚发布的开源 CLI ports 想解决的不是“如何杀掉一个进程”，而是“这台机器上正在监听的服务属于哪个项目”。它是一个 Go 编写的本地 CLI，采用 MIT 许可证；仓库同时含有网站代码，所以 GitHub 的主要语言字段显示 TypeScript，不应把它误称为纯 TypeScript 工具。它不启动服务、不充当守护进程，也不需要账号或遥测；工作是观察监听端口，并在你明确要求时终止相应服务。
先把端口冲突还原成“项目”
传统命令当然仍有价值。ss -ltnp 适合快速查看监听套接字，lsof -i :3000 适合按端口找 PID。但它们没有回答一个日常决策所需的问题：这个进程来自哪个工作目录、是不是某个 Compose 服务、与 8000 和 5432 是否属于同一套开发环境。
安装方式有多种。macOS 可用 Homebrew；Linux 和 macOS 可使用官方安装脚本，也可以在本机已有 Go 工具链时直接安装：
curl -fsSL https://ports.tools/install | sh go install github.com/pyjeebz/ports@latest ports
curl | sh 方便，但本质上会执行远程脚本。对受控工作站或生产跳板机，更稳妥的做法是查看 Release 页面 的二进制与校验文件，或审查安装脚本后再使用。无论哪种安装方式，第一步都应只是运行 ports，确认输出中的端口、进程、项目与运行时间是否符合预期。
README 展示的典型表格包含 PORT、PROCESS、PROJECT 和 UPTIME。因此开发者看到的不再是孤立的 48391，而是类似“Next.js 属于 ~/projects/shop，PostgreSQL 是 docker: shop-db”。这个差别很重要：一次端口占用往往不是单一故障，而是上一次开发环境没有完整退出。
推荐操作顺序：查找、确认、再停止
ports 的几个子命令不复杂，但适合组成一个风险较低的日常流程：
ports find shop ports find postgres ports free 3000 ports kill shop ports --json ports find shop --json
这里要特别区分 free 和 kill。ports free 3000 的语义是处理占用 3000 的服务；ports kill shop 则可能匹配同一项目下的多个服务。排查“前端端口被旧进程占用”时，前者更精确；确认整个项目已经不需要时，后者更省事。不要把项目名写得过于宽泛，也不要跳过 find 直接执行停止命令。
工具默认先尝试 SIGTERM，最多等待约两秒让进程正常退出，之后才升级到 SIGKILL；--force 会直接走强制终止。这比开场就手工 kill -9 更适合开发场景，但它不是事务：有未保存状态的本地服务仍可能丢失工作。对于数据库、消息队列或正在执行迁移的服务，先看清项目和容器名称，再决定是否停止。
它如何推断“这是谁的服务”
这类 CLI 的价值取决于推断是否可解释。ports 使用 gopsutil 枚举 TCP 的 LISTEN 连接，并以 (pid, port) 去重：同一进程同时绑定 IPv4 与 IPv6 时，表格不会重复两行。对每个已知 PID，它读取可执行文件、命令行、当前工作目录和创建时间，再结合命令行识别常见框架。
项目归属不是凭端口号猜测。源码会从进程当前目录向上检查：若存在多个 .git，选择最外层的 Git 根目录，因而能把 monorepo 中不同服务归入同一个项目；若找不到 Git 根，则寻找最近的项目标记，例如 package.json、go.mod、pyproject.toml、Cargo.toml 或 pom.xml。这是一种有用但并非绝对正确的启发式：从临时目录启动的服务、没有工作目录信息的系统进程，都可能无法归类。
Docker 是另一个常见陷阱。宿主机上看到的常常只是 docker-proxy，直接杀它可能让端口映射异常，却没有按预期关闭容器。ports 会尝试把代理关联回容器，并在有 Compose 标签时显示项目与服务；停止时优先通过 Docker daemon 处理容器。若容器无法解析，工具会明确提示改用 docker stop，而不是假装已经安全处理。
对于 WSL2，它还会合并 Windows 一侧监听端口的观察结果。不过“看见”不等于“能从 Linux 杀掉”：Windows PID 不能直接接受 Linux 信号，应该在 Windows 的任务管理器或 taskkill 中结束。这种边界提示比把跨系统操作伪装成成功更可靠。
一个可复现的排障回合
假设你在 shop 仓库启动前端后收到 3000 端口冲突。不要立刻把端口号当成唯一线索。先运行 ports find shop，观察匹配结果是否同时包含前端、API 和数据库。若只想重新启动前端，应运行完整的 ports 表格，确认 3000 这一行的项目路径与框架；find 按框架、进程、项目和容器等文本上下文匹配，并不是按端口号过滤。只有当 3000 确实属于遗留开发服务器时，才执行 ports free 3000。
完成后重新启动前端，并再次运行 ports。这一步不是形式主义：它能确认新进程是否从预期目录启动、监听的是否仍是 3000、旧服务是否真的退出。如果 free 提示没有监听者，但应用仍报地址占用，应检查应用是否使用了 Unix socket、反向代理是否保留了连接，或者报错来自容器内部网络而非宿主机端口。端口工具看到的是宿主机 TCP 监听状态，不能替代应用自身日志。
还应注意扫描与终止之间的时间差。进程可能在你确认后自行退出，PID 也可能被系统复用。ports 在停止前会比较扫描到的创建时间和当前 PID 的创建时间；二者不一致时会拒绝把新进程误当成旧目标。这种防护不能替代人工判断，但说明“先列出、后执行”不是界面上的多余步骤，而是避免误杀的必要边界。对持续变化的本地环境，重新扫描通常比复用一分钟前的终端输出更安全。
在多人共享的开发机上，权限也是一个明确边界。工具会把无法识别归属的端口标记为未知，并提示使用 sudo 获取更多信息；这不意味着应该无差别地以管理员权限执行停止动作。正确做法是先用提升权限的观察结果确认所有者和用途，再回到最小必要权限处理。对不属于自己的服务、系统服务或 CI runner，交给对应的生命周期管理工具和负责人处理。
JSON 输出则适合把“观察”接入自己的脚本，而不是让脚本猜 PID。例如可以在启动开发环境前记录 ports --json 的输出，在测试结束后再比对哪些端口新增。脚本应把 JSON 当作诊断输入，并把实际终止动作放在人工确认或显式白名单之后。这样能避免自动化清理规则把同机另一个仓库的服务误认为垃圾进程。
何时该用，何时不要把它当进程管理器
ports 最适合频繁切换多个本地仓库、混合使用 Node、Python、Docker 和 WSL 的开发者。它减少的是“端口—PID—进程名—工作目录”之间来回跳转的认知成本，尤其适合解决遗留开发服务器、端口冲突和 Compose 服务难以辨识的问题。
但它不是 supervisor，也不会替代 Docker Compose、systemd、foreman 或应用自身的生命周期管理。线上服务需要可审计的部署、健康检查和重启策略；本地工具只应作为诊断与定点清理的一环。一个实用的团队约定是：先运行 ports 或 ports find 保存现场，再执行 free 或 kill；如果端口仍被占用，再回到 ss、应用日志和容器状态排查根因。这样既能快速恢复开发，也不会把“释放端口”误当成“问题已经解决”。