Nginx 缓存分发层可通过 sub_filter_once off 配合 sub_filter 实现 HTML 响应体精准脚本注入，需确保响应类型为 text/html、禁用 gzip 或适配压缩、锚点唯一且仅注入一次，并通过 map 动态控制、header 注入上下文、日志监控及灰度验证保障可靠性。
在 Nginx 缓存分发层（如 CDN 边缘节点或反向代理网关）中，通过 sub_filter_once off 配合 sub_filter，可实现对 HTML 响应体的精准、低侵入式脚本注入，适用于全局埋点、性能监控、错误捕获等业务场景。关键在于确保只在 HTML 类型响应中生效、避免重复注入、不影响原始缓存逻辑。
确认响应类型与编码兼容性
sub_filter 仅作用于 text/html、text/plain 等明文响应，且默认不处理 gzip 压缩内容。需确保：
- 后端返回的 HTML 响应头包含
Content-Type: text/html; charset=utf-8（charset 显式声明可避免乱码） - 在 sub_filter 前禁用 gzip 输出：
gzip off;，或启用sub_filter_types text/html application/xhtml+xml;并配合gzip_vary off;避免压缩干扰 - 若必须保留 gzip，需在上游服务侧解压，或改用 Lua 模块（如 lua-resty-html）做流式解析注入
精准定位注入位置并避免重复
使用 sub_filter_once off 可多次匹配替换，但业务脚本通常只需注入一次（如 前）。推荐策略：
- 匹配唯一锚点：例如
sub_filter '' '<script src="/js/monitor.js"></script>'; - 启用
sub_filter_once on;（默认值），确保只替换第一个匹配项，防止脚本被重复插入 - 若需更灵活控制（如跳过某些路径），可结合
map指令动态开关 sub_filter：map $request_uri $inject_monitor { ~^/api/ ""; # API 接口不注入 default "1"; } ... location / { sub_filter '</head>' '<script src="/js/monitor.js"></script></head>'; sub_filter_once on; sub_filter_last_modified off; sub_filter_types text/html; sub_filter 'X-Inject: $inject_monitor' 'X-Inject: $inject_monitor'; add_header X-Monitor-Injected $inject_monitor; }保障脚本加载可靠性与监控闭环
注入的监控脚本需独立部署、版本可控，并支持加载失败回退与上报：
- 脚本 URL 使用带哈希的静态资源路径（如
/js/monitor.v1.2.3.min.js），避免缓存 stale 问题 - 脚本内嵌轻量 loader，支持异步加载 + 超时 fallback（如降级为 beacon 上报）
- 在 Nginx 层补充关键上下文：通过
add_header注入边缘节点 ID、缓存状态（$upstream_cache_status）、地区标签等，供前端监控 SDK 采集 - 对注入行为本身做日志记录：
log_format inject '$remote_addr - $request_uri [$time_local] inject=$inject_monitor cache=$upstream_cache_status';
验证与灰度上线要点
注入逻辑上线前必须实测响应完整性与性能影响：
- 用 curl 检查原始 HTML 是否含
、是否被 gzip、是否有 BOM 或非 UTF-8 字符（会导致 sub_filter 失效） - 开启
sub_filter_last_modified off;防止因 Last-Modified 头导致替换后校验失败 - 灰度阶段：先对特定 User-Agent 或 Cookie 标识用户启用，再逐步扩大；监控 5xx/HTML 解析错误率、首屏时间变化
- 禁止在 POST/JSON 接口响应中误启 sub_filter——严格限定
sub_filter_types和 location 匹配范围
- 脚本 URL 使用带哈希的静态资源路径（如
