keepalive_timeout用于控制HTTP长连接空闲保持时间，接受1~2个秒级参数，分别表示服务器关闭空闲连接时限和响应头中Keep-Alive timeout值；可在http、server、location块中配置，优先级为location>server>http；需协同client_body_timeout、proxy_read_timeout等参数避免冲突，并通过nginx -t && nginx -s reload生效。
直接在 http、server 或 location 块中设置 keepalive_timeout 指令即可，这是控制 HTTP 长连接空闲保持时间的核心参数。
keepalive_timeout 的基本用法
该指令接受一个或两个数值参数，单位默认是秒（可显式写 s）：
- 第一个值：服务器端保持空闲连接的最大时长，超时即关闭连接
- 第二个可选值：写入响应头
Keep-Alive: timeout=...的数值，影响部分浏览器行为
例如：keepalive_timeout 60s; 表示连接空闲 60 秒后关闭，并在响应头中写 Keep-Alive: timeout=60。
常见配置建议
不同场景下推荐值差异明显，需结合实际业务和客户端兼容性：
- 通用网站或 API 服务：设为
30s～60s，兼顾复用效率与资源释放 - 高并发轻量接口：可压至
15s～20s，加快连接回收 - 静态资源站（如 CDN 边缘节点）：可设为
5s～10s，减少长连接堆积 - 禁用 keepalive：设为
0，即keepalive_timeout 0;
注意：主流浏览器（如 Chrome、Firefox）实际只认约 60 秒，IE/Edge 更倾向 60–65 秒，设超过 60 秒意义有限。
配置位置与作用范围
该指令可在多个层级生效，优先级从高到低为：location > server > http：
- 全局统一控制：放在
http块中，适用于大多数站点 - 按域名区分：放在某个
server块内，适配特定虚拟主机 - 按路径精细化管理：放在
location /api/等块中，例如对上传接口设更短值
示例：
http {keepalive_timeout 60s;
server {
listen 443 ssl;
server_name api.example.com;
keepalive_timeout 20s;
location /upload/ {
keepalive_timeout 5s;
}
}
}
配套注意事项
单独调这个参数还不够，需协同其他超时项避免冲突：
-
keepalive_timeout应大于client_body_timeout，否则大文件上传中途连接可能被误关 - 若使用反向代理，
proxy_read_timeout和proxy_send_timeout也应不低于 keepalive 值，尤其后端处理慢时 - 启用 keepalive 后，建议同时检查
keepalive_requests（单连接最大请求数），防止连接长期占用
修改后需执行 nginx -t && nginx -s reload 生效，可用 curl -I 查看响应头中是否出现 Keep-Alive: timeout=... 来验证。
