NGINX模块开发需深度适配HTTP/2：应基于解帧后语义编程，正确处理小写头部、伪头映射；避免filter阶段直接修改headers_out指针；用ngx_http_is_v2()精准判协议；关键头部查找宜预建哈希索引优化性能。
NGINX 模块开发中若需深度支持 HTTP/2，不能仅依赖默认行为——核心在于理解其二进制帧机制与头部压缩（HPACK）特性，避免直接复用 HTTP/1.x 的 header 处理逻辑。
HTTP/2 帧层不可见，模块应面向“解帧后语义”编程
NGINX 在接收 HTTP/2 请求时，已由 ngx_http_v2_module 完成帧解析、流管理、HPACK 解码等底层工作。模块开发者看到的 r->headers_in 是解压还原后的头部集合，与 HTTP/1.x 表面一致，但有关键差异：
- 所有头部名自动转为小写（如
Content-Type→content-type），且无重复键； -
:method、:path、:scheme等伪头部已映射为标准字段（r->method_name、r->uri、r->schema），不应再从 headers_in 中手动提取； - HTTP/2 允许头部分帧（header block fragmentation），但 NGINX 已合并处理，模块无需感知碎片。
避免在 ngx_http_header_filter_t 中修改原始 header 字符串
HTTP/2 响应头部在发送前会经 HPACK 编码。若模块在 filter 阶段直接篡改 r->headers_out 中 header 的 value.data 指针或长度（例如用 ngx_pstrdup 替换 value），可能导致：
- HPACK 编码器引用已释放内存（因原 buffer 被 pool 清理）；
- 头部值被截断（未同步更新
value.len）； - 动态生成的 header（如
set_header X-Processed "true"）未触发 HPACK 上下文更新，影响后续请求压缩效率。
正确做法：使用 ngx_list_push 添加新 header，或调用 ngx_http_clear_content_length 等封装函数安全修改已有字段。
利用 NGX_HTTP_V2 宏精准识别协议版本
不要依赖 r->http_version == NGX_HTTP_VERSION_20 判断——该字段在 HTTP/2 下恒为 20，但无法区分是否真正在 HTTP/2 连接上（如被中间代理降级）。应结合连接层级判断：
- 检查
r->connection->quic是否非空（QUIC 场景）； - 更可靠方式是读取
r->connection->protocol，HTTP/2 连接该值为"HTTP/2.0"字符串； - 或直接使用
ngx_http_is_v2(r)宏（定义于ngx_http.h），它内部校验连接协议并兼容未来扩展。
头部解析性能优化：跳过冗余遍历与预分配
高频 header 查找（如鉴权、路由匹配）应避免每次调用 ngx_list_part 遍历整个 headers_in 链表。建议：
- 在
ngx_http_post_read_phase或access_handler中，对关键 header（如authorization、x-forwarded-for）建立哈希索引缓存到r->pool； - 使用
ngx_hash_keys_arrays_t构建静态哈希表（适用于编译期已知 header 名）； - 对重复出现的 header（如多个
cookie），用ngx_array_t预分配空间收集，避免多次ngx_palloc开销。
NGINX 自身的 ngx_http_parse_header_line 已高度优化，除非特殊需求（如解析自定义二进制 header 扩展），否则不建议重写解析逻辑。
