Uvicorn 是 ASGI 协议的严格实现,仅负责解析TCP流与事件翻译,不处理路由等业务逻辑;它要求应用必须正确实现 scope/receive/send 三参数异步调用、支持 http/websocket/lifespan 多类型事件,并对字节级格式零容忍。

Uvicorn 是 ASGI 协议的一个具体实现,不是协议本身,也不能脱离 ASGI 运行。 它不兼容 WSGI 应用,传进去一个 Flask 的 app 会直接报 TypeError: 'function' object is not async;反过来,一个符合 ASGI 规范的 async def app(scope, receive, send),哪怕不用 FastAPI,Uvicorn 也能原生跑起来。
ASGI 是接口契约,Uvicorn 是执行者
ASGI 定义了三件事:应用必须是异步可调用对象、必须接收 scope/receive/send 三个参数、必须按约定格式收发事件(比如 {"type": "http.response.start"})。Uvicorn 不做解释、不改规则,只负责把 TCP 字节流解析成这些事件,再把应用发回来的事件序列重新编码发给客户端。它不处理路由、不渲染模板、不连接数据库——它只翻译。
常见错误现象:
- 启动后请求返回空响应或卡住 → 很可能
send被漏调,或await send(...)写成了send(...)(协程未 await) - WebSocket 连接建立后立刻断开 →
scope["type"]是"websocket",但应用没处理websocket.connect或没调websocket.accept - HTTP/2 请求失败 → Uvicorn 默认不启用 HTTP/2,必须显式加
--http http2且服务端需配 TLS(--ssl-keyfile+--ssl-certfile)
Uvicorn 如何验证一个应用是否真 ASGI-compliant
它在启动时不做静态检查,而是在第一次请求进来时,把 scope 传给你的应用,然后等 receive() 和 send() 调用。如果应用抛出异常、没 await、或返回非预期 type(比如把 http.response.body 写成 http.response.chunk),Uvicorn 就会在日志里打 warning,甚至静默丢弃响应。
实操建议:
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
- 本地调试时加
--log-level debug,能看见每条receive和send的原始事件 - 不要依赖框架“自动包装”——比如用
asgiref.WsgiToAsgi包 Flask,虽能启动,但所有 IO 都退化为同步阻塞,Uvicorn 的并发优势归零 - 检查
scope["asgi"]["version"]:值为"3.0"时,receive可能返回{"type": "http.disconnect"},忽略它会导致连接泄漏
为什么不能只写 async def app() 就算 ASGI
ASGI 要求应用能处理多种 scope["type"]:不仅是 "http",还有 "websocket"、"lifespan"。Uvicorn 启动时会先发一个 lifespan.startup 事件,如果你的应用没监听这个类型,就会卡在启动阶段,日志里反复出现 lifespan.startup.timeout。
关键点:
-
lifespan事件只触发一次,且必须由应用主动响应lifespan.startup.complete,Uvicorn 才继续接受 HTTP 请求 - FastAPI 自动处理 lifespan;纯手写 ASGI 应用必须自己循环
await receive()并分支判断event["type"] - 用
--lifespan off可跳过 lifespan,但意味着你无法在启动时初始化数据库连接池等全局资源
最易被忽略的是:Uvicorn 对 ASGI 的执行是严格按规范字节级校验的。它不宽容、不猜测、不 fallback——传错一个 header 键名(比如用字符串 "content-type" 而非字节 b"content-type"),响应就可能被截断。这不是 bug,是协议强制要求。










