portcheck

portcheck

查看哪些程序正在使用端口、查找空闲端口、释放端口并检查远程主机。
一个静态二进制文件，适用于 macOS、Linux 和 Windows。

端口已被占用？

npx portcheck-cli kill 3000

portcheck 会显示占用端口的程序及其启动者，征求你的许可后再温和地停止它 （绝不会触碰系统进程）。它是更安全的 kill-port， 无需事先安装任何东西。

针对你遇到的错误提供解决方案：Node.js、Next.js、Vite · Python、Django、Flask · Docker · Rails、Spring Boot、Go、.NET、PHP · macOS · Windows · Linux

功能

	命令
🔍	portcheck list -l	列出所有监听套接字及其进程、PID 和用户
✅	portcheck 3000	端口是否空闲？如果不是，哪个进程占用了它？脚本可使用退出码 0 或 1
🆓	portcheck free 3000-3999 -n 3	查找空闲端口，并通过实际绑定进行验证
🛑	portcheck kill 8080	先发送 SIGTERM，再发送 SIGKILL；拒绝终止 PID 1、你的 Shell 和系统进程
🧹	portcheck servers --older-than 1d	找出你忘记关闭的开发服务器：按运行时间从长到短列出监听进程及其项目和运行时长；使用 --stop 清理
📡	portcheck scan db.internal -p 5432	对远程主机进行限速 TCP 连接检查。无需 root 权限
⏳	portcheck wait db:5432 -t 60s	阻塞等待服务接受连接，或等待端口空闲。专为 CI 打造
▶️	portcheck run --port 3000 --next -- npm run dev	在空闲端口上启动命令（$PORT、{port}）；使用下一个空闲端口，或停止占用端口的进程
🩺	portcheck doctor	检查 .portcheck.yaml 中列出的端口，并为每个问题提供修复方案
🖥️	portcheck	实时、可排序、可筛选的 TUI。无需退出即可停止进程
🌐	浏览器扩展	Edge（以及 Chrome）：查看哪个进程为 localhost 标签页提供服务；无人监听时显示 off；可从弹出窗口停止进程（指南）
🧩	VS Code 扩展	将终端中的“端口已被占用”错误变为一键修复；在侧边栏查看监听端口（指南）
🤖	portcheck mcp	AI 助手（Claude Code、Cursor、Copilot……）可自行检查和释放端口（指南）
⌨️	Raycast	从 Mac 启动器搜索端口、检查端口、终止占用端口的进程并查找空闲端口
✍️	Neovim	:Portcheck 选择器，可检查／终止进程／查找空闲端口；在 :terminal 中遇到“端口已被占用”时可停止占用进程
🔌	菜单栏／托盘应用	在 macOS 菜单栏或 Windows／Linux 系统托盘中查看监听端口：两次点击即可停止进程、打开或复制
🧠	JetBrains 插件	IntelliJ IDEA、WebStorm、PyCharm、GoLand……：“运行／调试”中遇到“端口已被占用”时，可选择 停止并重新运行；另有“端口”工具窗口

VS Code 扩展

当开发服务器因端口被占用而启动失败时，扩展会指出占用端口的进程并提供修复方式：停止该进程后重新运行，或改用下一个空闲端口重新运行。

从 VS Code Marketplace 安装 Portcheck - Port in Use Fixer（在 VS Code 中搜索“portcheck”），或从 Open VSX 安装（适用于 VSCodium、Cursor、Windsurf）。portcheck 内置其中。

JetBrains 插件

在 IntelliJ IDEA、WebStorm、PyCharm、GoLand 及其他 JetBrains IDE 中，当运行配置因端口被占用而失败时，通知会指出占用端口的进程，并提供 停止并重新运行 选项；端口 工具窗口会列出所有监听端口。

▶ 观看 20 秒演示

从最新版本下载并安装 portcheck-jetbrains-<version>.zip（Settings → Plugins → ⚙ → Install Plugin from Disk…）；该插件正在 JetBrains Marketplace 审核中（指南）。

浏览器扩展

在每个 localhost 标签页上，徽章会显示为其提供服务的进程名称；如果没有进程监听，则显示 off；弹出窗口会显示启动该进程的人，并安全地停止它。

从 Microsoft Edge Add-ons 安装 Portcheck - Localhost Port Inspector，然后运行一次 portcheck browser install。 对于 Chrome、Brave 和 Chromium，请从 最新版本 下载 zip 并加载（指南）。

亮点

• 在所有操作系统上使用相同的命令和输出。 它取代 lsof -i、netstat -ano、ss -ltnp 和 kill。
• 专为脚本设计。 --json 遵循版本化架构，退出代码稳定，结果输出到 stdout，消息输出到 stderr。
• 支持容器和 WSL。 Docker/Podman 发布的端口或从 WSL 转发的端口会显示容器或发行版；kill 会告诉你如何在那里停止进程，而不是杀掉代理。
• 如实说明权限限制。 对于隐藏的进程所有者，会标记为隐藏，并提示如何查看。
• 也是一个 Go 库。 请参阅 pkg/。

安装

# Homebrew (macOS, Linux)
brew install roystondwork-dev/tap/portcheck

# winget (Windows; the package is waiting for Microsoft's review)
winget install roystondwork-dev.portcheck

# Scoop (Windows)
scoop bucket add portcheck https://github.com/roystondwork-dev/scoop-bucket
scoop install portcheck

# npm (any OS): run it without installing
npx portcheck-cli 3000

# PyPI (any OS)
pipx install portcheck-tool

# Go 1.26+
go install github.com/roystondwork-dev/portcheck/cmd/portcheck@latest

amd64/arm64 的 .deb、.rpm、.apk 和压缩包可在发布页面获取。涵盖所有制品的校验和文件使用 cosign（无密钥）签名，发布包还附带 SBOM 和 SLSA 来源证明；请参阅验证下载文件。

快速入门

$ portcheck 3000
PORT  PROTO  STATUS  PID    PROCESS  USER
3000  tcp    in-use  42379  node     alice

$ portcheck kill 3000
About to terminate:
  PID 42379  node  (port 3000)
Proceed? [y/N] y
PID    PROCESS  RESULT      DETAIL
42379  node     terminated

$ portcheck free 3000-3999 -n 2 -o plain
PORT
3000
3001

$ portcheck list -l --json | jq '.data.sockets[] | {port: .localPort, name: .process.name}'

📖 文档： https://roystondwork-dev.github.io/portcheck/ （快速入门 · 指南 · CLI 参考 · 各操作系统的权限 · 常见问题）

用作 Go 库

res, err := inspect.NewSystem().List(ctx, inspect.Filter{Ports: portspec.Single(3000), ListeningOnly: true})
if err != nil {
	log.Fatal(err)
}
for _, s := range res.Sockets {
	if s.Process != nil { // nil when the owner is hidden from your user
		fmt.Println(s.PID, s.Process.Name)
	}
}

请参阅库指南，了解 portspec、inspect、freeport、killer、scan、waitfor 和 containers。

负责任地使用

portcheck scan 会建立普通的 TCP 连接，不具备隐蔽功能。只能扫描你拥有或获准测试的主机和网络。

参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解设置和标准（每项更改都会在 Linux、macOS 和 Windows 上进行测试，且库的覆盖率门槛为 100%），并查看 TASKS.md 了解路线图和状态。 请遵守行为准则，并按照 SECURITY.md 中的说明私下报告漏洞。

许可证

MIT © 2026 Royston D 和 portcheck 贡献者