如何通过 client_body_buffer_size 调优带有缓存逻辑的请求转发内存处理上限-Nginx-PHP中文网

client_body_buffer_size 控制 Nginx 对 POST/PUT 等请求体的内存缓冲上限，过小导致写临时文件使缓存失效，过大则浪费内存；仅影响带请求体的请求，需据业务实际大小合理设置。

如何通过 client_body_buffer_size 调优带有缓存逻辑的请求转发内存处理上限

通过 client_body_buffer_size 调优请求体缓存行为，核心是控制 Nginx 在代理转发前对客户端请求体（如 POST/PUT 数据）的内存缓冲上限，尤其影响带缓存逻辑（如 proxy_cache 或 fastcgi_cache）的场景。若该值过小，Nginx 会将请求体写入临时文件，导致缓存失效（因缓存模块默认不缓存含临时文件体的请求）；若过大，则可能浪费内存或引发 OOM 风险。

理解 client_body_buffer_size 对缓存生效的关键影响

当启用缓存（如 proxy_cache）时，Nginx 默认仅缓存“完全在内存中处理完”的请求体。一旦请求体超出 client_body_buffer_size，Nginx 会将其刷入磁盘临时文件（路径由 client_body_temp_path 指定），此时即使配置了 proxy_cache，该请求也不会被缓存——这是缓存跳过的常见静默原因。

缓存判定发生在请求头解析后、请求体读取完成前，若检测到已使用临时文件，直接跳过缓存流程
client_body_buffer_size 不影响 GET 请求（无请求体），只作用于有 body 的方法（POST、PUT、PATCH 等）
该指令作用于每个请求独立缓冲区，不是全局总和

合理设置 buffer size 的实操建议

需结合业务典型请求体大小与服务器资源权衡设定，而非盲目调大：

查看应用层常见 POST/PUT 数据大小：如表单提交通常
推荐起始值：4 KB（默认值）适用于简单表单；8–16 KB 更适配多数 REST API；超过 64 KB 需谨慎，除非确认所有缓存请求体都稳定在此范围
配合 client_max_body_size 使用：后者限制整体请求上限（含 header + body），前者只管 body 缓冲内存；二者需协调，避免 buffer 小于实际 body 导致强制落盘

验证是否真正启用缓存的关键检查点

仅调大 client_body_buffer_size 不保证缓存生效，还需确认：

响应头含 X-Cache: HIT 或 MISS（需在 location 中显式添加 add_header X-Cache $upstream_cache_status;）
Nginx error 日志中无 client request body is buffered to a temporary file 类警告
使用 curl -v 发送可缓存的 POST 请求（如带相同 body 和 cacheable header），观察多次调用是否返回缓存响应
确认 proxy_cache_methods POST 已显式开启（默认只缓存 GET/HEAD）