uvicorn，一个极速的 Python 库
大家好，我是木木。
今天给大家分享一个【极速】的 Python 库，uvicorn。
uvicorn
它是 Python 世界里最常见的 ASGI 服务器之一，适合把 FastAPI、Starlette 或原生 ASGI 应用快速跑起来；开发时够轻，线上也能通过事件循环、协议栈和多进程配置拿到很不错的吞吐表现。
项目地址：https://github.com/Kludex/uvicorn官方文档：https://uvicorn.dev
三大特点
启动快
uvicorn 的命令行极简，uvicorn module:app 就能启动服务。对原型验证、接口调试和小型服务来说，几乎没有上手成本；对团队协作而言，这也意味着更低的部署沟通成本。
协议全
它原生支持 HTTP/1.1 和 WebSocket，并围绕 ASGI 规范工作。只要你的应用遵循 ASGI 接口，就能把同步时代难做的长连接、流式响应和异步 I/O 处理得更自然。
可扩展
uvicorn 既能纯 Python 运行，也能配合 uvloop、httptools、websockets、watchfiles 等可选依赖增强性能与开发体验。开发、测试、生产三种环境都能找到合适的启动姿势。
最佳实践
安装方式
pipinstalluvicorn# 更推荐开发机直接安装标准增强包pipinstall'uvicorn[standard]'
这段代码解决什么问题：先把最基础的运行环境准备好。uvicorn[standard] 会补齐更快的事件循环、HTTP 解析器、WebSocket 实现和热重载能力，省掉你后面零碎补依赖的时间。
功能一：用最小 ASGI 应用快速起服务
这段代码解决什么问题：当你只是想验证一个 ASGI 服务是否能正常响应时，没必要先引入完整框架。直接写一个原生 ASGI callable，就能把协议链路、响应头和正文发送流程跑通。
# demo1_app.pyasyncdefapp(scope,receive,send):assertscope['type']=='http'body='你好，Uvicorn！这是最小可运行 ASGI 应用。\n'.encode('utf-8')awaitsend({'type':'http.response.start','status':200,'headers':[(b'content-type',b'text/plain; charset=utf-8')],})awaitsend({'type':'http.response.body','body':body})
这类写法特别适合排查网关、容器探针、反向代理或平台侧问题：先证明服务端口、响应链路和字符编码没有问题，再逐步接入业务框架。
功能二：开发阶段打开热重载
这段代码解决什么问题：接口开发时最烦的是改一行就手动重启一次。uvicorn 的 --reload 配合 watchfiles 可以在源码变化后自动重启，特别适合本地联调和接口迭代。
# demo2_app.pyVERSION='v1'asyncdefapp(scope,receive,send):assertscope['type']=='http'body=('{"version": "%s", "feature": "reload"}'%VERSION).encode('utf-8')awaitsend({'type':'http.response.start','status':200,'headers':[(b'content-type',b'application/json')],})awaitsend({'type':'http.response.body','body':body})
从实测结果可以看到，第一次响应还是 v1，修改文件后，WatchFiles 触发重载，再次请求已经切到 v2。这说明 uvicorn 的开发体验并不只是“能跑”，而是能把改动反馈闭环压到很短。
环境与版本信息
高级功能
用 WebSocket 跑双向消息通道
这段代码解决什么问题：如果你需要聊天、推送、终端桥接、协作编辑这类长连接场景，HTTP 请求/响应模型就不够用了。uvicorn 能直接承载 ASGI WebSocket 应用，不用额外换服务器。
# demo3_app.pyimportjsonasyncdefapp(scope,receive,send):ifscope['type']=='websocket':awaitsend({'type':'websocket.accept'})whileTrue:event=awaitreceive()ifevent['type']=='websocket.receive':text=event.get('text','')awaitsend({'type':'websocket.send','text':json.dumps({'echo':text,'length':len(text)},ensure_ascii=False)})elifevent['type']=='websocket.disconnect':return
适用场景很明确：实时协作、机器人回传、通知推送、前端订阅状态流。常见坑也很典型：一是反向代理要正确转发 Upgrade 头；二是生产环境需要根据连接数评估 worker 数量与心跳策略；三是不要把开发态的 --reload 和高并发长连接混在一起做性能判断。
适用边界与上线检查
适用
- FastAPI、Starlette、Litestar 等 ASGI 应用的默认服务器
- 需要 HTTP + WebSocket 共存的接口服务
不适用
- 主要是传统 WSGI 项目，且短期内没有迁移到 ASGI 的计划
- 强依赖复杂进程治理、prefork 管理或既有 Gunicorn 运维体系的团队
- 希望单靠开发机
--reload 的表现来判断真实生产性能的场景 - 对 HTTP/3、边缘网络能力有非常具体要求，但当前部署链路尚未配齐的项目
上线检查
- 生产环境优先用
uvicorn[standard] 或确认 uvloop、httptools 等增强依赖已安装。 - 放在 Nginx、Ingress 或云负载均衡后时，确认代理头、超时和 WebSocket Upgrade 配置都已验证。
- 根据 CPU 核数、连接数和请求耗时评估 worker 与日志策略，不要直接照搬本地开发参数。
总结
uvicorn 的价值不只是“FastAPI 默认会用它”，而是它把 ASGI 服务启动、调试、长连接支持和性能增强几件事做到了足够顺手。想把现代 Python Web 服务快速落地，它几乎总是值得优先考虑。
