Nginx sub_filter 可在响应 HTML 前动态注入调试脚本，需满足：响应未压缩、Content-Type 为 text/html 或 application/xhtml+xml、启用 sub_filter_once off、在 location 中配置；推荐用 map 指令控制开关并以 HTML 注释为锚点提升稳定性。

可以通过 Nginx 的 sub_filter 指令，在响应 HTML 内容返回给客户端前，动态插入调试脚本（如 Sentry、React DevTools 注入逻辑、环境标识 banner 等），无需修改前端构建产物，特别适合灰度或生产环境快速启用/关闭前端调试能力。

确保 sub_filter 正常工作所需的前提条件

sub_filter 默认只对 text/html 响应生效，且要求响应体未被压缩（gzip / brotli 会破坏替换逻辑）。需确认以下几点：

前端开发

ys-agent 前端（frontend/）功能迭代的工程规范守门 skill。当任何 agent 接到 ys-agent 前端相关任务时——新增页面、新增组件、加 API、加 Pinia store、改路由、写 mock、调整布局、修改样式、对接后端接口、迁移 demo 代码、做主题、加权限、写公共组件、做数据可视化、做表单、做弹窗、做表格、做搜索过滤、调 Element Plus 用法、做响应式、做性能优化，或仅仅是在 frontend/ 目录下编辑任何 .vue / .ts / .scss / .c

下载

• 后端返回的 HTML 响应头中 Content-Encoding 为空（即未开启 gzip/brotli）；若必须压缩，可在 Nginx 中先解压再替换（需 ngx_http_substitutions_filter_module 扩展模块，非官方内置）
• 启用 sub_filter_once off，否则只替换第一个匹配项
• 使用 sub_filter_types text/html application/xhtml+xml 显式支持 XHTML 类型（如有需要）
• 确保 sub_filter 在 location 块中配置，且该 location 能实际代理到返回 HTML 的 upstream

注入调试脚本的典型配置示例

以下配置在