uvicorn 详细介绍

一句话概括

uvicorn 是 Python 的 ASGI 异步 Web 服务器 ，专门用来运行 FastAPI、Starlette、Quart 这类异步 Web 框架；相当于异步版的 gunicorn，底层用 C 实现的 uvloop 和 httptools，性能很高PyPI。

ASGI：异步服务器网关接口，是 WSGI（同步）的下一代标准，原生支持 async/await、WebSocket、HTTP/2、长连接。 WSGI 只能处理一次性 HTTP 请求，不支持 WebSocket。

一、核心底层依赖

1. uvloop：高性能事件循环，基于 libuv（Node.js 底层），替换 Python 默认 asyncio 循环，大幅提升 IO 并发
2. httptools：C 语言编写的 HTTP 解析器，解析请求速度远快于纯 Python 实现

安装完整版：pip install "uvicorn[standard]"，会自动带上 uvloop+httptools； 极简安装：pip install uvicorn，只装纯 Python 版本，性能弱一点

二、核心能力

✅ 支持协议：HTTP/1.1、HTTP/2、WebSocket（长连接、实时推送、聊天服务） ✅ 原生异步协程，I/O 密集场景（数据库、调用第三方接口）并发能力极强 ✅ 开发自动重载（--reload），改代码自动重启 ✅ 支持 HTTPS、Unix 域套接字、代理头解析（Nginx 反向代理拿真实客户端 IP） ✅ 支持命令行启动，也支持代码内用 uvicorn.run() 编程启动 ✅ 可以独立运行，也可以作为 gunicorn 的 worker 进程（生产常用）

⚠️ 短板：单 worker 是单事件循环，同一个 worker 内 CPU 密集任务会阻塞整个事件循环，适合 IO 密集 API，不适合大量计算型接口

三、基础使用示例

1. 最简单的 ASGI 应用 main.py

# main.py
from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
from starlette.routing import Route

async def homepage(request):
    return PlainTextResponse("Hello Uvicorn")

app = Starlette(routes=[Route("/", homepage)])

2. 命令行启动

# 开发模式：代码修改自动重启，监听本地127.0.0.1:8000
uvicorn main:app --reload

# 对外暴露服务，监听所有网卡，端口8000
uvicorn main:app --host 0.0.0.0 --port 8000

main:app 含义：main = main.py 模块；app = 模块里的 ASGI 实例变量名

3. 在 Python 代码内部启动

import uvicorn

if __name__ == "__main__":
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

四、高频参数清单

表格

参数	说明
--host	监听地址，0.0.0.0= 允许外部访问；默认127.0.0.1仅本机访问
--port	端口，默认 8000
--reload	开发专用 ，代码变更自动重启；生产禁止开启；不能和 --workers 一起用
--workers N	多进程，N = 进程数；一般推荐 CPU核心数 * 2 +1
--loop uvloop	强制使用 uvloop 事件循环（性能更高）
--log-level	日志级别：debug /info/warning /error
--ssl-certfile / --ssl-keyfile	HTTPS 证书和私钥，开启 https
--proxy-headers	开启代理头，Nginx 反向代理时获取真实客户端 IP

五、部署模式（重点区分开发 / 生产）

① 开发环境：直接 uvicorn

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

优点：简单，改代码自动重启；缺点：性能弱，不适合正式线上。

② 生产推荐方案：gunicorn + uvicorn worker（最主流，FastAPI 官方推荐）

gunicorn 做进程管理器（master 主进程），负责监控、拉起、重启多个 worker；每个 worker 是一个 uvicorn 实例，处理异步请求。

gunicorn main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000

• master 进程：不处理 http，只管理 worker，worker 崩溃自动重启
• worker：uvicorn，处理异步请求、websocket
• 前面一般再加一层 Nginx 反向代理，处理静态资源、ssl、限流、负载均衡

架构：客户端 → Nginx → Gunicorn(master) → UvicornWorker(ASGI)

③ 直接用 uvicorn 多进程（简单生产，不推荐高并发）

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

uvicorn 自带简易主进程管理，但是进程管理能力不如 gunicorn 健壮。

六、uvicorn vs Gunicorn 对比

表格

项目	uvicorn	gunicorn
接口标准	ASGI（异步）	默认 WSGI（同步），可加载 uvicorn worker 支持 ASGI
适用框架	FastAPI、Starlette、Quart	Flask、Django（同步）
并发模型	单进程内协程异步；支持多进程	多进程预分叉模型
WebSocket	✅原生支持	❌原生不支持，要 uvicorn worker
定位	ASGI 请求处理器	成熟的进程管理器

七、适用场景

✅ 适合：

• FastAPI 异步 API 服务
• WebSocket 实时通信（聊天、消息推送、实时监控）
• 高并发 IO 接口（大量数据库 / HTTP 调用）
• 流式响应 SSE

❌ 不适合：

• 纯 CPU 密集型计算接口（单 worker 会阻塞事件循环）
• 大量老旧同步代码、阻塞型数据库驱动（会卡住协程）

八、同类 ASGI 服务器

• uvicorn：最流行，FastAPI 默认
• Hypercorn：支持 HTTP/3，功能更全
• Daphne：Django Channels 官方 ASGI 服务器

九、常见踩坑点

1. --reload不能上生产：会额外开监控进程，安全和性能差
2. --reload 和 --workers 不能同时使用
3. 单 uvicorn worker 遇到同步阻塞代码（time.sleep、同步 mysql 驱动）会卡死整个服务，要用 async 版本驱动
4. Nginx 反向代理时，必须加 --proxy-headers，否则拿到的 IP 是 127.0.0.1

如果你需要，我可以给你：

• uvicorn + gunicorn + Nginx 完整部署配置文件
• 或者 生产环境 systemd 托管 uvicorn/gunicorn 的 service 脚本。

---

---

---