Nginx 中 client_body_buffer_size 配置对上传文件的影响

client_body_buffer_size控制请求体内存缓冲大小，决定文件是全程驻留内存还是部分落盘；它不管上传上限（由client_max_body_size控制），只管“怎么传”。

这个参数直接决定上传文件是走内存还是落磁盘——它不控制能传多大，但决定“怎么传”。

它管什么，不管什么

client_body_buffer_size 只控制 Nginx 接收请求体时，为每个请求分配的初始内存缓冲区大小。上传文件是否成功，由 client_max_body_size 决定；而文件内容是全程在内存里处理，还是部分写入临时文件，就看这个缓冲区够不够用。

1. 文件大小 ≤ 缓冲区：整个请求体留在内存，转发快、无磁盘 I/O
2. 文件大小 > 缓冲区但 ≤ client_max_body_size：先填满内存，超出部分写入 client_body_temp_path 指定的临时文件
3. 文件大小 > client_max_body_size：Nginx 在读取请求头阶段就返回 413 错误，根本不会尝试接收数据

设小了会怎样

默认值通常是 8KB 或 16KB，对现代上传场景基本不够用。设得太小会导致：

1. 几百 KB 的图片或文档也频繁落盘，增加磁盘 I/O 和延迟
2. 临时文件生成量大，client_body_temp_path 目录可能被撑爆或写满
3. 出现 “could not open temp file” 报错（常见于权限不足或空间不足）
4. 并发稍高时，worker 进程内存 RSS 持续上涨，影响稳定性

设多大才合适

不是越大越好，要按业务典型上传尺寸来定：

1. 纯 JSON API 或表单提交：64KB–128KB 足够，比默认值更稳，又不浪费内存
2. 头像/截图/常规附件（≤2MB）：128KB–512KB 是平衡点，覆盖大多数请求
3. 文档/压缩包上传（≤20MB）：可设 2MB–4MB，但需确认单 worker 并发 × 缓冲区 ≤ 可用内存
4. 高并发轻量提交（如埋点、心跳）：反而建议调小到 4KB，省内存换连接数

必须同步检查的三项

单独改这个参数往往没效果，以下三者缺一不可：

1. client_max_body_size 必须 ≥ 缓冲区值，且配置作用域要匹配上传路径（比如在对应 location 块里显式设置）
2. client_body_temp_path 对应目录必须存在、Nginx 工作用户有读写权限、磁盘空间充足（即使很少用，启动时也会校验）
3. client_body_timeout 建议设为 10–300 秒，防慢速上传长期占着缓冲区，拖慢 worker