一条命令杀死占用端口的进程

English | 简体中文

以前:

# 查找进程
lsof -ti:3000
# 手动 kill
kill -9 <PID>

现在:

killport 3000
# ✓ Killed process 12345 (node) on port 3000

每个开发者都遇到过这些痛点：

• 🔴 "端口 3000 已被占用"
• 🔴 Google 搜索"如何在 Mac 上 kill 端口"
• 🔴 复制粘贴一些 lsof 命令
• 🔴 每天重复 5 次

killport 终结这种痛苦。一条简单命令。随处可用。

• ⚡ 快速: 毫秒级 kill 进程
• 🎯 简单: 一条命令，无需记忆复杂参数
• 🌍 跨平台: Linux、macOS、Windows 全支持
• 🛡️ 安全: kill 前显示进程信息并确认
• 📋 详细: 显示进程名、PID、用户等信息
• 🔍 批量: killport 3000 8080 5000
• 🎨 交互式模式: 无参数运行 killport，可视化选择要 kill 的进程
• 📜 智能滚动: 自动适应终端高度，支持大量进程显示
• 🔢 端口排序: 按端口号从小到大自动排序
• ⚙️ 配置文件: 支持自定义端口预设组
• 🚀 快捷命令: killport --dev 一键清理开发端口
• 📦 预设组: killport preset frontend 批量管理端口
• 👀 Watch 模式: killport watch 3000 持续监控端口占用状态
• 🛡️ 保护模式: killport protect 5432 防止误杀重要端口
• 📌 系统托盘: killport tray 常驻系统托盘，快速管理端口

# 克隆仓库
git clone https://github.com/TNT-Likely/killport.git
cd killport

# 构建并安装
make install

# 或仅构建
make build

go install github.com/TNT-Likely/killport@latest

访问 Releases 页面 下载对应平台的二进制文件。

# Kill 占用 3000 端口的进程
killport 3000

# 输出:
# Port 3000 is used by:
#   PID:  12345
#   Name: node
#   User: yourname
#
# Kill this process? [y/N]: y
# ✓ Killed process 12345 (node) on port 3000

# 无参数运行，进入交互式模式
killport

界面示例:

🔫 killport - Interactive Mode
🔍 Search: node_ (2/20)

  ▲ 5 more above...
  [✓] 3000    node          npm run dev
❯ [ ] 8080    main          ./main
  [ ] 🛡️ 5432    postgres      /opt/homebrew/opt/postgresql@14/bin/postgres
  ▼ 10 more below...

Showing 6-10 of 20 (filtered from 50) • Selected: 1
↑/k: up • ↓/j: down • Space: select • x/d: kill • p: protect • /: search • q: quit

操作说明:

• ↑/↓ 或 k/j: 移动光标
• Space: 选择/取消选择进程
• x 或 d: kill 选中的进程
• p: 将选中的端口加入保护
• /: 进入搜索模式，可搜索端口号、进程名、命令
• ESC: 清除搜索/退出
• q: 退出

搜索功能:

• 按 / 进入搜索模式
• 输入端口号、进程名或命令关键词实时过滤
• Enter 确认搜索，ESC 取消并清除过滤
• 支持模糊匹配，例如搜索 "node" 会显示所有包含 node 的进程

# Kill 多个端口
killport 3000 8080 5000

# 清理常用开发端口 ✨ NEW
killport --dev
# 清理: 3000, 8080, 5173, 5000, 4200

# 使用预设端口组 ✨ NEW
killport preset frontend
# 清理前端开发相关端口

killport preset backend
# 清理后端开发相关端口

killport preset database
# 清理数据库端口

# 创建默认配置文件
killport init

# 强制覆盖已存在的配置
killport init --yes

配置文件位置: ~/.killport.yaml 或 ~/.config/killport/config.yaml

