Uvicorn启动失败常见原因及解决方案：1.端口占用（Errno 98），用lsof/netstat查PID并kill，注意WSL2或IDE残留进程；2.路径错误导致ModuleNotFoundError或AttributeError，需检查__init__.py、变量名和工作目录；3.环境问题如未激活虚拟环境、pip与python环境不匹配等。
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 写错了，而是加载路径或变量名对不上。
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 传了它不认的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 进程树残留——这些底层细节最容易被忽略，但恰恰是重启几次都失败的真正原因。
