ngx_http_chunked_filter_module 是 Nginx 实现 HTTP/1.1 分块传输编码的核心模块，仅在 HTTP 版本 ≥ 1.1、未设 Content-Length、状态码允许 body 且未禁用 chunked 时触发，通过重写 chain_t 链表插入 chunk header（如 "X\r\n"）、trailer（"\r\n"）及终止标记 "0\r\n\r\n"，不拷贝数据而注入边界信息，依赖 filter 链顺序与内存管理协同工作。

nginx 的 ngx_http_chunked_filter_module 是实现 HTTP/1.1 分块传输编码（Chunked Transfer Encoding）的核心模块，它在响应体不带 Content-Length 且启用 chunked 编码时自动介入，将响应数据按块封装并追加 0\r\n\r\n 结束标记。它的逻辑并不复杂，但嵌入在 filter 链中、与内存管理及上下游协同紧密，理解其源码有助于排查响应截断、头部错乱、大文件流式输出异常等问题。

何时触发 chunked 编码

该模块不是默认始终启用的，它只在满足以下全部条件时才参与处理：

• 请求使用的 HTTP 版本 ≥ 1.1（r->http_version >= NGX_HTTP_VERSION_11）
• 响应未显式设置 Content-Length 头（r->headers_out.content_length_n == -1）
• 响应状态码允许 body（如非 1xx/204/304）且未禁用 chunked（r->chunked 为 1）
• 上游未自行完成 chunked 封装（例如某些 upstream 模块已写好 chunk header）

注意：r->chunked = 1 通常由 ngx_http_set_chunked 设置，发生在 header 过滤阶段（如 ngx_http_header_filter）检测到无 Content-Length 时。

核心过滤逻辑：ngx\_http\_chunked\_filter

该函数是模块主入口，被注册为 body filter，在每个 output chain buffer 到达时调用。它不直接操作 socket，而是重写 chain_t 链表结构，插入 chunk header 和 trailer：

• 对首个非空 buffer，前置插入形如 "X\r\n" 的 chunk size 行（十六进制 + CRLF）
• 对每个 buffer 末尾追加 "\r\n"（chunk data 后的 CRLF）
• 在整条响应结束时（收到空 buffer 或 last_buf 标志），插入终止块 "0\r\n\r\n"
• 若遇到 flush 标志或 last_buf，立即尝试发送当前链表，避免缓冲堆积

关键细节：它不拷贝原始数据，而是通过构造新的 ngx_buf_t（指向栈上字符串或常量内存）并调整 chain_t 指针关系来“注入”chunk 边界信息。所有 chunk header 均分配在 request pool 中，生命周期与请求一致。

与内存和 buffer 管理的协作

chunked filter 对 buffer 类型敏感，会跳过某些特殊 buffer：

• 忽略 buf->in_file == 1 的文件 buffer（不处理 sendfile 场景，chunked 不适用于纯 sendfile）
• 跳过 buf->sync 或 buf->last_buf 但尚未结束的 buffer（交由后续逻辑判断）
• 当一个 buffer 同时含 last_buf 和 last_in_chain，即视为响应终结，立即添加 "0\r\n\r\n"

若响应中途出错（如 upstream timeout），模块依赖 ngx_http_finalize_request 清理未发送的 chunk header，避免客户端等待超时。这也意味着：手动调用 ngx_http_send_special(r, NGX_HTTP_LAST) 时，必须确保此前所有 body 已经过 chunked filter，否则结尾 chunk 可能丢失。

调试与常见问题定位

遇到 chunked 相关异常（如浏览器卡在 loading、curl 报 transfer closed with outstanding read），可从以下方向切入：

• 开启 error_log debug;，搜索 "http chunked" 日志，确认模块是否被调用及插入 header 的位置
• 用 tcpdump 或 Wireshark 抓包，检查响应流中是否缺失 "0\r\n\r\n" 或 chunk size 格式错误（如十进制、多出空格）
• 检查是否有其他 filter（如 gzip、slice）顺序错误——chunked filter 必须在压缩 filter 之后（否则压缩后长度未知，无法 chunk），但在 write filter 之前
• 自定义模块若直接操作 r->out 或绕过 filter 链写 body，极易破坏 chunked 结构，应统一走 ngx_http_output_filter

不复杂但容易忽略：chunked 是协议层封装，它不改变业务数据，只负责让长度未知的流可被 HTTP 客户端正确解析。理解它如何穿插在 filter 链中，比记住每行代码更重要。