如何利用 sub_filter 在响应头中动态插入特定业务标识以辅助问题排查-Nginx-PHP中文网

sub_filter 不能修改响应头，因其仅作用于响应体；响应头在响应体生成前已封装完毕，sub_filter 完全无法触达。正确方式是用 add_header 或 more_set_headers 动态注入业务标识。

如何利用 sub_filter 在响应头中动态插入特定业务标识以辅助问题排查

sub_filter 不能用于修改响应头，它只作用于响应体（即 HTTP body）内容。若需在响应头中动态插入业务标识，应使用 add_header 或 more_set_headers（需安装 headers-more 模块），而非 sub_filter。

为什么 sub_filter 不适用于响应头

sub_filter 是 Nginx 的输出过滤模块，工作在内容编码之后、发送给客户端之前，仅对响应体中的文本进行查找替换。HTTP 响应头在响应体生成前已封装完毕，sub_filter 完全无法触达或修改 header 字段。

常见误解是试图用类似写法实现头注入：

错误示例（无效）：

sub_filter 'X-App-Version:.*' 'X-App-Version: v1.2.3';<br>sub_filter_once on;

这段配置不会生效——因为 sub_filter 根本不处理响应头行。

正确方式：用 add_header 动态添加业务标识

若业务标识是静态值（如固定服务名、环境标签），直接使用 add_header 即可：

add_header X-Biz-Id "order-service-prod";
add_header X-Request-Trace-ID $request_id;（依赖内置变量）
add_header X-Cluster-Name $hostname;

注意：add_header 只在响应状态码为 2xx 或 3xx 时生效，且会覆盖同名已有头（除非配置 multiple headers）。

进阶方案：基于变量或条件动态设置头

若需根据请求路径、参数或上游响应动态生成标识，推荐组合使用：

map 指令预定义变量：例如按 location 或 host 映射业务域
proxy_pass + proxy_hide_header 配合 add_header：隐藏上游头，统一注入自定义标识
headers-more 模块的 more_set_headers：支持 if 条件判断，比原生 add_header 更灵活（如：more_set_headers 'X-Biz-Tag: $my_biz_tag' if=$is_api;）

示例（基于 path 设置业务标识）：

map $uri $biz_tag {<br>  ~^/api/v1/orders/  "orders-v1";<br>  ~^/api/v1/pay/    "payment-v1";<br>  default  "unknown";<br>}<br>add_header X-Biz-Tag $biz_tag;