hypercorn,一个优雅的 Python ASGI/WSGI 服务器

大家好，我是木木。

今天给大家分享一个【优雅】的 Python 库，hypercorn。

hypercorn 是一个基于 Hyper 系列库（sans-io hyper、h11、h2、wsproto）构建的高性能 ASGI/WSGI 服务器，灵感来源于 Gunicorn。它同时支持 HTTP/1、HTTP/2、WebSocket（over HTTP/1 & HTTP/2），并可借助 uvloop 或 trio 实现异步加速。2026 年的 Python Web 服务选型中，它是一个值得关注的新选择。

项目地址：https://github.com/pgjones/hypercorn官方文档：https://hypercorn.readthedocs.io

三大特点

多协议支持

hypercorn 同时支持 ASGI 和 WSGI 两大应用规范，并原生支持 HTTP/1、HTTP/2 以及 WebSocket。对 HTTP/3 的草稿支持也可通过 pip install hypercorn[h3] 开启，用 --quic-bind 即可监听 QUIC 端口。

异步 worker 类型

支持 asyncio（默认）、uvloop 和 trio 三种异步 worker 类型。只需在命令行加 --worker-class 参数即可切换，无需修改应用代码。对于已有 trio 生态的项目（如某些科学计算框架），直接可用。

命令行友好

hypercorn module:app 一行命令即可启动服务，支持热重载（--reload）、绑定地址配置（-b）、多进程 workers（-w）等常用参数，无需编写配置文件即可投入生产。

最佳实践

环境与版本信息

• Python：≥ 3.8
• 关键依赖：h11、h2、wsproto、hyper（sans-io 版）
• 可选依赖：uvloop、trio、aioquic（HTTP/3）

安装方式

pipinstallhypercorn# 可选安装 uvloop 加速pipinstallhypercorn[uvloop]# 可选安装 trio workerpipinstallhypercorn[trio]# 可选安装 HTTP/3 支持pipinstallhypercorn[h3]

功能一：快速启动 ASGI 应用

下面这段代码演示了用 hypercorn 启动一个 FastAPI 应用。hypercorn 会自动处理 ASGI 协议，启动 HTTP/1 和 HTTP/2 支持。

# main.pyfromfastapiimportFastAPIapp=FastAPI()@app.get("/")defread_root():return{"message":"Hello from Hypercorn!"}@app.get("/items/{item_id}")defread_item(item_id:int):return{"item_id":item_id,"message":f"Item {item_id} details"}

# 启动服务（默认 asyncio worker）hypercornmain:app--bind0.0.0.0:8000# 使用 uvloop 加速hypercornmain:app--bind0.0.0.0:8000--worker-classuvloop# 多 worker 模式hypercornmain:app--bind0.0.0.0:8000-w4

功能二：程序化配置与启动

hypercorn 支持通过 Python 代码精细控制配置，适合嵌入到更大的系统中：

# serve_app.pyimportasynciofromhypercorn.configimportConfigfromhypercorn.asyncioimportservefromfastapiimportFastAPIapp=FastAPI()@app.get("/")defread_root():return{"server":"Hypercorn","protocols":["http/1","http/2"]}@app.get("/info")defget_info():return{"worker":"asyncio","features":["websocket","http2","asgi3"],"status":"running"}asyncdefmain():config=Config()config.bind=["0.0.0.0:8000"]config.worker_class="asyncio"config.accesslog="-"# 输出到 stdoutconfig.errorlog="-"awaitserve(app,config)if__name__=="__main__":asyncio.run(main())

pythonserve_app.py

高级功能

使用 trio worker 运行 ASGI 应用

对于已经使用 trio 生态的项目（如某些异步科学计算任务），hypercorn 的 trio worker 可以让 Web 层和业务层共享同一个事件循环：

# trio_app.pyimporttriofromhypercorn.configimportConfigfromhypercorn.trioimportservefromstarlette.applicationsimportStarlettefromstarlette.routingimportRouteasyncdefhomepage(request):returnResponse("Running on trio worker!",media_type="text/plain")asyncdefstats(request):returnResponse("Trio nursery active — async world shared with web layer",media_type="text/plain")routes=[Route("/",homepage),Route("/stats",stats),]app=Starlette(routes=routes)asyncdefmain():config=Config()config.bind=["0.0.0.0:8000"]config.worker_class="trio"awaitserve(app,config)if__name__=="__main__":trio.run(main)

pipinstallhypercorn[trio]starlettepythontrio_app.py

适用场景：trio 生态的项目、需要与 Web 请求共享同一 async 上下文的场景。

常见坑：trio worker 下同一个进程内不支持多 worker 数量调整（-w 参数会被忽略）；确保所有第三方库在 trio 环境中兼容。

适用边界与上线检查

适用

• 需要同时支持 ASGI 和 WSGI 应用的部署场景
• 项目中使用 trio 作为异步框架
• 需要 HTTP/2 或 WebSocket 支持，而 uvicorn 升级遇阻时
• 实验性 HTTP/3 需求（通过 aioquic）

不适用

• 依赖特定 ASGI 框架的独有特性（如 Starlette 的某些中间件在 hypercorn 下行为略有差异）
• 追求最广泛生产验证的严肃生产环境（uvicorn/gunicorn 社区更大、踩坑报告更多）
• Windows 环境（部分 worker 类型不支持）

上线检查

1. 确认 worker-class 与应用异步生态匹配（asyncio/uvloop/trio）
2. 生产环境建议多 worker（-w 4 或更高）并配合 reverse proxy（Nginx）
3. HTTP/2 需要 HTTPS；在本地测试时可用 --certfile / --keyfile 指定证书

总结

hypercorn 以 Hyper 系列库为核心，为 Python ASGI/WSGI 应用提供了一个多协议、高性能、配置灵活的服务器选择。对 trio 和 uvloop 的原生支持，以及 HTTP/3 的实验性支持，使其在现代 Python Web 生态中具有独特的定位。适合追求协议前沿支持和异步多样性的开发者。