如何通过 sub_filter 实现 HTML 静态页面内容的动态实时替换-Nginx-PHP中文网

sub_filter 是 Nginx 的流式文本替换模块，仅支持字面量匹配、不解析 HTML、不支持正则；需启用 http_sub_module，配合 sub_filter_once off 实现全局替换，并通过 sub_filter_types 显式指定 MIME 类型。

如何通过 sub_filter 实现 html 静态页面内容的动态实时替换

sub_filter 是 Nginx 提供的一个模块（需启用 ngx_http_sub_module），它能在响应返回给客户端前，对 HTML 内容做**流式、单向、正则无关**的字符串替换。它不解析 HTML 结构，也不执行 JavaScript，但胜在轻量、低延迟、无需后端参与——特别适合静态页面中嵌入环境变量、CDN 地址、版本号、灰度标识等简单动态内容。

启用 sub_filter 并配置基础替换

确保 Nginx 编译时已包含 --with-http_sub_module（主流发行版预编译包通常默认启用）。在 location 块中使用 sub_filter 指令：

每条 sub_filter 指令匹配并替换一次（按书写顺序执行，不支持全局多匹配）
必须配合 sub_filter_once off 才能替换页面中所有匹配项（默认为 on，只换第一个）
sub_filter_types 指定生效的 MIME 类型，默认仅 text/html；若需处理 .js 或 .css 中的内容，需显式添加

示例：将静态页中的 API_BASE_URL 替换为实际地址

location / {
    alias /var/www/static/;
    index index.html;

    sub_filter 'API_BASE_URL' 'https://api-prod.example.com';
    sub_filter_once off;
    sub_filter_types text/html application/javascript text/css;
}

实现多环境差异化输出（如 dev/staging/prod）

利用 Nginx 变量 + map 模块可实现运行时环境感知，避免为每个环境部署不同 HTML 文件：

先用 map 定义变量映射（放在 http 块中）
再在 location 中引用该变量做 sub_filter 替换

示例：

Html2md

使用 Readability + Turndown 将 HTML 页面转换为干净的、Agent 友好的 Markdown。去除导航栏、广告、页脚、Cookie 横幅、社交按钮等干扰元素。支持 URL...

下载

http {
    map $host $api_url {
        ~dev\.example\.com    https://api-dev.example.com;
        ~staging\.example\.com https://api-staging.example.com;
        default                https://api-prod.example.com;
    }
}

server {
    location / {
        alias /var/www/static/;
        sub_filter 'API_BASE_URL' $api_url;
        sub_filter_once off;
        sub_filter_types text/html;
    }
}

注意边界与限制：哪些不能靠 sub_filter 解决

sub_filter 是纯文本流式替换，有明确能力边界：

不支持正则表达式（仅字面量匹配），无法处理“匹配 class='btn-*'”这类需求
不解析 HTML DOM，无法保证只替换标签内文本而避开属性值（例如同时出现在 href 和文本中时会一并替换）
不支持条件逻辑（如“仅当存在 data-env=‘prod’ 时才替换”）
不支持嵌套或递归替换（如替换后的结果不会再被后续 sub_filter 处理）
若原始 HTML 被 gzip 压缩，sub_filter 默认失效 —— 需搭配 sub_filter 与 gzip off，或启用 gzip_static + sub_filter（较复杂，建议直接禁用响应压缩用于替换路径）

进阶技巧：组合 use case 实践

真实场景常需多个替换协同工作，例如注入版本号 + CDN 域名 + 跟踪 ID：

统一用占位符命名规范（如 %%ASSET_CDN%%、%%APP_VERSION%%），避免歧义
按依赖顺序书写 sub_filter（例如先换 CDN 域名，再换带该域名的完整 URL）
对敏感替换（如 token、密钥），确保只在可信内网路径启用，且禁止被爬虫或外部缓存命中
可结合 Nginx 的 add_header 插入自定义响应头（如 X-Subfilter-Applied: true），便于前端或监控识别是否走替换流程

示例片段：

sub_filter '%%ASSET_CDN%%' 'https://cdn.example.com';
sub_filter '%%APP_VERSION%%' 'v2.4.1';
sub_filter '%%TRACKING_ID%%' 'UA-123456789-1';
sub_filter_once off;

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索前端的入门与实战技巧！