端口被占但netstat查不到进程，大概率是WSL2或Docker Desktop在Linux内核中监听，其状态不反映在Windows netstat中；需用wsl lsof或Get-NetTCPConnection查PID并强制终止。
端口被占但 netstat 查不到进程？先盯住 WSL2 和 Docker Desktop
Windows 上用 netstat -ano | findstr :8000 查不到任何结果，却仍报 OSError: [WinError 10048]，大概率不是“真没进程”，而是进程藏在 WSL2 或 Docker Desktop 的 Linux 内核里。WSL2 默认把端口映射到 Windows 主机，但它的监听状态不会出现在 Windows 的 netstat 输出中。
验证方法：在 PowerShell 中运行 wsl -d Ubuntu-22.04 -- lsof -i :8000（把 Ubuntu-22.04 换成你实际的发行版名）；或者直接进 WSL 终端执行 lsof -i :8000。如果看到 uvicorn 或 python 进程，就是它。
解决建议：
- 关掉 WSL2：运行
wsl --shutdown，再试启动 - 关掉 Docker Desktop（它默认启用 WSL2 后端），再试
- 不想关？换端口启动时加
--host 127.0.0.1，避免跨网络栈绑定冲突
PyCharm / VS Code 调试中断后残留进程怎么杀干净？
IDE 点红色停止按钮 ≠ 进程真正退出。Uvicorn 在 --reload 模式下会 fork 子进程，主进程退出后子进程可能还在跑，且名字常是 python.exe，不带 uvicorn 字样，在任务管理器里很难识别。
更可靠的办法是按 PID 杀，而不是按名字：
- 先查所有监听 8000 的 TCP 连接：
Get-NetTCPConnection -LocalPort 8000 | Select-Object OwningProcess - 拿到 PID 后，强制终止整个进程树：
Stop-Process -Id <pid> -Force</pid> - 如果提示“访问被拒绝”，说明是系统级或高权限进程，改用管理员 PowerShell 执行
别依赖 IDE 自带的“终止所有进程”功能——它只管自己启动的，不管 fork 出来的子进程。
为什么换端口就立刻好，但一换回来又报错？
这不是运气问题，是 TIME_WAIT 状态在作祟。TCP 连接关闭后，操作系统会保留该 socket 地址一小段时间（通常 2–4 分钟），防止延迟到达的旧包被新连接误收。Uvicorn 快速重启时，如果旧连接还没出 TIME_WAIT，就会触发 Address already in use。
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
这在开发阶段高频重启时特别明显，尤其当你 Ctrl+C 中断后立刻 uvicorn main:app --reload。
临时缓解办法：
- 加
--lifespan off参数，跳过 ASGI 生命周期等待逻辑（仅限开发） - 启动前加个 sleep：比如
sleep 3 && uvicorn main:app --port 8000 - 根本解法：改用
--reload-delay 1.5，让 uvicorn 自己等一会儿再 reload
注意：SO_REUSEADDR 是底层 socket 选项，Uvicorn 默认已启用，所以这不是配置缺失问题，而是系统行为本身。
后台运行的 uvicorn 怎么彻底停掉？
用 nohup uvicorn main:app --port 8000 & 启动后，ps aux | grep uvicorn 可能只看到 shell 进程，找不到真正的 uvicorn PID。这是因为 nohup 把 stdout/stderr 重定向后，父进程变了。
正确做法是查监听端口反推：
- Linux/macOS：
lsof -t -i :8000直接输出 PID（多个就都列出来） - Windows：
netstat -ano | findstr :8000→ 提取最后一列 PID →taskkill /F /PID <pid></pid> - 一定要 kill 所有返回的 PID，Uvicorn 的 reload 模式常启多个子进程，漏一个就会复现错误
别信“我刚 kill 过了”——多跑一遍 lsof -t -i :8000，输出为空才算真正干净。
