Uvicorn启动报错怎么解决-Python教程-PHP中文网

Uvicorn启动失败常见原因及解决方案：1.端口占用（Errno 98），用lsof/netstat查PID并kill，注意WSL2或IDE残留进程；2.路径错误导致ModuleNotFoundError或AttributeError，需检查__init__.py、变量名和工作目录；3.环境问题如未激活虚拟环境、pip与python环境不匹配等。

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" 查进程名
端口被占但 netstat 查不到？大概率是 WSL2 或 Docker Desktop 在 Linux 内核里监听，需进 WSL 执行 lsof -i :8000，或用 PowerShell 运行 Get-NetTCPConnection -LocalPort 8000
IDE 调试中断后残留进程很常见：PyCharm 点红色停止按钮 ≠ 进程真正退出，--reload 模式下子进程可能还在跑，建议按 PID 杀，而不是按名字

ModuleNotFoundError 或 AttributeError: no attribute 'app'

这类错误说明 uvicorn 根本没找到你的应用对象，不是 FastAPI 写错了，而是加载路径或变量名对不上。

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 兼容问题。

Uvicorn 0.52.1

Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。

下载

错误典型长这样：TypeError: _patch_asyncio..run() got an unexpected keyword argument 'loop_factory'
根本原因：PyCharm 调试器（pydevd）对 asyncio.run() 做了 patch，但新版 uvicorn 传了它不认的 loop_factory 参数
临时绕过：uvicorn.run("main:app", reload=True) 通常能跑通，因为 reload=True 会 fork 子进程，避开主进程的 patch 冲突
彻底解决：在 PyCharm 中按两下 Shift → 输入 Registry → 找到并关闭 python.debug.asyncio.repl
别用降级 uvicorn 来凑合——0.52.1 是当前稳定版，兼容性已足够好，问题不在它身上

pip install 后仍报 No module named 'uvicorn'

这说明解释器在当前运行环境的 sys.path 中没找到 uvicorn 模块，安装“成功”只是假象。

检查 Python 版本是否匹配：uvicorn 0.52.1 支持 Python 3.8~3.13；Python 3.7 装这个版本就会静默失败
确认 pip 和 python 是同一环境：which python 和 which pip（macOS/Linux），或 where python 和 where pip（Windows）
虚拟环境必须激活后再 pip install uvicorn；未激活时，模块可能装到了全局环境，而 IDE 默认用的是虚拟环境解释器
缓存损坏常见于多次中断安装后，可加 --force-reinstall --no-deps 重装，再手动补依赖：pip install click h11 typing-extensions

TIME_WAIT 状态、WSL2 端口映射、IDE 进程树残留——这些底层细节最容易被忽略，但恰恰是重启几次都失败的真正原因。