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="..." alt="如何利用 sub_filter 指令实现在代理层动态修正后端页面中的 CDN 资源加速链接" > 中的路径
• 区分协议与路径：对 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 日志支持）