推荐直接安装 pip install "uvicorn[standard]"，因其包含 uvloop、httptools、watchfiles、websockets 等关键依赖，支持自动重载、高性能并发与 WebSocket；裸装 pip install uvicorn 仅适用于最简 Hello World。
直接装 uvicorn[standard]，别用裸 pip install uvicorn —— 后者缺自动重载、缺 uvloop、缺 websockets，开发卡顿、生产掉链子。
安装时选 standard 依赖包
最小安装（pip install uvicorn）只够跑个 hello world；但只要涉及文件改动要自动重启、并发稍高、或用 WebSocket，就立刻报错或性能骤降。
-
pip install "uvicorn[standard]"是开发和轻量生产唯一推荐方式 - 它会顺带装上：
uvloop（Linux/macOS 下更快的事件循环）、httptools（高性能 HTTP 解析）、watchfiles（比旧版watchdog更稳的文件监听）、websockets（WebSocket 必需） - 验证是否装全：
python -c "import uvloop, watchfiles, websockets, httptools"—— 不报错才算到位
启动命令里 app 路径写错是最高频失败原因
uvicorn main:app 看似简单，但冒号前不是文件路径，而是 Python 模块导入路径；冒号后必须严格匹配变量名。
Uvicorn 0.52.1
下载
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
- 如果项目结构是
src/api/main.py且目录里没有__init__.py，就得写成uvicorn src.api.main:app（前提是src在PYTHONPATH或当前工作目录下） - 如果没
__init__.py又不想改结构，用--app-dir src显式指定根目录：uvicorn api.main:app --app-dir src - 常见报错
ModuleNotFoundError: No module named 'main'：检查当前终端是否在main.py所在目录运行；AttributeError: module 'main' has no attribute 'app'：确认代码里真叫app = FastAPI()，不是application或api
开发用 --reload，但别在生产环境开
--reload 依赖 watchfiles 监听文件变化，它在容器、NFS、某些 IDE 的临时文件写入场景下会反复触发重启，甚至卡死进程。
- 开发阶段加：
uvicorn main:app --reload --host 0.0.0.0 --port 8000 - 一旦部署到服务器或容器，必须去掉
--reload；若需热更新能力，改用gunicorn+uvicorn.workers.UvicornWorker组合 - 注意：
--reload和--workers > 1互斥 —— 开了 reload 就只能单进程，否则多进程会抢 reload 触发权，行为不可控
PyCharm 里配错了 interpreter 就白忙活
很多人在 PyCharm 里点运行按钮没反应，或者报 uvicorn not found，90% 是因为没选对解释器，而不是没装 uvicorn。
- 进
Run → Edit Configurations… → Python → Module name填uvicorn，不是你的main.py -
Parameters填main:app --reload --host 0.0.0.0 --port 8000，不要漏空格 -
Python interpreter必须选中项目虚拟环境（不是系统 Python，也不是 base conda），且该环境里已执行过pip install "uvicorn[standard]" - Working directory 设为项目根目录（即
main.py所在目录），否则模块导入失败
真正容易被忽略的是：Uvicorn 的配置优先级是「命令行参数 > 编程式参数 > 环境变量」，而很多人在 Docker 里同时设了 UVICORN_RELOAD=true 又写了 --reload，结果 reload 行为被覆盖却不自知。调参前先确认哪一层在起作用。
