Address already in use 错误主因是端口被占，应先用 lsof -i :8000（Linux/macOS）或 netstat -aon | findstr :8000（Windows）查 PID，再 kill 或关 IDE；也可临时换端口如 --port 8001。
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 写错了，而是加载路径或变量名对不上。
Uvicorn 0.52.1
下载
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()做了 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)" 看解释器找得到什么。
