Nginx sub_filter可在不修改源文件前提下向HTML注入统计脚本，需关闭gzip、匹配</head>插入、用变量控制环境、禁用ETag防缓存失效。
可以通过 Nginx 的 sub_filter 模块，在响应 HTML 内容时原地替换文本，从而在不修改源文件的前提下，向页面中注入全局统计脚本（如 Google Analytics、百度统计、自建埋点等）。关键在于精准匹配插入位置、避免重复注入、处理压缩与缓存问题。
确保 sub_filter 正常启用并配置基础规则
Nginx 默认编译时已包含 sub_filter 模块（无需额外加载），但需确认使用的是主干版或较新稳定版（1.1.6+），且未被禁用。在 location 块中启用：
- 开启输出过滤：
sub_filter_once off;（允许多次替换，适合注入多个脚本） - 设置字符集避免乱码：
sub_filter_types text/html;（必要时补充application/xhtml+xml） - 关闭 gzip 响应（或配合
gunzip on;）：因为sub_filter无法处理 gzip 压缩后的内容；若必须压缩，需在应用层或 CDN 层处理
选择安全可靠的注入位置
推荐将统计脚本插入到 </head> 前，兼顾执行时机与兼容性。例如：
前端设计优化skill
下载
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
- 匹配：
sub_filter '</head>' '<script src="/js/stat.js"></script></head>'; - 更健壮写法（防空格/换行干扰）：
sub_filter '</head>' '<script>window._statConfig={env:"prod"};</script><script src="/js/stat.js"></script></head>'; - 若 HTML 无
</head>（如 SSR 或模板缺失），可退而匹配<body>开头，但注意脚本需加defer或包裹在DOMContentLoaded
避免重复注入与跨环境污染
生产环境才注入，开发/测试环境应跳过：
立即学习“前端免费学习笔记（深入）”；
- 利用变量控制：
set $inject_stat "";+if ($host ~* "^(www\.)?example\.com$") { set $inject_stat "on"; } - 配合 map 模块更清晰：
map $host $should_inject { default ""; "~*example\.com" "1"; }，再用sub_filter配合if ($should_inject) { ... } - 对静态 HTML 文件（如
index.html）单独配置 location，避免对 API 或资源文件误触发
处理缓存与调试技巧
sub_filter 修改响应体后，ETag 和 Content-Length 会变化，可能破坏缓存一致性：
- 显式清除 ETag：
etag off; - 禁用响应头中的缓存校验字段（如
add_header Cache-Control "no-cache";仅用于调试） - 调试时开启日志：
error_log /var/log/nginx/subfilter.log notice;，并在配置中加sub_filter_last_modified off;避免时间戳干扰 - 用
curl -I查看响应头是否含Content-Encoding: gzip，若有则sub_filter必然失效
