client_body_in_file_only on 是 nginx 调试/安全指令，强制请求体全写入磁盘临时文件且禁用内存读取，默认 off；仅允许在 http/server/location 块中配置，需配合 client_body_temp_path、buffer_size 和 max_body_size 使用，启用后性能下降并需注意权限、磁盘空间及文件清理问题。
client_body_in_file_only on 是 Nginx 的一个内部调试/安全相关指令，不建议在生产环境中直接设置为 on，它主要用于强制将客户端请求体（如 POST 数据）全部写入临时文件，且禁止从内存读取。默认值是 off，正常情况下 Nginx 会根据请求体大小自动选择内存或临时文件存储。
如果你确实需要启用它（例如用于调试大请求体处理逻辑，或配合某些特殊模块），需注意以下几点：
- 该指令**只能出现在
http、server或location块中 - 它必须与
client_body_buffer_size和client_max_body_size配合使用 - 开启后，所有请求体（无论大小）都会被写入磁盘临时文件，且不会保留在内存中，这会影响性能，还可能引发权限或磁盘空间问题
正确配置方式
http {
# 设置临时文件存放路径（确保目录存在且 Nginx 有写权限）
client_body_temp_path /var/tmp/nginx/client_body;
server {
listen 80;
server_name example.com;
location /upload {
# 启用强制写文件模式
client_body_in_file_only on;
# 确保缓冲区足够小（否则小请求仍可能走内存）
client_body_buffer_size 1k;
# 允许上传较大文件（按需调整）
client_max_body_size 100m;
# （可选）显式指定临时文件清理行为
client_body_timeout 60s;
proxy_pass http://backend;
proxy_set_header X-Request-Body-File $request_body_file; # 后端可获取文件路径
}
}
}
关键注意事项
-
/var/tmp/nginx/client_body目录必须由运行 Nginx 的用户（如www-data或nginx）可写，且需提前创建 -
client_body_in_file_only on时，Nginx 会通过$request_body_file变量向后端传递临时文件路径（仅限proxy_pass场景） - 若同时设置了
client_body_in_file_only clean，则请求结束后会自动删除临时文件；设为on则不会自动清理，需自行处理残留文件 - 该指令与
underscores_in_headers on、large_client_header_buffers等无关，不要混淆作用域
常见误用场景
- 在
if块中使用 —— 不合法，Nginx 会报错invalid directive - 未配
client_body_temp_path—— Nginx 使用默认路径（通常是/var/tmp/nginx/client_body），但若该路径不可写，会导致 411 或 500 错误 - 与
fastcgi_pass或uwsgi_pass配合时，$request_body_file变量不一定被后端框架识别，需额外开发支持
不复杂但容易忽略