presets:
  # 开发环境常用端口
  dev:
    - 3000  # React, Next.js
    - 8080  # 通用后端
    - 5173  # Vite
    - 5000  # Flask, Create React App
    - 4200  # Angular

  # 前端开发端口
  frontend:
    - 3000  # React, Next.js
    - 5173  # Vite
    - 5000  # CRA
    - 4200  # Angular
    - 8080  # Vue

  # 后端开发端口
  backend:
    - 8080  # Spring Boot, Tomcat
    - 8000  # Django, FastAPI
    - 9000  # PHP-FPM
    - 3001  # Node.js
    - 5000  # Flask

  # 数据库端口
  database:
    - 5432  # PostgreSQL
    - 3306  # MySQL
    - 27017 # MongoDB
    - 6379  # Redis

  # 自定义预设
  myproject:
    - 3000  # 前端
    - 8080  # API 网关
    - 8001  # 用户服务
    - 6379  # Redis

# 保护端口（可选）
# 被保护的端口无法被 killport 杀死
protected_ports:
  - 5432  # PostgreSQL
  - 3306  # MySQL
  - 27017 # MongoDB

持续监控端口的占用状态，实时显示占用/释放事件：

# 监控 3000 端口
killport watch 3000

# 输出示例:
# 👀 Watching port 3000... (Press Ctrl+C to stop)
#
# [19:30:15] 🟢 Port 3000 occupied
#            PID: 12345, Process: node
#            Command: npm run dev
#            User: yourname
#
# [19:32:20] ⚪ Port 3000 freed
#
# [19:35:10] 🟢 Port 3000 occupied
#            PID: 23456, Process: node
#            Command: npm start

使用场景:

• 调试端口占用问题
• 监控服务重启
• 观察进程生命周期

防止误杀重要端口（如数据库）：

# 保护端口
killport protect 5432   # 保护 PostgreSQL
killport protect 3306   # 保护 MySQL

# 列出所有保护端口
killport list-protected
# 输出:
# 🛡️  Protected Ports:
#    5432
#    3306

# 移除保护
killport unprotect 5432

# 尝试 kill 被保护的端口
killport 5432
# 输出:
# 🛡️  Port 5432 is protected and cannot be killed
#     Use 'killport unprotect 5432' to remove protection

保护端口会在以下场景生效:

• 直接 kill: killport 5432
• 批量 kill: killport 3000 5432 8080
• 预设组: killport preset database
• 开发模式: killport --dev
• 交互式模式: killport (被保护的端口会显示 🛡️ 图标)

常驻系统托盘，快速管理端口：

# 启动系统托盘（默认后台运行）
killport tray

# 前台运行（用于调试）
killport tray --foreground

# 停止托盘
killport stop-tray

托盘功能:

• 📊 实时显示当前占用的端口数量（菜单栏显示 "🔫 N"）
• 📋 查看活跃端口列表（最多显示20个，超出可点击"View All"查看全部）
• ⚡ 每个端口支持右键操作：
  • ❌ Kill Process - 终止进程
  • 🛡️ Protect/Unprotect Port - 保护/取消保护端口
• 🔍 端口搜索功能（直接打开搜索模式）
• 🔄 智能刷新（每30秒自动检测，仅在有变化时更新UI）
• 📦 预设组快捷操作（dev、frontend、backend、database等）
• 🛡️ 显示保护端口列表
• 🎯 快捷打开交互式模式
• 🧹 快捷清理开发端口
• 💡 使用文字显示，兼容性更好
• 🚀 默认后台运行，不占用终端

托盘菜单示例:

🔄 Refresh
───────────────
📋 Active Ports
   Port 3000 - node (PID: 12345)
      ❌ Kill Process
      🛡️  Protect Port
   🛡️ Port 8080 - main (PID: 23456)  # 已保护的端口
      ❌ Kill Process
      🔓 Unprotect Port
   ...
   📋 View All 25 Ports  # 超过20个端口时显示
───────────────
📦 Presets
   dev
   frontend
   backend
   database
