Nginx可通过ngx_http_sub_module模块在HTML响应中自动注入前端监控探针脚本，需启用模块、配置sub_filter规则、处理gzip压缩、限定作用范围、支持环境变量动态注入，并验证效果及规避CSP等陷阱。
可以通过 Nginx 的 ngx_http_sub_module 模块，在响应 HTML 页面时，将前端监控探针脚本（如 Sentry、Datadog RUM、或自研埋点 SDK）自动插入到页面中，无需修改源站代码，实现统一、可控的探针注入。
确认模块已启用并配置基础替换规则
Nginx 默认不编译此模块，需确认启动时包含 --with-http_sub_module。可通过 nginx -V 2>&1 | grep -o with-http_sub_module 验证。启用后，在 location 块中使用 sub_filter 实现文本替换：
- 常用做法是将探针脚本插入到
</head>前，例如：sub_filter '</head>' '<script src="/probe.js"></script></head>'; - 必须开启
sub_filter_once off;才能对整个响应体多次匹配（否则只替换第一个</head>） - 需设置
sub_filter_types text/html;显式声明作用 MIME 类型（默认仅text/html） - 若上游返回压缩内容（gzip），需先解压再替换：添加
proxy_buffering on;和gunzip on;（要求启用ngx_http_gunzip_module）
避免污染非 HTML 资源与敏感路径
不应无差别对所有响应注入脚本，需精准控制作用范围：
前端设计优化skill
下载
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
- 用
location ~ \.html$或location /配合if ($sent_http_content_type ~ "text/html")限定仅处理 HTML 响应 - 排除静态资源目录（如
/static/、/assets/）、API 接口（/api/、/health）等非页面路径，防止脚本误注入 JSON 或 JS 文件造成解析错误 - 可结合
map指令定义白名单 host 或 path，按环境差异化注入（如仅prod.example.com注入探针，预发环境跳过）
支持动态参数与环境感知注入
纯静态脚本无法满足多环境（dev/staging/prod）、多项目隔离需求。可通过 Nginx 变量实现上下文感知：
立即学习“前端免费学习笔记（深入）”；
- 利用
$host、$request_uri或自定义请求头（如$http_x_env）拼接探针 URL 参数：sub_filter '</head>' '<script src="/probe.js?env=$host&path=$request_uri"></script></head>'; - 使用
map提前映射环境标识：map $host $probe_env { dev.example.com "dev"; staging.example.com "staging"; default "prod"; }
再在 sub_filter 中引用$probe_env - 注意：sub_filter 不支持变量嵌套或条件逻辑，所有变量需在 sub_filter 执行前已解析完成；复杂逻辑建议交由后端或边缘计算（如 NJS）处理
验证效果与规避常见陷阱
注入后务必验证是否生效且不影响页面功能：
- 用
curl -sI http://your-site/ | grep Content-Encoding确认响应未被 gzip（否则 sub_filter 失效）；若需压缩，确保启用gunzip on并测试解压后替换是否正常 - 检查浏览器开发者工具的 Network → Response，确认 HTML 源码中已出现探针 script 标签；同时查看 Console 是否有加载错误（如 404、CSP 拦截）
- CSP（Content-Security-Policy）头可能阻止内联或外部脚本执行，需同步更新策略：
add_header Content-Security-Policy "script-src 'self' https://cdn.example.com;"; - 避免重复注入：若页面本身已含探针，可配合
sub_filter '<script src="/probe.js">' '';先清除旧版本，再插入新版本
