先查PID再确认进程:Linux/macOS用lsof -i :端口或netstat -tulpn | grep,Windows用netstat -aon | findstr :端口+tasklist | findstr PID;若netstat查不到则检查WSL2/Docker,残留子进程需按PID整树终止,TIME_WAIT导致的瞬时冲突应避免频繁重启并改用--host 127.0.0.1。

Address already in use 错误怎么快速定位占用进程
错误里明确写着 OSError: [Errno 98] Address already in use 或 Windows 下的 [WinError 10048],说明端口已被某个进程绑定。别猜,直接查 PID:
- Linux/macOS:运行
lsof -i :8000(把8000换成你实际用的端口);若没装lsof,用netstat -tulpn | grep :8000 - Windows 命令行:
netstat -aon | findstr :8000,再用tasklist | findstr "12345"(把12345换成上一步看到的 PID)查进程名 - 如果
netstat查不到但依然报错——优先怀疑 WSL2 或 Docker Desktop:在 PowerShell 运行wsl -- lsof -i :8000,或Get-NetTCPConnection -LocalPort 8000 | Select-Object OwningProcess
杀不干净的 uvicorn 子进程怎么彻底清理
IDE 点“停止”按钮后服务看似退出,但 --reload 模式下 fork 出的子进程常残留,名字就是 python.exe,任务管理器里根本找不到。靠名字杀不准,必须按 PID 杀整棵树:
- Windows 上拿到 PID 后,用管理员权限 PowerShell 执行:
Stop-Process -Id 12345 -Force - Linux/macOS:先
ps aux | grep uvicorn确认,再kill -9 12345;若多个相关 PID,用kill -9 12345 67890一起干掉 - 更省事:直接关掉 PyCharm/VS Code,再
wsl --shutdown(如果用了 WSL2),比手动杀更可靠
换端口能绕过,但为什么一换回来就又冲突
不是运气差,是 TCP 的 TIME_WAIT 状态在起作用。Uvicorn 被 Ctrl+C 中断后,旧连接 socket 还在内核里挂几秒钟(通常 2–4 分钟),新进程立刻重绑同一端口就会撞上。这不是 bug,是协议安全机制。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
- 临时对策:加
--host 127.0.0.1启动,避免绑定到0.0.0.0引发的跨栈监听冲突(尤其 WSL2 场景) - 开发时别频繁 Ctrl+C + 回车:等几秒再启,或改用
uvicorn main:app --reload --port 8001固定换一个调试端口 - 别把
--port 8000当默认习惯——协作时别人也用 8000,部署时还得改配置,早晚会踩坑
NSSM 注册为 Windows 服务后端口释放不了
服务模式下进程更难杀,且 NSSM 默认不会清理子进程。关键不是“怎么杀”,而是“怎么避免残留”:
- 检查 NSSM 配置里的
Path:必须是完整路径,比如C:\myproject\venv\Scripts\uvicorn.exe,不能只写uvicorn -
Arguments里务必加上--host 127.0.0.1,减少网络栈干扰;--port建议避开 8000/8080 这类高危端口,比如用8088 - 修改完配置,点 NSSM 界面的
Test按钮验证能否干净启停;测试通过后再net stop FastAPI_Service && net start FastAPI_Service
真正麻烦的从来不是“端口被占”,而是占着的进程你不知道它从哪来、有没有其他依赖、杀完会不会影响别的服务。查 PID 是起点,理解 TIME_WAIT 和 WSL2/Docker 的端口映射机制,才是不再反复踩坑的关键。

