───────────────
🛡️  Protected Ports
   Port 5432
   Port 3306
───────────────
🔍 Search Ports        # 搜索端口
🎯 Interactive Mode
🧹 Clear Dev Ports
───────────────
ℹ️  About
❌ Quit

使用场景:

• 后台常驻监控
• 快速响应端口占用
• 右键端口选择 Kill 或 Protect
• 搜索特定端口或进程
• 无需打开终端即可管理端口
• 一键使用预设组清理端口
• 适合开发者日常使用

操作说明:

1. 查看端口: 点击托盘图标 "🔫 N" 查看端口列表
2. 操作端口: 点击任意端口展开子菜单，选择 Kill 或 Protect
3. 搜索端口: 点击 "🔍 Search Ports" 打开搜索模式
4. 批量清理: 点击预设组（如 dev）一键清理
5. 停止托盘: 运行 killport stop-tray 或从菜单选择 Quit

注意:

• 系统托盘需要GUI环境支持（macOS/Windows/Linux桌面环境）
• 默认自动后台运行，日志文件位于 ~/.killport-tray.log
• 使用 killport stop-tray 停止托盘进程
• 使用 --foreground 选项可以前台运行（用于调试）
• 详细说明请参考 TRAY_GUIDE.md

# 列出所有占用端口的进程
killport list

# 预览模式（不实际 kill）
killport 3000 --dry-run

# 强制 kill，跳过确认（适合脚本）
killport 3000 --yes

# 详细输出
killport 3000 --verbose

# 查看版本
killport --version

# 查看帮助
killport --help

# 早上开始工作
killport --dev

# 或使用自定义预设
killport preset myproject

# 启动交互式模式
killport

# 使用方向键选择
# 空格标记要 kill 的进程
# 按 x 执行

#!/bin/bash
# 清理开发环境
killport --dev --yes

# 启动新服务
npm run dev

# 从项目 A 切换到项目 B
killport preset project-a
# ... 启动项目 B

# 保护所有数据库端口
killport protect 5432   # PostgreSQL
killport protect 3306   # MySQL
killport protect 27017  # MongoDB

# 现在可以安心使用 --dev 或 preset，不会误杀数据库
killport --dev

# 监控端口，观察服务重启
killport watch 3000

# 在另一个终端测试你的服务
# Watch 会实时显示端口占用变化

# 启动系统托盘
killport tray

# 托盘会显示端口数量，右键可快速 kill
# 适合开发者日常使用，无需频繁打开终端

killport 使用平台特定的方法查找并 kill 进程：

• Linux: 使用 lsof 或 ss 命令
• macOS: 使用 lsof 命令
• Windows: 使用 netstat 和 taskkill

所有功能封装在统一的简单接口中。

Q: 使用安全吗？ A: 安全。killport 默认会显示进程信息并请求确认。使用 --yes 可跳过确认（适合 CI/CD）。

Q: 如果端口没被占用怎么办？ A: killport 会提示 "Port 3000 is not in use" 并正常退出。

Q: 支持 Docker 容器吗？ A: 支持，如果端口暴露在宿主机上。

Q: 可以在 Shell 脚本中使用吗？ A: 当然！使用 killport 3000 --yes 跳过确认提示。

Q: 需要 root/管理员权限吗？ A: 仅当要 kill 其他用户的进程时需要。kill 自己的进程不需要特殊权限。

# 克隆仓库
git clone https://github.com/TNT-Likely/killport.git
cd killport

# 安装依赖
make deps

# 构建
make build

# 运行测试
make test

# 运行（带参数）
make run ARGS="3000"

# 构建所有平台
make build-all

# 格式化代码
make fmt

欢迎贡献！请随时提交 Pull Request。

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 提交 Pull Request

MIT © TNT-Likely

Made with ❤️ by developers, for developers

如果 killport 为你节省了时间，请给个 ⭐