Nginx 通过 sub_filter_once off 配合 sub_filter 在 text/html 响应中零侵入注入监控脚本，需禁用 gzip 或启用 gunzip、设置 sub_filter_types、选用稳定锚点（如）并注意 Content-Type 格式。
使用 Nginx 的 sub_filter_once 指令在 HTML 响应中注入前端监控脚本，是一种典型的“零侵入”埋点方式——无需修改业务代码、不依赖构建流程、不改动前端资源，所有注入由反向代理层完成。
理解 sub_filter_once 的作用范围
sub_filter_once 控制 Nginx 的 sub_filter 模块是否只替换每个匹配项的第一次出现（on）或全部出现（off）。在注入监控脚本时，通常设为 off，但关键在于：它仅对响应体中**明确匹配的字符串**生效，且默认只处理 text/html 类型响应。因此必须确保：
- 后端返回的 HTML 响应头包含
Content-Type: text/html（不含 charset 参数干扰） - 目标插入位置存在稳定、可识别的锚点，例如
或 - 启用
sub_filter时同时开启sub_filter_last_modified off（避免缓存校验失败）
安全注入监控脚本的典型配置
以下为生产可用的 Nginx 片段，将监控 SDK 脚本插入到 前（推荐位置，保证早执行）：
location / {
proxy_pass http://backend;
proxy_set_header Host $host;
<pre class="brush:php;toolbar:false;"># 启用 sub_filter 并允许多次替换
sub_filter '' '<script src="/js/monitor.min.js" async></script>';
sub_filter_once off;
sub_filter_last_modified off;
# 必须设置，否则 sub_filter 不生效
sub_filter_types text/html;
proxy_set_header Accept-Encoding "";
proxy_http_version 1.1;
proxy_set_header Connection '';}
将一个或多个 UI 原型图、线框图、产品截图或设计稿转换为标准化、可直接交付的 PRD 风格文档，供产品、设计、前端和测试共同使用。适用于 Codex 需要分析 PC 网页、桌面端、移动端、响应式页面、独立弹窗、表单、表格、看板、数据大屏或多页面流程截图，还原页面结构与交互，强制套用固定文档模板，抽取跨页面共享规则，或把一组原型沉淀为单页规范文档加整体业务流程文档的场景。不适用于纯视觉审美点评、代码实现、接口设计、埋点方案、竞品分析或无 UI 输入的业务需求创作。
注意：proxy_set_header Accept-Encoding "" 是关键——禁用 gzip 可避免 Nginx 对压缩响应体跳过 sub_filter；若需保留压缩，需搭配 gunzip on（要求 Nginx 编译含 gunzip 模块）。
规避常见陷阱与增强健壮性
纯字符串替换易受 HTML 格式变化影响（如换行、空格、注释）。提升鲁棒性的实用做法：
- 锚点尽量选闭合标签（如
），避免开标签（如）导致误插在注释或属性中 - 监控脚本自身使用 IIFE 封装，避免变量污染，并内置错误捕获（
window.onerror、Promise.catch） - 通过
sub_filter注入 base64 编码的内联脚本（规避外链加载失败），例如：sub_filter '' '<script>eval(atob("ZnVuY3Rpb24gcmVwb3J0KCkge30K"))</script>'; - 对多环境差异化注入，可用 map 指令控制：
map $host $monitor_js { ~dev\. example\.com "/js/monitor-dev.min.js"; default "/js/monitor.min.js"; }，再在 sub_filter 中引用$monitor_js
验证与灰度上线建议
注入行为不可见于源码，需主动验证：
- 用
curl -H "Accept-Encoding:" http://yoursite/ | grep monitor检查响应体是否含脚本 - 浏览器开发者工具中查看 Network → HTML 响应的 Preview/Raw，确认插入位置准确
- 首次上线建议配合 Nginx 变量控制开关（如
if ($arg_monitor = "1") { ... }），通过 URL 参数灰度开启 - 监控脚本内记录日志时带上
inject: nginx字段，便于后端区分埋点来源
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
