sub_filter_once on 仅对未压缩的text/html响应体做一次字符串替换，适合在</head>前注入埋点脚本；需禁用gzip、规范HTML格式、避免误替换及流式响应场景。
使用 sub_filter_once on 可以在 Nginx 代理响应中**仅对 HTML 响应体做一次字符串替换**，适合轻量、确定位置的埋点脚本注入（如插入到 </head> 前）。但它不支持正则、不解析 HTML 结构、不处理压缩响应，需配合其他指令谨慎使用。
确保响应可被 sub_filter 处理
Nginx 的 sub_filter 默认只处理未压缩的文本响应。若后端返回 gzip 响应，sub_filter 会失效：
- 后端需关闭 gzip（推荐），或 Nginx 配置
gzip off;或gzip_disable "msie6";（慎用） - 确认响应 Content-Type 为
text/html，可通过sub_filter_types text/html;显式声明 - 避免与
proxy_buffering off冲突——缓冲关闭可能导致流式响应截断，影响替换
精准定位注入点（推荐 /head 前）
利用 sub_filter 将埋点脚本插入到 </head> 标签前是最稳定的方式，因该标签在 HTML 中通常唯一且位置靠前：
前端设计优化skill
下载
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
- 配置示例：
sub_filter '</head>' '<script src="/js/monitor.js"></script></head>';<br> sub_filter_once on;
- 注意：脚本路径需由 Nginx 静态服务（如
location /js/指向本地文件）或反向代理到监控服务 - 若 HTML 中存在空格或换行（如
</ head>、</head\n>），替换会失败——建议后端输出规范格式，或用多条sub_filter覆盖常见变体
规避常见陷阱
sub_filter_once 是简单替换，不是 DOM 操作，极易因 HTML 结构变化失效：
立即学习“前端免费学习笔记（深入）”；
- 不支持条件注入（如仅对生产环境注入）——需靠不同 location 或 map 变量控制是否启用
sub_filter - 若页面本身含
</head>字符串（如 JS 字符串字面量、注释、模板代码），会被误替换——务必检查源码，必要时改用更安全的注入方式（如服务端模板、构建时注入） - 无法处理 HTTP/2 Server Push 或流式 SSE 响应——这些场景下
sub_filter不生效 - 开启
sub_filter_once后，只替换第一个匹配项；若需全局替换（如多个 script 标签），需设为off并承担性能开销
替代方案对比（何时不该用 sub_filter_once）
当业务复杂度上升，sub_filter 很快会成为维护负担：
- 需要根据 URL、UA、Cookie 动态注入？→ 改用
map+add_header注入 HTTP 头，再由前端 JS 读取并加载脚本 - 需保证脚本在所有资源加载前执行？→ 使用
<script defer>或服务端渲染时内联关键监控逻辑 - 已有微前端或 CSR 应用，HTML 骨架极简？→ 在入口 HTML 模板中注入，或由主应用统一加载 SDK
- 要求高可靠性与调试能力？→ 直接在构建流程（Webpack/Vite 插件）中注入，而非依赖代理层
