Uvicorn 入门详解

前言

在 Python Web 领域,异步服务器网关接口(ASGI) 已成为现代 Web 框架(如 FastAPI、Starlette、Sanic 等)的主流标准。作为 ASGI 生态的明星服务器,Uvicorn 以其高性能、易用性和极简风格,成为 FastAPI 官方推荐的生产级部署方式。

本文将带你快速了解 Uvicorn 的工作原理、常用用法、开发热重载、日志管理和部署技巧,并总结开发者常见的踩坑经验。

  1. Uvicorn 是什么?
    Uvicorn 是一个基于 uvloop 和 httptools 实现的超快 ASGI 服务器。
    它能托管所有兼容 ASGI 的 Python Web 框架,实现真正的异步非阻塞网络通信,大幅提升性能。

你可以把 Uvicorn 理解为 WSGI 时代的 gunicorn,但为异步而生!

  1. Uvicorn 安装
    pip install uvicorn

建议用 FastAPI 时一并装

pip install fastapi[all]

  1. 最简单的用法

假设你有一个 FastAPI 应用 app/main.py:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")

def hello():

return {"msg": "Hello Uvicorn"}

启动命令:

uvicorn app.main:app --reload

app.main:app 表示 "app" 文件夹下 "main.py" 文件中的 "app" 对象。

--reload 代表热重载,开发调试专用。

  1. 常用启动参数详解
    --host 指定服务监听地址(默认127.0.0.1)

--port 端口号(默认8000)

--reload 代码变更自动重启,开发环境专用

--log-level info 显示 info 及以上级别日志

--workers N 多进程并发,适合 CPU 密集型场景(一般推荐部署时用 gunicorn 搭配 uvicorn workers)

--proxy-headers 用于处理 Nginx 代理后的真实 IP

例如:

uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload --log-level info

  1. 热重载原理与注意事项

--reload 会启动一个监视器,检测项目文件变化,自动重启服务。

只建议开发环境用。生产环境用会降低性能且存在安全风险。

常见坑:在 Docker 容器用 --reload 时要保证本地代码映射进容器,否则热重载无效。

  1. 日志输出最佳实践
    用 Python 标准库 logging,并用 uvicorn 作为 logger 名称:

import logging

logger = logging.getLogger("uvicorn")

logger.info("Hello Uvicorn Logger")

启动时用 --log-level info,否则 info 级别日志不会显示。

不建议直接用 print,在 uvicorn 部分场景(如生产、容器)下 print 可能不会显示。

  1. 生产部署建议
    不要用 --reload!

推荐用 gunicorn + uvicorn worker 管理多进程:

pip install gunicorn

gunicorn app.main:app -k uvicorn.workers.UvicornWorker -w 4 -b 0.0.0.0:8080

-k uvicorn.workers.UvicornWorker 让 gunicorn 采用 Uvicorn 作为异步 worker。

配合 Nginx 做反向代理,更安全、灵活。

  1. 常见问题与踩坑总结
    print 打印不出日志?
    用 logging,并加 --log-level info。

代码保存后没热部署?

没加 --reload 参数。

参数没传全报错?

传 None 或者用参数默认值。

Docker 下热部署没反应?

挂载本地代码目录到容器(-v $(pwd):/app),否则容器里的代码不会变。

  1. 小结
    Uvicorn 是 Python 异步 Web 服务的基础设施,搭配 FastAPI 能快速开发高性能接口。
    开发用 --reload,日志用 logging,生产用 gunicorn + uvicorn worker!
相关推荐
蓝婷儿37 分钟前
Python 机器学习核心入门与实战进阶 Day 1 - 分类 vs 回归
python·机器学习·分类
Devil枫2 小时前
Kotlin扩展函数与属性
开发语言·python·kotlin
程序员阿超的博客3 小时前
Python 数据分析与机器学习入门 (八):用 Scikit-Learn 跑通第一个机器学习模型
python·机器学习·数据分析·scikit-learn·入门教程·python教程
xingshanchang4 小时前
PyTorch 不支持旧GPU的异常状态与解决方案:CUDNN_STATUS_NOT_SUPPORTED_ARCH_MISMATCH
人工智能·pytorch·python
费弗里7 小时前
Python全栈应用开发利器Dash 3.x新版本介绍(1)
python·dash
李少兄9 天前
解决OSS存储桶未创建导致的XML错误
xml·开发语言·python
就叫飞六吧9 天前
基于keepalived、vip实现高可用nginx (centos)
python·nginx·centos
Vertira9 天前
PyTorch中的permute, transpose, view, reshape和flatten函数详解(已解决)
人工智能·pytorch·python
学Linux的语莫9 天前
python基础语法
开发语言·python
匿名的魔术师9 天前
实验问题记录:PyTorch Tensor 也会出现 a = b 赋值后,修改 a 会影响 b 的情况
人工智能·pytorch·python