sub_filter 是 Nginx 的流式文本替换模块，仅支持字面量匹配、不解析 HTML、不支持正则；需启用 http_sub_module，配合 sub_filter_once off 实现全局替换，并通过 sub_filter_types 显式指定 MIME 类型。
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 文件：
立即学习“前端免费学习笔记（深入）”；
htmlppt.skill
下载
把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。
- 先用 map 定义变量映射（放在 http 块中）
- 再在 location 中引用该变量做 sub_filter 替换
示例：
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;
