client_body_in_file_only 是强制请求体落盘、实现内存与磁盘物理隔离的开关，需配合专用 location、最小缓冲区、独立 temp_path 及 clean 模式使用，确保大文件上传不争抢资源、可流式透传。
client_body_in_file_only 不是用来“微调性能”的指令，而是用来强制请求体落盘、物理隔离内存与磁盘路径的开关。它在高性能网关中真正的价值，不是提速，而是为特定长文件上传路径（如 /upload/video、/api/v1/batch-import）提供确定性行为：绕过内存缓冲、规避 buffer 争抢、防止大请求拖垮 worker 内存，并将 I/O 压力显式导向可控的磁盘子系统。
要达成“物理隔离”，关键不是单独设 on，而是组合配置 + 路径收口 + 权限管控：
✅ 隔离目标路径，禁用共享缓冲区竞争
只在明确需要长文件直通的 location 中启用，与其他轻量 API 完全分离：
location /upload/large {
# 强制所有请求体写入文件（无论大小）
client_body_in_file_only on;
# 缓冲区压到最小，避免小请求也占内存
client_body_buffer_size 8k;
# 允许超大文件（如 5GB），但不意味着全放内存
client_max_body_size 5g;
# 指向专用 SSD 分区或 tmpfs 挂载点，与主服务磁盘解耦
client_body_temp_path /mnt/ssd/nginx-upload-temp 1 2;
proxy_pass http://storage-backend;
proxy_set_header X-File-Path $request_body_file; # 后端可直接读取
}
注意：
/mnt/ssd/nginx-upload-temp必须由 nginx worker 用户（如www-data）可写，且需提前mkdir -p并chown。
✅ 显式控制临时文件生命周期，避免残留堆积
client_body_in_file_only 有两个取值：
-
on：文件写完后不自动删除，由后端或定时任务清理（适合需要二次校验、断点续传等场景） -
clean：请求处理完成后（无论成功失败）自动 unlink 临时文件（推荐用于一次性上传）
生产建议统一用 clean，再配合简单 cron 清理残余（防崩溃遗留）：
# 每小时清理 1 小时前未访问的临时文件 find /mnt/ssd/nginx-upload-temp -type f -mmin +60 -delete 2>/dev/null
✅ 配合后端协议，跳过内存中转，实现真正流式透传
Nginx 设置 client_body_in_file_only clean 后，会把完整文件路径通过 $request_body_file 变量注入 header（仅 proxy_pass 场景有效）。后端无需解析 body，直接 open() 该路径即可：
- Spring Boot 接收方可用
@RequestHeader("X-File-Path") String path获取 - Go/Python 等可直接
os.Open(path)流式读取，全程零内存拷贝 - 若后端支持
X-Sendfile或X-Accel-Redirect，甚至可让 Nginx 直接回源发送，彻底卸载后端 I/O
❌ 必须避开的误用陷阱
- 不要在
if块里设置 —— 语法非法，Nginx 启动报invalid - 不要和
client_body_buffer_size大值混用（如设2m）—— 逻辑冲突，on会忽略 buffer 大小，但配置冗余易引发误解 - 不要跨 location 共享
client_body_temp_path—— 失去物理隔离意义，不同业务的临时文件混在一起，无法按路径限速、配额或监控
不复杂但容易忽略。物理隔离的本质，是让“大文件”走一条从入口到后端的专属车道，不挤占其他请求的内存资源，也不依赖不可控的缓冲区调度逻辑。
