sub_filter高效运行的关键是精准控制作用范围：仅对必要MIME类型启用，禁用无关类型；关闭响应压缩或合理设置buffer大小；按location分层配置；确保编码统一为UTF-8。
要让 sub_filter 既精准生效、又不拖慢性能，关键不在“多替换”，而在“只处理该处理的”。sub_filter_types 就是那个决定“哪些响应能进替换流水线”的开关——配得松，Nginx 可能白忙活甚至吃内存；配得准，才能轻量、可控、可预期。
明确指定 MIME 类型，避免通配符滥用
很多人图省事写 sub_filter_types *，以为“全接住”更稳妥。实际这会让 Nginx 对所有响应（包括图片、字体、视频流、压缩包）都尝试缓冲、解码、扫描字符串——哪怕它们根本不是文本。结果就是：无效 buffer 占用、CPU 白耗、GC 压力上升，尤其在高并发小响应场景下，内存碎片和分配失败风险陡增。
- 只加真正需要改写的类型：比如前端项目，通常只需
text/html text/css text/javascript application/json - 若仅改 HTML 页面文案，就保持默认
text/html，连 CSS/JS 都不碰 - 绝对不要对
application/octet-stream或image/*启用替换——模块无法处理二进制，强行匹配会跳过或报错
配合禁用压缩，防止 buffer 膨胀失控
sub_filter 必须操作原始未压缩内容。如果后端返回 gzip 响应，Nginx 默认不会自动解压——它要么跳过替换（因 Content-Type 不匹配），要么在启用 gunzip on 后把整个响应体解压进内存再处理。这对大 JSON 或长 HTML 来说，buffer 可能瞬间翻倍。
- 推荐做法：在 location 中显式关闭压缩
gzip off;，并告知后端别发 gzip（加proxy_set_header Accept-Encoding "";） - 如必须保留压缩，启用
gunzip on;的同时，务必限制 buffer 大小：sub_filter_buffer_size 256k;（默认约 1MB，对多数页面已过大） - 监控
nginx -t输出是否含warn: sub_filter_buffer_size is too small，这是内存压力早期信号
按业务路径分层控制，缩小作用域
全局替换看似方便，实则放大风险。一个 /api/v1/user 返回的 JSON 若被误加了 sub_filter_types application/json，又没设 buffer 限值，可能让单次 2MB 用户数据在内存中膨胀为 4MB+（解压+替换+输出）。正确做法是“按需授权”：
- 静态资源走独立 location：
location ~* \.(js|css|html)$ { ... sub_filter ... sub_filter_types ... } - API 接口单独配置，且只开
application/json，禁用其他类型 - 用
include抽离规则文件，确保同一套sub_filter+sub_filter_types只在明确需要的 location 中加载，不扩散
留意编码一致性，避免 buffer 错位重分配
sub_filter 是字节流替换，不解析字符编码。如果后端返回 GBK 编码的 HTML，但 Nginx 按 UTF-8 解读，查找字符串时会出现偏移错位——模块可能反复扩容 buffer 尝试对齐，最终触发内存告警。
- 强制后端统一输出
Content-Type: text/html; charset=utf-8 - Nginx 不做编码转换，也不建议用
charset utf-8指令覆盖响应头——那只是告诉浏览器怎么解码，不影响 sub_filter 内部处理逻辑 - 若无法统一编码，宁可放弃 sub_filter，改用 Lua 在 body_filter_by_lua_block 中手动 decode/encode 处理
