sub_filter 不能直接替换 HTML 中的 标签，因为默认启用 gzip 压缩导致响应体被压缩，sub_filter 无法匹配明文字符串；必须禁用 gzip（gzip off）或启用解压（gunzip on），并配置 sub_filter_types text/html; 和 sub_filter_once off; 才能可靠注入。
sub_filter 为什么不能直接替换 HTML 中的
因为 sub_filter 默认只处理响应体中「已缓冲完成」的 chunk，而 Nginx 默认对 HTML 响应启用 gzip 压缩，导致原始文本被压缩后无法匹配明文字符串（比如 ），替换直接失效。这不是配置写错了，是压缩和过滤的执行顺序冲突。
- 必须在
sub_filter生效前禁用 gzip：在 location 块里加gzip off; - 若后端已返回 gzip 内容（如 Node.js/Java 应用主动压缩），还需加
gunzip on;让 Nginx 先解压再过滤 -
sub_filter_once off;才能确保多次注入（比如多个页面含多个）
如何安全注入监控脚本而不破坏原有 HTML 结构？
直接把 <script src="..."></script> 插到 开头或结尾都可能引发问题：有些前端框架依赖 <meta charset> 必须靠前，有些监控 SDK 要求 DOM 尚未渲染就加载。稳妥做法是插在 的末尾、所有其他标签之后。
- 匹配模式用正则更可靠：
sub_filter '' '<script src="/js/monitor.js"></script>'; - 务必开启
sub_filter_types text/html;，否则对Content-Type: text/html; charset=utf-8这类带参数的类型不生效 - 如果页面有 CSP 头限制内联脚本，
sub_filter注入的外链 script 一般不受影响，但需确认 CSP 的script-src是否放行了你的域名
为什么本地测试正常，上线后部分页面没注入？
常见原因是响应头中存在 Content-Encoding: br（Brotli 压缩）或 Content-Encoding: gzip，而 Nginx 的 sub_filter 不支持直接处理 Brotli，且默认不自动解压 Brotli 编码内容。
- 检查响应头：
curl -I https://yoursite.com/看是否含br或gzip - 若用 Brotli，Nginx 需要
ngx_http_brotli_filter_module模块 + 手动启用brotli off;（无内置brotili on;解压指令，只能关掉 Brotli 输出） - 更通用的兜底方案：让后端关闭压缩，或统一由 Nginx 做 gzip（并配
gunzip on;）
监控脚本加载失败时，有没有 fallback 或日志手段？
sub_filter 本身不提供加载反馈机制，但可以通过组合手段暴露问题：
立即学习“前端免费学习笔记（深入）”；
- 在注入的脚本 URL 后加版本参数（如
/js/monitor.js?v=20240615），配合 CDN 缓存刷新，避免旧缓存干扰 - 监控脚本自身加简单错误捕获：
const s = document.createElement('script'); s.onerror = () => console.warn('monitor.js load failed'); s.src = '/js/monitor.js'; document.head.appendChild(s); - Nginx access log 可记录注入行为是否触发：用
log_format加$sent_http_content_length和$upstream_http_content_length对比，异常变小说明替换出错
真正难调试的是「替换发生了，但脚本没执行」——比如页面用了 strict-dynamic CSP 或提前调用了 document.write，这时候 sub_filter 已经无能为力，得靠前端运行时检测补位。
