nginx透传灰度标签需用proxy_set_header显式转发，头名须用短横线（如x-gray-tag）或启用underscores_in_headers on；必须置于proxy_pass前，支持$http_x_gray_tag变量透传、map动态路由及x-real-ip等上下文头保留。

要在 Nginx 代理中透传自定义的 Web 前端灰度测试路由标签（比如 X-Gray-Tag、X-Route-Tag），核心是用 proxy_set_header 显式转发，且必须确保头名合法、位置正确、值可控。

确保 header 名称合规，避免被丢弃

Nginx 默认会忽略含下划线（_）的请求头，例如 X_Gray_Tag 或 X_Route_Tag。这类头会被静默丢弃，后端收不到。

• 推荐统一使用短横线命名，如 X-Gray-Tag 或 X-Route-Tag，无需额外配置
• 若必须用下划线命名，需在 http 或 server 块顶部启用：
  underscores_in_headers on;
• 确认上级作用域未设为 off，否则该指令无效

在 proxy_pass 前设置 proxy_set_header

该指令必须出现在 proxy_pass 之前，否则不生效；同一 location 内多次设置同名 header，仅最后一条生效。

前端设计优化skill

前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。

下载

• ✅ 正确写法（透传客户端原始值）：
  proxy_set_header X-Gray-Tag $http_x_gray_tag;
• ✅ 固定值注入（全量切流）：
  proxy_set_header X-Gray-Tag "v2";
• ✅ 同时透传多个标识：
  

  proxy_set_header X-Route-Tag $http_x_route_tag;<br>proxy_set_header X-Region $http_x_region;

配合 map 实现动态路由 + 标签透传

单纯透传还不够，通常还需结合灰度路由逻辑——比如根据 header 选择 upstream，再把对应标签透传给后端。

• 先用 map 提前映射变量：
  

  map $http_x_gray_tag $upstream_backend {<br>  "v2" backend-canary;<br>  default backend-stable;<br>}

• 在 location 中使用：
  

  proxy_pass http://$upstream_backend;<br>proxy_set_header X-Gray-Tag $http_x_gray_tag;

• 这样既完成路由，又保证后端能拿到原始灰度标识，便于日志打标或特征识别

补充关键细节：保留原始请求上下文

灰度场景中，后端常需还原真实用户意图，不能只靠一个 tag。

• 默认已开启 proxy_pass_request_headers on，但建议显式保留关键头：
  

  proxy_set_header X-Real-IP $remote_addr;<br>proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

• 若前端通过 Cookie 打标（如 gray=1），可用 $cookie_gray 变量参与判断或透传：
  proxy_set_header X-Gray-Cookie $cookie_gray;
• 避免在 if 块里写 proxy_set_header，容易因作用域问题失效

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！