FastAPI的Uvicorn怎么安装与配置-Python教程-PHP中文网

Uvicorn必须单独安装，推荐命令为pip install uvicorn==0.34.2[standard]；仅装fastapi不包含uvicorn，缺装或版本不匹配将导致ModuleNotFoundError或500错误。

fastapi的uvicorn怎么安装与配置

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.run() 时的三个关键参数陷阱

在 Python 脚本里调用 uvicorn.run() 启动服务，不是填完 host 和 port 就完事。以下参数漏配或乱配，会导致开发体验断崖式下降：

Uvicorn 0.52.1

Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。

下载

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')"，避免只导入模块却不支持完整功能