thread_pool 必须定义在 main 块，不能在 events、http 或 server 块中配置；大文件 IO 阻塞需配合 aio threads 指令启用线程池，且必须关闭 sendfile 才生效。
不能在 events 块中配置 thread_pool。
thread_pool 必须定义在 main 块
Nginx 的线程池是全局资源，每个 worker 进程独享一个实例，因此只能在配置文件最外层（即 main 上下文）中声明。常见错误是把它写进 events、http 或 server 块，Nginx 会直接报错：
正确位置示例：
# nginx.conf
worker_processes auto;
<h1>✅ 正确：main 块中定义</h1><p>thread_pool default threads=16 max_queue=8192;
thread_pool uploads threads=32 max_queue=65536;</p><p>events {
use epoll;
worker_connections 1024;
}</p><p>http {
...
}大文件 IO 阻塞的真正触发点不在 events
events 块只管网络连接事件（accept、read ready、write ready），不处理磁盘读取。大文件阻塞发生在：
– 使用 alias 或 root 返回静态文件时
– gzip_static off 且需解压读 .gz 文件
– 启用 directio 后的用户态读取
– 日志写入或 SSL 证书加载等后台操作
这些场景需要配合 aio threads 指令启用线程池，而该指令**只能出现在 http、server 或 location 块中**，例如：
location /downloads/ {
alias /data/files/;
aio threads=default;
directio 4m; # 触发线程池读取
output_buffers 1 128k;
sendfile off; # ⚠️ 必须关闭 sendfile 才生效
}关键生效条件必须同时满足
- sendfile 必须为 off：否则内核直接零拷贝发送，绕过用户态读，线程池不介入
- aio threads=xxx 要显式开启，并指向已定义的池名
- directio 或大文件读取行为存在：小文件（如 < 4k）默认走 page cache，一般不触发阻塞读
- 文件系统延迟高：HDD、NFS、加密盘等场景效果明显；本地 NVMe SSD 上收益有限
推荐配置组合
针对大文件下载服务（如 /downloads/）：
# main 块
thread_pool downloads threads=32 max_queue=32768;
<h1>location 块</h1><p>location /downloads/ {
root /storage;
sendfile off;
aio threads=downloads;
directio 8m;
output_buffers 1 256k;
tcp_nopush off; # 配合 aio 更稳定
}注意：不要盲目增大 threads 数——每个线程占用内存和文件句柄，建议按预期并发下载数 × 1.5 估算，上限不超过 64。
