sub_filter默认仅处理text/html,需用sub_filter_types显式添加application/json、text/css等类型才能生效;类型名须与Content-Type响应头完全一致,且配置须与sub_filter同作用域。

Nginx 的 sub_filter 默认只对 text/html 类型响应生效,若需对 JSON、XML、CSS、JS 等其他文本类响应也启用替换,必须显式配置 sub_filter_types 指令。
sub_filter_types 的作用与默认行为
该指令用于扩展 sub_filter 的作用范围。Nginx 默认等价于:sub_filter_types text/html;
这意味着即使你写了 sub_filter "old" "new";,它也不会处理 application/json 或 text/css 响应——除非你主动添加对应 MIME 类型。
如何正确配置支持多类型
在 location 或 server 块中,将需要处理的 MIME 类型逐个列出(不支持通配符):
- 确保
sub_filter已启用(如sub_filter "http://" "https://";) - 添加所需类型,例如:
sub_filter_types application/json text/css text/javascript text/xml; - 注意:类型名须与响应头
Content-Type中的值完全一致(包括大小写和参数),如application/json; charset=utf-8仍匹配application/json - 若响应含压缩(如 gzip),需确保
sub_filter在解压后执行——Nginx 会自动处理,但要求gzip off或使用gzip_vary off避免缓存干扰
常见误配与排查建议
替换未生效?检查以下几点:
- 确认后端实际返回的
Content-Type值(用curl -I查看响应头),避免拼写差异(如text/plain写成text/plaintext) -
sub_filter_types必须出现在sub_filter后面,且在同一作用域;若在http块定义,子块需用sub_filter_types *;继承(Nginx 1.17.2+ 支持*表示全部类型,但慎用) - 动态内容(如 PHP、Node.js 输出)若设置了
Content-Encoding: gzip,而 Nginx 未配置gzip_disable或未关闭代理压缩,可能导致 sub_filter 跳过处理 - 替换仅对响应体生效,不影响响应头或二进制内容;对图片、PDF 等非文本类型即使加入 types 也无效
合理设置 sub_filter_types 能让内容替换精准作用于目标格式,既避免无效扫描,又防止遗漏关键接口响应。


















