Uvicorn启动失败常见原因及解决方案:1.端口占用(Errno 98)——用lsof/netstat查PID并kill,或换端口;2.路径/变量名错误——检查__init__.py、app变量名及工作目录;3.PyCharm调试兼容问题——降级uvicorn或改用普通运行模式。

Uvicorn 启动失败,八成不是代码问题,而是环境、路径或配置链路上某个环节断了。直接看日志里最靠前的那条错误,它通常就指向真正的根因。
Address already in use 怎么快速定位和释放端口
这是开发时最常撞上的墙,表现就是命令卡住、没日志、浏览器打不开。错误信息里明确写着 OSError: [Errno 98] Address already in use,但你未必知道是谁占的。
- 先确认端口:默认是
8000,但如果你改过--port,就得查对应的数字 - Linux/macOS 执行:
lsof -i :8000或netstat -tulpn | grep :8000,看输出里的PID - Windows 用:
netstat -aon | findstr :8000,再用tasklist | findstr "PID"查进程名 - 别急着
kill -9:有些 IDE(比如 PyCharm)启动 uvicorn 会起多个子进程,只杀主 PID 可能残留;更稳妥的是直接关掉 IDE 再试 - 懒人方案:加个
--port 8001绕过去,但别养成习惯——端口混乱会拖慢协作和部署
ModuleNotFoundError 或 AttributeError: no attribute 'app'
这类错误说明 uvicorn 根本没找到你的应用对象,不是 FastAPI 写错了,而是加载路径或变量名对不上。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
-
ModuleNotFoundError:检查目录下有没有__init__.py。没有的话,不能写api.main:app,得写成api/main:app(文件路径格式) -
AttributeError: no attribute 'app':打开你的main.py,确认app = FastAPI()这行变量名真是app,不是application、fastapi_app或缩写成a - 工作目录错位:PyCharm 运行配置里
Working directory必须设成main.py所在目录,否则uvicorn main:app会找不到文件 - 虚拟环境没激活或依赖没装:运行
pip list | grep uvicorn和pip list | grep fastapi,双保险
PyCharm 调试模式下报 loop_factory 参数错误
这个错误只在 PyCharm 点虫子图标调试时出现,普通运行完全正常,本质是调试器补丁和 Python 3.12+ uvicorn 的 asyncio 兼容问题。
- 错误典型长这样:
TypeError: _patch_asyncio.<locals>.run() got an unexpected keyword argument 'loop_factory'</locals> - 根本原因:PyCharm 的
pydevd补丁版asyncio.run不支持loop_factory参数,而 uvicorn 0.30.0+ 默认传了它 - 临时解法:降级 uvicorn 到
0.29.0(pip install "uvicorn) - 更推荐做法:PyCharm 中改用普通运行模式(绿色三角形),调试时用
print/logging+ 断点混合策略
502/504 错误不是 uvicorn 报的,但它可能被牵连
Uvicorn 自身不生成 502 或 504,这些是上游(Nginx、K8s Ingress、Cloud Load Balancer)返回的状态码。但它们暴露的是 uvicorn 服务层的真实健康状态。
-
upstream prematurely closed connection(Nginx 日志)说明 uvicorn worker 主动断开了连接,常见于:单 worker 配置下请求处理超时、on_startup卡死、或def同步函数阻塞线程池导致后续请求排队溢出 - 若容器未重启但出现 502,重点查
uvicorn --workers > 1场景:某个 worker 崩溃后未被主进程及时拉起,Nginx 仍把流量打过去 - 验证方法:用
curl -v http://localhost:8000/health直连 uvicorn,绕过所有中间件;如果直连也失败,问题就在 uvicorn 层本身
真正难排查的从来不是报错信息本身,而是错误发生前那一秒——比如 on_startup 里一个没加 timeout 的数据库连接、一个没设 max_connections 的 Redis 客户端、或者一个在 def 函数里悄悄缓存了 torch 模型却没清 CUDA cache 的操作。这些不会立刻炸,但会让 uvicorn 在某个高并发时刻突然“失语”。

















