启用 sendfile on 时 Lua 模块无法输出自定义二进制流，因内核零拷贝与用户态输出缓冲冲突；应禁用 sendfile 并分块输出。
当 Nginx 启用 sendfile on 时，Lua 模块（如 ngx_lua）无法直接输出自定义二进制流（例如通过 ngx.say()、ngx.print() 或 ngx.exec() 返回非文本内容），这是由内核零拷贝机制与 Lua 输出缓冲机制的根本冲突导致的。
sendfile 与 Lua 输出的本质矛盾
sendfile 是内核态的文件高效传输机制，绕过用户空间，直接在内核 buffer 间复制；而 Lua 模块所有 ngx.print() 等调用都写入 Nginx 用户空间的输出链表（ngx_chain_t）。一旦开启 sendfile on，Nginx 会优先尝试用 sendfile() 发送响应体——但此时若响应体尚未落盘（比如是 Lua 动态生成的内存二进制块），就无法提供合法的文件描述符和偏移，导致行为未定义：常见表现为连接被重置、响应截断、或直接 500 错误。
确认是否触发了该冲突
可通过以下方式快速定位：
- 检查 Nginx error log 中是否出现
sendfile() failed (32: Broken pipe)、sendfile() failed (32: Broken pipe) while sending to client或lua entry thread aborted: runtime error: ... attempt to send data after sendfile - 临时关闭
sendfile（设为off）并复现请求，若问题消失，则基本可确认是此冲突 - 使用
strace -e trace=sendfile,write,writev -p $(pidof nginx)观察实际系统调用路径
安全可靠的解决方案
核心原则：对 Lua 动态生成的响应（尤其是二进制流），必须禁用 sendfile 并启用用户态输出路径。推荐做法如下：
- 在
location块中显式关闭sendfile：
sendfile off; - 确保不触发 Nginx 的静态文件优化逻辑（如避免
try_files @fallback回退到静态文件服务） - 若需返回大二进制数据（如动态生成图片、PDF），建议分块输出：
ngx.flush() 配合循环ngx.print(chunk)，并设置合适的Content-Length或保持 chunked 编码 - 对于小响应（ngx.say(data)，Nginx 会自动使用
writev发送
不推荐的“绕过”方式
某些方案看似可行，但存在严重隐患，应避免：
- 全局关闭
sendfile on：牺牲所有静态资源性能，得不偿失 - 用
ngx.exec("@static")跳转到一个sendfile on的 location：Lua 已开始输出，跳转后响应头可能已发送，易导致协议错误 - 尝试用
lua_shared_dict+alias模拟文件：无法保证原子性与生命周期，且仍需额外磁盘 I/O
