sub_filter 是 Nginx 代理层对文本响应实时字符串替换的轻量级方案，需显式开启、配置类型、禁用 gzip 并谨慎设计替换模式以保障安全与性能。
sub_filter 指令可在 Nginx 代理层对后端返回的 HTML、CSS、JS 等文本响应内容进行实时字符串替换，是实现 CDN 链接动态注入或修正的轻量级方案。它不依赖后端修改，适合灰度切换、多环境适配或遗留系统加速改造。
启用 sub_filter 并确保生效前提
sub_filter 默认仅作用于 text/html 响应，且默认不启用缓冲替换（即只处理已缓存的完整响应）。需显式配置以下关键项：
- 开启 sub_filter：设置要替换的原始字符串和目标字符串，如
sub_filter "https://origin.example.com/" "https://cdn.example.com/"; - 启用 sub_filter_once off：允许多次匹配替换（默认只替换第一个匹配项）
- 设置 sub_filter_types：显式声明需处理的 MIME 类型，例如
sub_filter_types text/html text/css application/javascript; - 确保响应未被压缩（gzip）：sub_filter 不处理 gzip 编码内容，需在 location 中加
gzip off;或前置解压（需 ngx_http_gunzip_module）
安全替换 URL：避免误伤与路径冲突
直接全局替换域名易引发问题（如替换 JSON 字符串中的字段名、注释里的示例链接）。推荐采用更精准的模式：
- 用相对路径锚定：替换
src="/static/→src="https://cdn.example.com/static/，比替换整个域名更可控 - 限定上下文：配合正则风格写法（Nginx 1.19+ 支持
sub_filter的正则变体sub_filter_regex），例如只替换<img src="...">中的路径 - 区分协议与路径：对 HTTP/HTTPS 混合场景，可先统一转为协议相对 URL（
//cdn.example.com/...），再由浏览器自动适配
结合变量实现多环境动态 CDN 域名
通过 Nginx 变量 + map 指令，可按请求来源、Host 或参数动态选择 CDN 域名：
- 定义映射关系：
map $host $cdn_domain { example.com "cdn-prod.example.com"; test.example.com "cdn-staging.example.com"; default "cdn-dev.example.com"; } - 在 location 中引用：
sub_filter "https://origin.example.com/" "https://$cdn_domain/"; - 注意：变量值必须在 sub_filter 执行时已确定，建议放在 server 或 location 块顶层，避免嵌套延迟求值
调试与限制注意事项
sub_filter 是简单字符串替换，不具备 HTML 解析能力，使用中需主动规避其局限性：
- 不支持跨标签替换（如把
<link href="a.css">和后续<script src="a.js"></script>中的公共路径合并处理） - 响应体过大时性能下降明显——建议配合
sub_filter_last_modified on;减少重复处理，或仅对特定路径（如 /assets/）启用 - 调试技巧：临时加
add_header X-Subfilter-Status "active";，并用 curl -I 验证是否命中；开启error_log /path/to/log debug;查看 sub_filter 匹配日志（需编译含 debug 日志支持）
