FastAPI的Uvicorn报错怎么排查-Python教程-PHP中文网

Address already in use 错误主因是端口被占，应先用 lsof -i :8000（Linux/macOS）或 netstat -aon | findstr :8000（Windows）查 PID，再 kill 或关 IDE；也可临时换端口如 --port 8001。

fastapi的uvicorn报错怎么排查

Uvicorn 启动失败，八成不是 FastAPI 代码写错了，而是环境、路径或配置链路上某个环节断了。直接看日志里最靠前的那条错误，它通常就指向真正的根因。

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 写错了，而是加载路径或变量名对不上。

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（≥0.36.0）传了 loop_factory 参数，而 patch 版本不认
临时解法：降级 uvicorn 到 0.35.0（pip install uvicorn==0.35.0）
更推荐做法：在 PyCharm 里把运行方式从「Debug」切回「Run」，调试逻辑用 print / logging + 断点混合代替

You must pass the application as an import string

这个警告不是报错，但意味着 --reload 或 --workers 功能实际没生效。

常见于用 uvicorn.run(app, ...) 的方式启动，而不是命令行 uvicorn main:app --reload
根本原因：Uvicorn 在子进程中需要重新导入模块，所以必须用字符串路径（如 "main:app"），不能传已实例化的对象
修复方式：把 uvicorn.run(app, host="0.0.0.0", port=8000, reload=True) 改成 uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)
注意引号：字符串里的 main 是模块名（对应 main.py），不是文件路径；如果 main.py 不在当前目录，还得确保该目录在 sys.path 里

最容易被忽略的是工作目录和模块路径的耦合关系——哪怕所有代码都对，只要终端 cd 错了位置，或者 PyCharm 的 Working directory 设错，Uvicorn 就会静默失败。每次怀疑是代码问题前，先 pwd / ls 确认当前在哪、python -c "import sys; print(sys.path)" 看解释器找得到什么。