client_body_buffer_size 控制 Nginx 对 POST/PUT 等请求体的内存缓冲上限，过小导致写临时文件使缓存失效，过大则浪费内存；仅影响带请求体的请求，需据业务实际大小合理设置。
通过 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）
替代方案：绕过缓存对请求体的依赖
若业务确实存在较大但可缓存的请求体（如固定配置模板 POST），又不愿扩大内存占用，可考虑：
- 改用 GET + query 参数传递结构化数据（需注意长度和编码限制）
- 前端预计算请求指纹（如 body 的 SHA256），用该指纹作为 GET 路径的一部分，使缓存基于路径而非原始 POST
- 在上游服务中实现幂等性与本地缓存，让 Nginx 专注做无状态转发
