如何利用 sub_filter_once 模式实现在静态网页中全局注入第三方动态统计代码-Nginx-PHP中文网

sub_filter_once off 实现全局替换，需配合 sub_filter_types text/html 和禁用 gzip；仅作用于 text/html 响应，不支持压缩内容直接处理，适用于静态 HTML 注入统计脚本。

如何利用 sub_filter_once 模式实现在静态网页中全局注入第三方动态统计代码

使用 sub_filter_once off（注意：Nginx 中实际指令为 sub_filter_once，值为 off 表示**多次替换**）配合 sub_filter，可以在 Nginx 代理静态 HTML 页面时，将第三方统计代码（如 GA4、百度统计、自建埋点脚本）注入到所有匹配位置（通常是或前），实现“全局无侵入式注入”。但需注意：这不是前端 JS 的动态执行，而是服务端响应阶段的文本替换，仅适用于 Nginx 作为反向代理或静态文件服务器的场景。

前提条件与限制

该方案依赖 Nginx 的 http_sub_module（通常需编译启用，主流发行版包默认包含）。关键约束包括：

只对 text/html 响应生效：需确保 sub_filter_types 包含 text/html，且后端返回的 Content-Type 正确；
不支持压缩内容直接替换：若开启 gzip 或 gzip_static，需先解压再替换（推荐关闭 gzip 代理静态 HTML，或用 gunzip on 配合）；
替换发生在响应体流式输出中：无法修改 HTTP 头部，也不能处理 chunked 编码下的边界问题；
不适用于 SPA 的客户端路由页：仅对 Nginx 实际读取并返回的 .html 文件有效，不处理 history 路由产生的虚拟路径。

基础配置示例（注入到前）

在 server 或 location 块中添加：

location / {
    alias /var/www/static/;
    try_files $uri $uri/ =404;
<pre class="brush:php;toolbar:false;"># 启用 sub_filter，允许多次替换（关键！）
sub_filter_once off;

# 指定可处理的 MIME 类型
sub_filter_types text/html;

# 替换：在  前插入统计代码（注意转义双引号和换行）
sub_filter '' '<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXX"></script>

⚠️ 注意：sub_filter 中的字符串必须严格匹配原始 HTML 中的文本（包括空格与大小写）。建议源 HTML 中单独成行、无多余空格，或使用更宽松的匹配（见下一条）。

提升兼容性：用正则风格的模糊匹配（需 Nginx ≥ 1.19.5 + --with-http-sub-module=dynamic）

新版 Nginx 支持 sub_filter 的正则语法（需显式启用），可缓解格式敏感问题：

# 启用 PCRE 正则支持（配置前确认模块可用）
sub_filter '[hH][eE][aA][dD]>' '<script>...</script>' i;
sub_filter_once off;
sub_filter_types text/html;

其中 i 标志表示忽略大小写，[hH][eE][aA][dD]> 可匹配、等变体。但注意：正则模式下 sub_filter_once off 仍控制是否全局替换所有匹配项。

安全与维护建议

避免注入未校验的远程脚本：优先使用内联代码或托管在自有域名下的统计 JS（如 /js/stat.js），防止因第三方不可用导致页面阻塞或 CSP 报错；
配合 CSP 头部：若注入外链脚本，需同步设置 add_header Content-Security-Policy "script-src 'self' https://www.googletagmanager.com;";；
禁用缓存干扰：确保被替换的 HTML 不被 CDN 或浏览器强缓存（可加 add_header Cache-Control "no-cache, no-store, must-revalidate"; 仅用于调试）；
测试替换效果：用 curl -H "Accept-Encoding: identity" http://yoursite/index.html 查看原始响应，确认注入位置准确、无 HTML 损坏。