Nginx的sub_filter模块支持对响应体进行静态字面量字符串替换，仅作用于text/html等明文类型，默认不处理二进制、gzip压缩或chunked响应，且不支持正则、变量或条件逻辑。
Nginx 的 sub_filter 模块可用于在响应返回给客户端前，对 HTML 内容做简单字符串替换，常被用来动态修正前端资源（如 JS、CSS、图片）的绝对路径，从而避免因部署环境不同（如开发 / 测试 / 生产，或子路径部署如 /app/）导致资源 404。但它有明确限制：只作用于文本响应（默认仅 text/html），不处理二进制内容，且不支持正则捕获重用，替换是静态、逐字匹配的。
启用 sub_filter 并设置基础替换规则
确保 Nginx 已编译启用 ngx_http_sub_module（主流发行版通常默认开启）。在对应 server 或 location 块中配置：
- 用
sub_filter定义要查找和替换的字符串，例如将硬编码的https://dev.example.com/static/替换为相对路径或当前域名路径 - 必须搭配
sub_filter_once off才能全局替换（默认只替换第一个匹配项） - 添加
sub_filter_types text/html application/xhtml+xml;可扩展支持 XHTML 等类型（如有需要） - 注意：替换后响应体长度可能变化，需显式关闭缓存并设置
sub_filter_last_modified off防止 ETag 或 Last-Modified 失效
适配子路径部署（如 /admin/ 或 /v2/）
当前端打包为子路径（如 publicPath: '/admin/'），但 Nginx 实际代理到根路径时，HTML 中的 src="/admin/app.js" 会 404。此时可让 sub_filter 去掉前缀：
HISUI 前端框架开发指南（IRIS版）
下载
HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。
- 若后端返回的 HTML 含
src="/admin/static/js/app.js"，配置sub_filter '/admin/' '/'; - 更安全的做法是加边界符，如
sub_filter 'src="/admin/' 'src="/';，避免误替换其他含/admin/的字符串 - 同理处理
href、data-src等属性，必要时多条sub_filter规则叠加
按 Host 或请求头动态切换替换逻辑
sub_filter 本身不支持变量，但可通过 map + set + if（谨慎使用）间接实现环境感知：
立即学习“前端免费学习笔记（深入）”；
- 先用
map $host $origin_replacement定义不同域名对应的替换目标，如dev.example.com → "https://dev-api.example.com" - 在 location 中用
set $sub_from "..."; set $sub_to "...";构造变量值（注意：sub_filter不接受变量，此步仅作说明；实际仍需静态规则） - 真正可行的是：为不同环境配置独立的 server 块，每个块内写死对应的
sub_filter规则，由 SNI 或反向代理路由分发 - 若必须单配置多环境，可结合 Lua 模块（如
ngx_lua）做动态过滤，但已超出纯sub_filter范畴
注意事项与常见陷阱
该方案轻量但脆弱，上线前务必验证：
-
sub_filter不修改 HTTP 响应头中的Content-Length，若启用 gzip，需先解压再替换，再压缩——必须配置sub_filter在 gzip 模块之后生效（即 gzip off，或确保gzip_vary off且响应未被压缩缓存） - 避免替换 URL 中的协议部分（如
http://→https://），易引发跨域或混合内容问题；优先用协议相对路径//example.com/xxx或相对路径 - 不要依赖它修复大量或嵌套路径，如
/api/v1/users和/api/v2/posts共存时，简单替换/api/会出错 - 现代前端构建工具（Webpack/Vite）支持运行时 publicPath 配置或环境变量注入，比 Nginx 层替换更可靠，
sub_filter更适合作为兜底或遗留系统改造手段
