Nginx sub_filter 可在不改代码、不重启服务前提下软下线静态网页模块，需精准定位唯一HTML片段、用注释或display:none安全替换，并配置sub_filter_types、gunzip、sub_filter_once、sub_filter_last_modified四项关键参数。
不用改代码、不重启服务，靠 Nginx 的 sub_filter 就能在反向代理层把静态网页里某个功能模块“软下线”——比如隐藏试用入口、停用旧版聊天框、屏蔽促销横幅。核心是精准定位、安全替换、配置兜底。
锁定目标 HTML 片段要唯一且稳定
sub_filter 是纯字符串匹配，不是 DOM 解析器。它只认原始响应里的文本，所以必须确保你要下线的模块在 HTML 源码中以固定、可识别的方式存在：
- 最好由前端预先加上专属 ID 或 class，例如：
<div id="ai-assistant-v1" class="feature-beta"> - 避免用泛化词匹配（如只写“客服”或“立即开通”），否则可能误删文案、按钮文字甚至 JSON 字符串里的字段
- 确认该模块是服务端直出的 HTML，而非 JS 动态插入——sub_filter 对后者完全无效
- 若页面含多个同类模块（如多处“分享按钮”），需开启
sub_filter_once off才能全部处理
替换方式推荐注释或 display:none 占位
直接删标签风险高：容易破坏 HTML 结构（比如漏掉闭合标签）、引发 CSS 选择器错乱、或让依赖它的 JS 报错。稳妥做法是“视觉隐藏+语义保留”：
- 替换成 HTML 注释：
sub_filter '<section id="promo-banner">' '<!-- [OFFLINE] promo-banner hidden -->'; - 或加样式隐藏并保留容器结构：
sub_filter '<div class="trial-cta">' '<div class="trial-cta disabled" style="display:none;">'; - 若模块含内联脚本，建议整体注释掉
<script>...</script>，注意不要让脚本内的</script>提前终止替换
关键配置项一个都不能少
sub_filter 默认不生效，以下几项必须显式设置，缺一不可：
-
sub_filter_types text/html;—— 明确声明只处理 HTML；如需同时处理 CSS/JS，追加text/css application/javascript -
gunzip on;或proxy_set_header Accept-Encoding "";—— 确保响应未被压缩，否则 sub_filter 读不到明文 -
sub_filter_once off;—— 启用全量替换（默认只换第一个） -
sub_filter_last_modified off;—— 防止后端返回的 Last-Modified 头干扰替换逻辑（尤其在有缓存时）
上线前务必灰度验证
替换看似简单，但实际容易因边界问题失效：
- 用
curl -H "Accept: text/html" http://your-domain/page.html直接抓取原始响应，确认目标字符串确实存在且格式一致 - 检查响应头是否含
Content-Type: text/html，且无Content-Encoding: gzip - 先在小流量路径（如
/test/）或特定 User-Agent 下启用，观察控制台报错、布局异常、功能残留等情况 - 特别留意 CSS 中的
display: none是否被更高优先级规则覆盖，必要时加!important或换用注释方案
