Nginx中不存在sub_filter_buffers指令，其功能由proxy_buffering、proxy_buffers和proxy_buffer_size等代理缓冲指令协同实现；需开启proxy_buffering并合理配置缓冲区大小与数量，同时关闭gzip、精确设置sub_filter_types，才能确保sub_filter对大响应体完整生效。
sub_filter_buffers 本身并不存在——Nginx 官方文档和所有稳定版本（截至 2026 年）中，没有 sub_filter_buffers 这个指令。你可能混淆了 Nginx 的缓冲机制：真正控制 sub_filter 处理能力的，是 proxy_buffering、proxy_buffers 和 proxy_buffer_size 等代理缓冲指令，而非一个独立的 “sub_filter_buffers”。
为什么不存在 sub_filter_buffers？
Nginx 的 sub_filter 模块不管理自己的缓冲区，它完全依赖上游响应的缓冲行为。它只对 Nginx 已完整接收并解压（若需）后的响应体做一次扫描替换。因此：
- 没有名为 sub_filter_buffers 的配置项，写入配置会直接导致 nginx -t 报错：“unknown directive”
- 所谓“提升大规模文本替换效率”，实质是确保 Nginx 能把整个响应体（尤其是大 HTML/JS 文件）先缓存在内存中，再交给 sub_filter 处理
- 若响应被分块传输（chunked）且未缓冲，或缓冲区太小导致响应被分片处理，sub_filter 可能只作用于前几 KB，造成替换不全甚至失败
真正起作用的缓冲配置组合
要在代理场景下可靠处理大 HTML 或 JS 文件（例如 500KB+），需在 location 块中显式调优以下三项：
- proxy_buffering on; —— 必须开启，否则 sub_filter 无法获得完整响应体
- proxy_buffer_size 128k; —— 设置首块缓冲区大小，建议 ≥ 最大响应头长度（通常 4k–128k 足够）
- proxy_buffers 16 128k; —— 总缓冲区 = 16 × 128k = 2MB，可覆盖多数单页应用 HTML 或压缩前 JS
示例配置：
location /app/ {proxy_pass https://backend;
proxy_buffering on;
proxy_buffer_size 128k;
proxy_buffers 16 128k;
sub_filter '/static/' 'https://cdn.example.com/static/';
sub_filter_once off;
sub_filter_types text/html application/javascript text/css;
gzip off; # 避免压缩导致 sub_filter 失效
}
配合 gzip 和内容类型的注意事项
即使缓冲足够，以下两点仍会导致 sub_filter “看似生效实则静默跳过”：
- gzip 未关闭：后端返回 gzip 压缩的 HTML，Nginx 若未启用 gunzip，则 sub_filter 直接忽略；稳妥做法是 proxy_set_header Accept-Encoding ""; 强制后端返回明文
- sub_filter_types 不匹配：比如 JS 文件返回 Content-Type: application/javascript，但配置里只写了 text/html —— 替换不会触发。务必按实际类型精确声明，不加 * 或 text/*
验证是否真正生效的简单方法
用 curl 检查三要素：
- Content-Type：curl -I https://yoursite/app/index.html | grep Content-Type
- Content-Encoding：确认无 gzip 或 br（若有，需配 gunzip on）
- 响应体内容：curl https://yoursite/app/index.html | grep "https://cdn.example.com" —— 查看替换结果
