如何利用 sub_filter 指令实现在网关层动态注入反代环境专用的前端脚本-Nginx-PHP中文网

sub_filter是最轻量、无需修改源站代码的前端脚本注入方案，适用于灰度、SaaS、测试标识等场景；需确保响应为text/html、禁用gzip、启用sub_filter_once off，并在或前安全注入，配合map按环境动态注入脚本。

如何利用 sub_filter 指令实现在网关层动态注入反代环境专用的前端脚本

在 Nginx 反向代理网关层动态注入前端脚本，sub_filter 是最轻量、无需修改源站代码的方案之一。它适用于灰度环境、多租户 SaaS、测试环境标识、埋点脚本差异化注入等场景。关键在于精准匹配 HTML 响应体、避免污染非文本内容，并处理好替换顺序与缓存干扰。

确保 sub_filter 生效的基础条件

sub_filter 默认只作用于 text/html 类型响应，且要求响应未被压缩（gzip/brotli 会破坏文本匹配）。需确认以下几点：

后端返回的 Content-Type 包含 text/html（如 text/html; charset=utf-8）
关闭 Nginx 对该 location 的 gzip on 或显式禁用：gzip off;
启用 sub_filter_once off（默认为 on），否则只替换第一个匹配项
开启 sub_filter_last_modified off（若需支持缓存协商，但通常建议关闭以避免干扰）

在或前安全注入脚本

推荐将脚本插入闭合标签前，避免阻塞渲染；或插入前，确保 DOM 已加载。注意：HTML 中可能有空格、换行或注释干扰匹配，建议用宽松正则 + 多次替换策略：

location / {
    proxy_pass https://www.php.cn/link/d1fe9485be324217b5d180d04dfcb87f;
    proxy_set_header Host $host;
<pre class="brush:php;toolbar:false;"># 匹配 /head>（兼容大小写、前后空格、可选换行）
sub_filter '' '<script type="text/javascript" src="/js/gateway-env.js"></script>';
sub_filter '' '<script type="text/javascript" src="/js/gateway-env.js"></script>';
sub_filter_once off;
sub_filter_types text/html;
gzip off;

}

更健壮的做法是用 sub_filter 配合 sub_filter_last_modified off 和 sub_filter_recursive on（Nginx 1.19.5+ 支持），实现嵌套替换；若版本较低，可用两个 sub_filter 指令分步处理（如先清理多余空白再替换）。

HISUI 前端框架开发指南（IRIS版）

HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。

下载

按环境变量动态注入不同脚本

单纯静态替换无法满足多环境需求。可通过 map 指令将请求头、域名或路径映射为变量，再结合 sub_filter 实现条件注入：

map $host $env_script {
    ~^staging\. example\.com$ "/js/staging.js";
    ~^dev\.example\.com$     "/js/dev.js";
    default                 "/js/prod.js";
}
<p>server {
location / {
proxy_pass <a href="https://www.php.cn/link/d1fe9485be324217b5d180d04dfcb87f">https://www.php.cn/link/d1fe9485be324217b5d180d04dfcb87f</a>;
sub_filter '' '<script src="%24env_script"></script>';
sub_filter_once off;
sub_filter_types text/html;
gzip off;
}
}</p>

注意：sub_filter 不直接支持变量插值（旧版 Nginx），上述写法需 Nginx ≥ 1.17.3 且开启 sub_filter 的变量支持（部分发行版需编译时启用 --with-http_sub_module 并确认支持变量）。更兼容的方式是用 add_header 注入自定义 HTTP 头，再由前端 JS 读取并动态加载对应脚本。

规避常见陷阱与增强可靠性

实际部署中易出现脚本重复注入、替换失败、JS 执行报错等问题，需针对性防护：

防重复注入：在注入脚本内加 guard 判断，例如 if (window.__GATEWAY_INJECTED) return;，并在开头设 window.__GATEWAY_INJECTED = true;
防替换污染：限定 sub_filter_types 仅 text/html，避免误改 JSON、CSS 或 JS 文件（即使它们被错误标记为 html）
支持 UTF-8 特殊字符：确保 Nginx 编译时启用了 PCRE UTF-8 支持，并在配置中添加 charset utf-8;
调试技巧：临时开启 error_log /var/log/nginx/subfilter.log debug;，配合 curl -H "Accept-Encoding: identity" http://gateway/ 查看原始响应是否被正确匹配替换