uvicorn是啥

原创已于 2025-12-12 21:35:42 修改 · 419 阅读

9 ·

CC 4.0 BY-SA版权

文章标签：

#python

于 2025-12-12 21:34:06 首次发布

【服务器开发】专栏收录该内容

2 篇文章

订阅专栏

uvicorn 是 Python 生态中专门用于运行 ASGI 应用 的高性能异步 Web 服务器，也是 FastAPI、Starlette 等现代异步 Web 框架的官方推荐服务器。下面从核心概念、作用、使用方式等维度讲清楚：

一、先搞懂：ASGI 是什么？

要理解 uvicorn，先明确它的运行标准：

Web 服务器和应用之间的通信需要遵循统一规范：
- 传统同步框架（如 Flask/Django<3.0）遵循 WSGI 规范（Web Server Gateway Interface）；
- 现代异步框架（FastAPI/Starlette/Django≥3.0）遵循 ASGI 规范（Asynchronous Server Gateway Interface）—— 支持异步、WebSocket、HTTP/2 等特性。
uvicorn 是 ASGI 服务器，专门适配遵循 ASGI 规范的应用，是连接“客户端请求”和“你的 Python 应用代码”的中间层。

二、uvicorn 核心作用

简单说：uvicorn 帮你把写好的 FastAPI/Starlette 代码“跑起来”，成为可对外提供服务的 Web 服务，核心职责包括：

监听网络端口：比如监听 localhost:8000，接收客户端（浏览器/Postman 等）的 HTTP 请求；
解析 HTTP 请求：把原始的 HTTP 报文解析成 Python 应用能识别的格式（如请求路径、参数、请求体）；
调度应用代码：将解析后的请求传递给你的 FastAPI 应用（如 app 实例），调用对应的路由函数（如 hello()）；
返回响应：把应用代码的返回值（如 {"msg": "Hello, world!"}）封装成 HTTP 响应报文，返回给客户端；
异步高性能：基于 Python 的 asyncio 实现异步 I/O，并发处理请求的能力远优于传统 WSGI 服务器（如 Gunicorn 同步模式）。

三、uvicorn 基本使用方式

1. 安装

pip install uvicorn
# 如果需要支持 HTTP/2、WebSocket 等高级特性，安装完整版：
pip install "uvicorn[standard]"

2. 核心运行命令

格式：uvicorn <模块名>:<应用实例名> [可选参数]
以你之前的 FastAPI 代码（文件名为 main.py）为例：

# 基础运行：监听 127.0.0.1:8000，代码修改后不会自动重启
uvicorn main:app

# 开发环境常用（--reload 热重载：代码修改后自动重启服务器）
uvicorn main:app --reload

# 自定义端口/主机（比如对外网开放，监听所有IP的8888端口）
uvicorn main:app --host 0.0.0.0 --port 8888 --reload

参数说明：

main:app：main 是你的 Python 文件名（模块名），app 是文件中创建的 FastAPI 实例（app = FastAPI()）；
--reload：开发模式专用，代码修改后自动重启（生产环境禁止使用，会有性能损耗）；
--host 0.0.0.0：允许外部设备访问（默认只允许本机 127.0.0.1 访问）；
--port：指定监听端口（默认 8000）。

3. 生产环境使用

uvicorn 是单进程服务器，生产环境通常搭配 Gunicorn（多进程管理器）使用：

Gunicorn 作为主进程，管理多个 uvicorn 工作进程，提升并发和稳定性；

命令示例：

# 安装 gunicorn
pip install gunicorn

# 启动 4 个 uvicorn 工作进程
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

四、uvicorn 与 FastAPI 的关系

FastAPI：是 Web 框架，负责定义路由、处理业务逻辑、校验参数、生成文档等；
uvicorn：是 Web 服务器，负责把 FastAPI 应用暴露成可访问的 Web 服务；
类比：FastAPI 是“厨师”（处理核心业务），uvicorn 是“餐厅服务员”（接收顾客请求、传递给厨师、返回菜品）。

五、关键特性

支持异步/同步应用（兼容 WSGI 应用，可运行 Flask/Django）；
原生支持 WebSocket、HTTP/2；
轻量、易配置，与 FastAPI 无缝集成；
开发模式的热重载（--reload）大幅提升开发效率。

总结：uvicorn 是运行 FastAPI 等异步 Web 应用的“必备工具”，是连接你的代码和外部请求的桥梁，核心价值是高性能地处理异步 Web 请求。