Address already in use主因是WSL2或Docker Desktop在Linux内核监听端口,Windows netstat不可见;应执行wsl --shutdown或退出Docker Desktop,或启动时加--host 127.0.0.1避免冲突。

nohup uvicorn 启动后报 Address already in use
后台启动时没显式报错,但浏览器打不开、日志卡在 startup 阶段,十有八九是端口被占——而且不是你当前终端里跑着的另一个 uvicorn,而是 WSL2 或 Docker Desktop 在 Linux 内核里监听了该端口,Windows 的 netstat 看不见它。
验证方法:
- 在 PowerShell 里执行:
wsl -d Ubuntu-22.04 -- lsof -i :8000(把Ubuntu-22.04换成你实际的 WSL 发行版名) - 或直接进 WSL 终端运行:
lsof -i :8000 - 如果看到
uvicorn或python进程,就是它
临时解法比杀进程更快:
- 执行
wsl --shutdown关掉整个 WSL2 - 或者退出 Docker Desktop(它默认启用 WSL2 后端)
- 不想关?启动时加
--host 127.0.0.1,避免跨网络栈绑定冲突
nohup uvicorn --reload 启动失败
--reload 在后台模式下根本无效,Uvicorn 会直接报错或静默忽略。因为 --reload 依赖文件系统监听和子进程管理,而 nohup 启动后父 shell 断开,inotify 事件可能丢失,子进程也容易 orphan。
正确做法:
- 开发阶段别用
--reload+nohup组合,改用uvicorn main:app --reload在前台跑 - 生产部署需要后台常驻,请用
systemd(Linux)、pm2或supervisord,它们能管理进程生命周期和重启策略 - 真要 quick hack:去掉
--reload,只留nohup uvicorn main:app --host 0.0.0.0 --port 8000 > uvicorn.log 2>&1 &
后台 uvicorn 启动后无法停止
用 nohup 启动的进程不会出现在 jobs 里,Ctrl+C 或 IDE 停止按钮完全无效。更麻烦的是,Uvicorn 可能 fork 出多个子进程,只 kill 主 PID 会残留 worker。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
可靠终止步骤:
- 查监听端口的 PID:
sudo lsof -t -i tcp:8000(Linux/macOS)或Get-NetTCPConnection -LocalPort 8000 | Select-Object OwningProcess(PowerShell) - 拿到 PID 后,用
kill -9 <pid></pid>或Stop-Process -Id <pid> -Force</pid>强制终结整个进程树 - 如果提示“访问被拒绝”,说明进程以高权限运行,换管理员权限的终端再试
别信 ps aux | grep uvicorn ——后台 uvicorn 子进程名常是 python,不带任何标识。
nohup uvicorn 日志为空或乱码
nohup 默认把 stdout/stderr 合并重定向到 nohup.out,但 Uvicorn 的日志输出受 --log-level 和格式控制,默认 INFO 级别以下不打印,且异步日志缓冲可能导致延迟写入。
确保日志可用:
- 显式指定日志输出:
nohup uvicorn main:app --log-level info --access-log --error-log uvicorn.error.log > uvicorn.access.log 2>&1 & - 加
--access-log才会记录 HTTP 请求;不加则只有错误和启动信息 - 如果用中文路径或参数,Windows 下建议在命令前加
chcp 65001切 UTF-8 编码,否则日志可能乱码
真正难搞的不是启动,是后台进程的可观测性和可控性——一旦脱离终端,所有依赖交互的操作(比如 reload、优雅关闭、实时日志 tail)都得靠外部工具补位。

















