ngx_http_fastcgi_module是HTTP与FastCGI协议间的翻译器，负责请求封装、参数映射、流式转发和响应解析，核心为零拷贝协议转换而非网络通信。
nginx 的 ngx_http_fastcgi_module 并不实现 FastCGI 协议本身，而是负责将 HTTP 请求“翻译”为符合 FastCGI 规范的二进制数据流，并将后端返回的 FastCGI 响应解析回 HTTP 响应。它的核心是协议封装与解封装，而非网络通信或进程管理。
FastCGI 消息结构如何映射到 nginx 内存布局
FastCGI 协议基于固定长度的 record（记录），每个 record 长度为 8 字节 header + payload（最大 65535 字节）。nginx 使用 ngx_http_fastcgi_header_t 结构体精确对齐 header 字节布局：
- 前 1 字节为版本号（固定为 1）
- 第 2 字节为类型（如
FCGI_BEGIN_REQUEST、FCGI_PARAMS、FCGI_STDIN） - 第 3–4 字节为请求 ID（network byte order，nginx 始终用 1）
- 第 5–6 字节为 content length（payload 实际字节数，大端序）
- 第 7 字节为 padding length（填充字节数，使 total % 8 == 0）
- 第 8 字节保留（全 0）
实际构造时，nginx 不直接 malloc record，而是复用 request 的 pool 和 bufs 链表，在 ngx_http_fastcgi_create_request() 中逐段写入：先填 header，再写 name-len/value-len/name/value（用于 PARAMS），最后补 padding。整个过程无 memcpy，靠指针偏移和长度计算完成零拷贝组装。
HTTP 头部如何转成 FastCGI PARAMS 键值对
nginx 并非原样转发所有 HTTP 头。它按 fastcgi_param 指令显式定义规则，例如：
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_param QUERY_STRING $query_string; fastcgi_param REQUEST_METHOD $request_method;
在 ngx_http_fastcgi_params() 中，每条指令被编译为一个 ngx_http_script_code_pt 可执行片段。执行时动态展开变量（如 $request_method → "GET"），并调用 ngx_http_fastcgi_encode_kv() 将 key 和 value 编码为 FastCGI 的 length-prefixed 格式（1/4 字节长度 + 内容），然后追加到 PARAMS record 的 payload 区域。
特别注意：CONTENT_LENGTH 和 CONTENT_TYPE 仅在请求体存在且非 GET/HEAD 时才注入；HTTP_* 头默认全部转为 HTTP_Xxx 形式（下划线转横线，首字母大写），但可通过 underscores_in_headers on 改变行为。
请求体（body）如何分块发送而不阻塞
当 client 发送大 body（如文件上传），nginx 不等全部接收完再发给 FastCGI。它采用流式转发策略：
- 若
fastcgi_buffering off，则 body 到达即刻封装为FCGI_STDINrecords，每块 ≤fastcgi_busy_buffers_size（默认 256KB），边收边发 - 若开启 buffering，则先暂存至内存 buffer 或临时文件，待
POST完整后再一次性发出多个 STDIN record - 每个 STDIN record 的 content length 取决于当前可用数据量，末尾 record 可能为 0（表示 EOF）
关键点在于：nginx 使用 ngx_event_pipe_t 管理双向流，通过 read_event_handler 和 write_event_handler 解耦读写事件，避免因后端处理慢导致 client 连接超时。
响应解析如何应对不规范的 FastCGI 输出
FastCGI 标准允许一个请求对应多个 FCGI_STDOUT record（支持流式响应），也允许混杂 FCGI_STDERR。nginx 在 ngx_http_fastcgi_process_record() 中严格按 record type 分流：
-
FCGI_STDOUT：写入输出缓冲区，触发 HTTP 响应头/体发送 -
FCGI_STDERR：写入 error log（级别为NGX_LOG_ERR），不影响响应流程 -
FCGI_END_REQUEST：检查 status（0=success，非0=failure），决定是否关闭连接或重试
对常见异常有容错机制：record length 超限自动截断、padding 长度错误则跳过该 record、type 未知则静默丢弃。但若连续收到非法 record，会触发 FCGI_UNKNOWN_TYPE 并终止连接，防止协议混淆攻击。
理解这四个层面，就抓住了 ngx_http_fastcgi_module 的骨架——它本质是一个运行在 event loop 上的协议翻译器，所有逻辑围绕“如何把 HTTP 语义准确、高效、安全地编码进 FastCGI 字节流”展开。
