Address already in use 错误主因是端口被占，需用lsof/netstat查PID后kill，或换端口绕过；ModuleNotFoundError因路径错误（缺__init__.py），AttributeError因变量名不匹配；PyCharm调试报loop_factory错是兼容问题，建议降级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
下载
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，但没同步支持 3.12 新增的loop_factory参数 - 临时解法：降级 uvicorn 到
0.29.0（不带 loop_factory 支持）：pip install uvicorn==0.29.0 - 长期建议：用普通运行模式（绿色三角）开发 + 接口测试工具（如 HTTPie）联调，只在关键逻辑处切回调试模式
- 注意：不要在生产环境用
--reload或调试器启动，这个坑只存在于开发阶段
reload 热重载不生效，改了代码没反应
终端没打印 INFO: Reloading triggered...，说明文件监听根本没捕获到变化，问题不在 FastAPI，而在 uvicorn 底层的 watchfiles。
- 先确认命令带了
--reload，且没拼错成--relaod这种低级错误 - 检查编辑器保存行为：VS Code 默认启用“延迟写入”（delayed write），可能绕过 inotify；在设置里关掉
files.useExperimentalFileWatcher - Mac 用户注意：如果项目放在 iCloud Drive 或 Dropbox 同步目录里，watchfiles 会失效——系统事件被同步服务劫持了
- Docker 场景下：宿主机改代码，容器内 uvicorn 看不到变更，必须挂载整个目录并确保
--reload-dir指向正确路径，例如--reload-dir /app - 别信“自动检测”，显式指定监听范围更稳：
uvicorn main:app --reload --reload-dir ./api --reload-dir ./core
真正难排查的往往不是报错本身，而是错误发生前的静默状态——比如端口被占却没提示、文件修改没触发监听、调试器悄悄跳过异步初始化。盯住启动第一秒的日志输出，比反复重启更有用。
