Hypercorn配置：PythonHTTP/2实战指南

本文深入解析了在 Hypercorn 中正确启用 HTTP/2 的关键要点与常见陷阱：HTTP/2 在 Hypercorn 中并非默认开启，必须同时满足两个硬性条件——显式传入 `--http2` 参数并配置有效的 TLS 证书（通过 `--certfile` 和 `--keyfile`），缺一不可；纯 HTTP 请求无论是否加参数都会强制降级为 HTTP/1.1，而证书链不完整、OpenSSL 版本过低或 ALPN 协商失败等底层问题更会悄无声息地导致降级，且无明确报错；文章还强调了验证方法的严谨性——必须使用支持 HTTP/2 的工具（如新版 curl、httpx 或浏览器 Network 面板）进行测试，避免误用 requests 等不兼容工具，并提醒开发者注意中间件对 HTTP/2 流语义的潜在破坏。掌握这些细节，才能真正释放 HTTP/2 的性能优势，而非徒有配置之形。

Hypercorn 默认不启用 HTTP/2，必须显式配置 TLS

Hypercorn 支持 HTTP/2，但只在启用 TLS（即 HTTPS）时才协商 HTTP/2 —— 这是 HTTP/2 协议本身的强制要求，不是 Hypercorn 的限制。纯 http:// 请求永远走 HTTP/1.1，哪怕你写了 --http2 参数也没用。

常见错误现象：curl -v http://localhost:8000 显示 HTTP/1.1 200，即使启动命令里加了 --http2；或者浏览器地址栏没出现「h2」标识。

• 必须提供有效的 TLS 证书和私钥：用 --certfile 和 --keyfile 指向 PEM 格式文件
• --http2 参数必须显式传入，不能省略（即使 Hypercorn 版本 ≥ 0.14）
• 开发时可用自签名证书，但需用 curl --insecure 或浏览器手动信任，否则连接直接失败
• 证书链不完整（比如缺少中间 CA）会导致 ALPN 协商失败，降级到 HTTP/1.1，且无明确报错

启动命令里漏掉 --http2 就等于没开

Hypercorn 不会默认开启 HTTP/2，哪怕你配了 TLS 也不行。它把 HTTP/2 当作一个可选特性，需要主动声明。

正确写法：hypercorn --certfile cert.pem --keyfile key.pem --http2 app:app

错误写法：hypercorn --certfile cert.pem --keyfile key.pem app:app（看起来能跑，但实际还是 HTTP/1.1）

• 检查是否生效：用 curl -I --http2 --insecure https://localhost:8000，响应头里应有 server: hypercorn-h2 或类似标识
• 如果 curl 报错 HTTP/2 stream 1 was not closed cleanly，大概率是证书或 ALPN 配置问题，不是代码逻辑错误
• 某些旧版 curl（--http2，会静默回退到 HTTP/1.1，建议用最新版或改用 httpx 测试

ASGI 应用本身不需要改，但中间件可能破坏 HTTP/2 语义

HTTP/2 的头部压缩、服务器推送、流优先级等特性由 Hypercorn 在 transport 层处理，你的 ASGI app 函数完全感知不到协议差异 —— 它收到的仍是标准 ASGI scope 和事件。

但要注意：部分中间件会篡改响应头或提前结束响应体，导致 HTTP/2 流异常关闭。

• 避免在中间件里手动写 response.headers['connection'] = 'close'，HTTP/2 不认这个头
• 不要用 StreamingResponse 返回未分块的超长 body（如一次性读完大文件再 yield），容易触发流重置
• 日志中间件如果对每个 chunk 都打时间戳并刷 stdout，可能拖慢流速，引发客户端超时，表现为 503 Service Unavailable 而非连接错误

用 httpx 而不是 requests 测试 HTTP/2 支持

requests 库至今（2024 年）仍不支持 HTTP/2，所有请求都走 HTTP/1.1，用来验证 HTTP/2 是否开启毫无意义。

真正能确认协议版本的工具只有：现代 curl、httpx、浏览器开发者工具的 Network 面板（Protocol 列）。

• 用 httpx --http2 --verify=false https://localhost:8000，输出里带 HTTP/2 字样才算成功
• Python 代码中测试：用 httpx.AsyncClient(http2=True, verify=False) 发起请求，再检查 response.http_version
• 别依赖服务端日志里的 “1.1” 或 “2” 字符串 —— Hypercorn 日志默认只写协议大类（如 h11 / h2），且位置不固定，不适合做自动化判断

最常被忽略的一点：HTTP/2 的 ALPN 协商发生在 TLS 握手阶段，一旦证书加载失败、密钥格式错误、或 OpenSSL 版本太老（openssl s_client -alpn h2 -connect localhost:8000 确认底层 TLS 层是否支持 h2 ALPN。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Hypercorn配置：PythonHTTP/2实战指南》文章吧，也可关注golang学习网公众号了解相关技术文章。