文章目录端口被占时你真正卡在哪现象与手工排查成本脚本要达成的行为跨平台怎么查、怎么杀统一入口Windowsnetstat 对 PIDtaskkill 强制结束Unix先 lsof再退到 ss先看清楚再杀杀完必须复核打印比「静默强杀」更重要退出码表达结果落地时别踩的坑权限与系统进程端口合法性子进程调用姿势本地起Spring Boot、Vite、uvicorn时报错里最常见的一句是Address already in use。端口被占服务起不来。手敲lsof/netstat再kill在 macOS 和 Windows 上命令还不一样换机器就得重记一遍。下面用一套跨平台 Python 脚本把「查占用 → 看进程 → 结束 → 再确认」串起来Win / macOS / Linux 同一入口。端口被占时你真正卡在哪现象与手工排查成本典型报错大致是OSError: [Errno 48] Address already in use bind: address already in use手工路径通常是系统查谁占了端口结束进程Windowsnetstat -ano再对最后一列 PIDtaskkill /PID … /FmacOS / Linuxlsof -iTCP:端口 -sTCP:LISTENkill -9 PID问题不在命令难而在三件事叠在一起命令不统一、输出要自己筛、杀完还得再查一遍确认端口真的空了。脚本要解决的就是这三步而不是再包一层花哨 UI。脚本要达成的行为一次调用只处理一个端口号流程固定校验端口在1–65535按当前平台找出占用该端口的 PID 列表打印每个 PID 的进程名与命令行再结束再次查找若仍有占用非零退出跨平台怎么查、怎么杀统一入口在仓库根目录用uv跑依赖由pyproject.toml管不必本机另装一套 Python 环境套路uv run os/kill_port.py8080参数就是端口整数。日志走统一Logger场景名kill-port方便事后在logs/里按日期翻。Windowsnetstat 对 PIDtaskkill 强制结束查找侧跑netstat -ano用正则匹配「地址列里带:端口」的行取最后一列数字当 PIDport_rere.compile(rf(?:^|\s)\S*:{port}\s)# 行末字段是 PIDpid 0 才收录结束侧用taskkill /PIDpid/F进程详情优先Get-CimInstance Win32_Process拿Name与CommandLine失败再退到tasklist /FI PID eq …至少能打出进程名避免「只看到数字、不知道杀的是谁」。Unix先 lsof再退到 ssmacOS / Linux 优先lsof-nP-iTCP:8080-sTCP:LISTEN-t-nP避免主机名/端口名解析拖慢-t只吐 PID方便脚本收集。LISTEN 查完后再补一轮 TCP / UDP 的-t把非 LISTEN 但仍占着该端口的连接进程也捞进来。若lsof不可用或没命中退到ss-lptunH从输出里用pid(\d)抽 PID。两边都没有可用工具时直接报错退出而不是假装「端口空闲」。结束进程先kill -9 pid失败再用os.kill(pid, SIGKILL)。ProcessLookupError视为已不存在算成功PermissionError记失败并提示权限不足。win32其它仍有清空输入端口平台netstat -anolsof / ss汇总 PID打印 name cmdlinetaskkill 或 kill -9再次查找退出码 1退出码 0先看清楚再杀杀完必须复核打印比「静默强杀」更重要找到 PID 后脚本会先打一行列表例如发现 1 个进程 PID12345 namenode cmdlinenode ./server.js 正在结束 PID 12345 (node)... 已结束 PID 12345开发机上经常是「上次没关干净的 node / java / python」。看见 cmdline才知道这是残留调试进程还是系统服务误伤风险。先 log 再 kill比把确认交互塞进 CI 更适合本机一键清理场景。退出码表达结果情况退出码端口本就空闲0打「无需清理」全部结束且复核为空0有 PID 杀失败或杀完仍占用1复核再调一次同一套find_pids。只信taskkill/kill的返回码不够子进程、短时重启、权限不够时端口可能马上又被占上。落地时别踩的坑权限与系统进程杀系统服务或其它用户进程会碰到权限失败。脚本应把失败 PID 数清楚打出而不是吞掉 stderr。需要提权时在对应系统上用管理员 /sudo再跑同一命令脚本本身不偷偷提权。端口合法性入口处直接拒绝非法值ifnot1args.port65535:logger.error(端口号必须在 1-65535 之间)return1避免把奇怪参数拼进lsof -iTCP:…或 netstat 正则。子进程调用姿势查找与结束都用参数列表调用subprocess.runshellFalsestdout/stderr 捕获为文本。跨平台路径、带空格的命令行更稳也少一层注入面。把这套逻辑收成仓库里的一个小命令后日常就是服务起不来 →uv run os/kill_port.py 端口→ 看日志确认杀的是谁 → 再启服务。同一套代码在笔记本macOS和公司 Windows 开发机上行为一致省掉「这台机器该敲哪条命令」的切换成本。