nginx 的 sub_filter 是轻量级响应级脱敏手段，适用于 html 或文本接口中隐藏手机号、姓名、身份证号等；需配置 sub_filter_types、sub_filter_once、绕过 gzip 和分块传输限制，并注意匹配顺序与大小写敏感性。
在 Nginx 中用 sub_filter 替换敏感关键字，是一种轻量、低侵入的响应级脱敏手段，适合前端 HTML 页面或纯文本接口中隐藏手机号、姓名、身份证号等明文信息。它不依赖后端改造，但需严格满足内容类型、编码与缓冲条件。
基础配置：启用替换并指定目标类型
敏感词替换必须显式声明处理哪些响应类型，否则默认只对 text/html 生效：
-
sub_filter_types text/html text/plain application/json;—— 若后端返回 JSON 数据含用户姓名或手机号，需加入application/json -
sub_filter_once off;—— 确保页面内所有匹配项都被替换，例如一个页面出现三次“张三”，全部变成“***” - 每条
sub_filter指令独立生效，大小写敏感，不支持正则捕获，仅字面匹配
常见敏感词替换示例
以下配置可放在 location / 或具体 API 路径下：
-
sub_filter "13812345678" "138****5678";—— 手机号掩码（建议按固定格式统一处理） -
sub_filter "张三" "***";—— 姓名脱敏 -
sub_filter "身份证：11010119900307231X" "身份证：****************";—— 长文本整体遮盖
注意：多条规则按顺序执行，避免前后冲突（如先替“张”再替“张三”会出错），长词、高频词建议前置。
绕过压缩与编码限制
若后端返回 gzip 压缩内容，sub_filter 默认失效。解决方式有两种：
- 推荐：在
location中加proxy_set_header Accept-Encoding "";，让后端返回未压缩响应 - 备用：启用
gunzip on;（需确认 Nginx 编译时含ngx_http_gunzip_module），自动解压后再替换 - 禁用分块传输：添加
proxy_buffering on;和合理proxy_buffer_size，避免流式响应截断导致漏替换
验证与避坑要点
替换是否生效，不能只看浏览器 Elements 标签页（DOM 已被解析渲染），应检查 Network → Response 原始内容：
- 确保响应头含
Content-Type: text/html等已列入sub_filter_types的类型 - 状态码需为 200/201/206 等允许改写的类型；4xx/5xx 响应默认不处理
- 占位符含特殊字符（如
/、;）时，用单引号包裹整条指令，避免语法错误 - 不支持忽略大小写，如需“张三”“ZHANGSAN”都脱敏，得分别写两条规则
