Uvicorn必须单独安装，推荐命令为pip install uvicorn==0.34.2[standard]；仅装fastapi不包含uvicorn，缺装或版本不匹配将导致ModuleNotFoundError或500错误。
Uvicorn 必须单独安装，不能只靠 pip install fastapi 带进来；不装或装错版本，uvicorn.run() 会直接报 ModuleNotFoundError 或启动后 500 错误。
用 pip 安装 uvicorn 的正确命令组合
FastAPI 和 Uvicorn 是两个独立包，官方推荐分开控制版本。常见错误是只装 fastapi 就以为万事大吉：
-
pip install fastapi—— 不带任何 ASGI 服务器，uvicorn模块根本不存在 -
pip install fastapi uvicorn—— 能跑，但缺可选依赖（如httptools、uvloop），性能打七折 -
pip install "fastapi[standard]"—— 这个命令其实只装 FastAPI 及其自身依赖，不包含 uvicorn
真正推荐的安装方式是：
pip install fastapi==0.115.12 pip install uvicorn==0.34.2[standard]
其中 [standard] 启用二进制加速模块，==0.34.2 是当前（2026年11月）与 FastAPI 0.115.x 兼容最稳的版本。跳过版本号容易触发 starlette 接口变更导致的 TypeError: __init__() missing 1 required positional argument: 'app'。
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
配置 uvicorn.run() 时的三个关键参数陷阱
在 Python 脚本里调用 uvicorn.run() 启动服务，不是填完 host 和 port 就完事。以下参数漏配或乱配，会导致开发体验断崖式下降：
-
reload=True必须配合app实例变量名和文件名严格匹配，比如文件叫main.py，app = FastAPI()，就得写uvicorn.run("main:app", ...)；写成"main.py:app"或"main:App"都会报ImportError: cannot import name 'app' -
debug=True仅限本地开发，生产环境必须删掉——它会暴露完整 traceback，且和reload冲突，在某些 Linux 发行版上引发OSError: [Errno 24] Too many open files -
workers=1是默认值，但如果你加了--workers 4却没装uvloop或httptools，Uvicorn 会静默降级回单进程，日志里连 warning 都不打
用 uv 命令行工具替代 pip 安装后的启动流程
如果你用 uv（Astral 开发的超快 Python 工具链）管理项目，安装和启动方式完全不同，也更容易出错：
-
uv add fastapi uvicorn[standard]—— 这条命令实际装的是uvicorn[standard]，不是uvicorn；少写[standard]，后续uv run uvicorn main:app --reload会卡住不动，因为缺watchfiles -
uv run uvicorn main:app --reload中的main是模块名，不是文件路径，不能写./main.py，否则报ImportError: attempted relative import with no known parent package -
uv run默认使用项目根目录下的.venv，如果手动激活了其他虚拟环境，uv run仍会切回自己的环境，容易造成依赖版本错乱却查不到原因
离线环境部署时 uvicorn 的依赖打包要点
内网服务器没外网时，pip install uvicorn 会直接失败。这时候不能只打包 uvicorn 本身：
- 必须用
pip download uvicorn[standard] --no-deps -d ./wheels先下载主包，再补全所有依赖：pip download --no-cache-dir --find-links ./wheels --prefer-binary --trusted-host pypi.org -r requirements.txt -d ./wheels -
uvicorn[standard]实际依赖httptools、uvloop、click、h11、websockets等至少 7 个子包，漏一个就可能在启动时抛AttributeError: module 'uvicorn' has no attribute 'Config' - 打包后在目标机运行前，先验证
python -c "import uvicorn; print(uvicorn.__version__)"，再验证python -c "from uvicorn.config import Config; print('ok')"，避免只导入模块却不支持完整功能
最容易被忽略的是：Uvicorn 的 [standard] 编译依赖在离线机上没有 gcc 或 musl 工具链时，pip install 会自动退回到纯 Python 实现，吞吐量下降 40% 以上，但没有任何提示。
