Nginx 透传或生成链路追踪 ID 的关键是确保上游服务收到且值一致：优先透传客户端携带的 X-Trace-ID 或 W3C 标准 traceparent/tracestate；若无则可选 $request_id 补充；需在 proxy_pass 前用 proxy_set_header 设置，并注意变量命名（如 $http_x_trace_id）和 header 覆盖问题。
在 Nginx 中使用 proxy_set_header 传递自定义链路追踪 ID（如 X-Request-ID、Traceparent 或业务自定义的 X-Trace-ID），核心是：**确保上游服务能收到该 header，且该值在请求生命周期中保持一致（尤其跨代理时）**。
确认或生成链路 ID
Nginx 本身不生成分布式追踪 ID，需依赖外部注入或简单生成：
- 若上游（如网关或客户端）已携带（例如
X-Trace-ID），直接透传即可； - 若需 Nginx 自动生成（仅适用于非生产调试或简单场景），可用
$request_id变量（Nginx 内置，每个请求唯一，格式类似1a2b3c4d5e6f7g8h）； - 更严谨的做法是让前端或入口网关生成符合 W3C Trace Context 标准的
traceparent（如00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01），Nginx 只负责透传。
在 proxy\_pass 前设置 header
在 location 或 server 块中，于 proxy_pass 指令前使用 proxy_set_header：
location /api/ {
# 透传客户端带的 X-Trace-ID
proxy_set_header X-Trace-ID $http_x_trace_id;
<pre class="brush:php;toolbar:false;"># 若客户端没带，用 Nginx 自带 request_id 补充（可选）
proxy_set_header X-Trace-ID $request_id;
# 透传 W3C 标准字段（推荐用于 OpenTelemetry / Jaeger / SkyWalking）
proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;
# 必须设置 Host，否则上游可能无法路由
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://backend;}
注意：$http_x_trace_id 是 Nginx 自动将请求头 X-Trace-ID 映射成的变量（小写 + 下划线）；同理 $http_traceparent 对应 traceparent 请求头。
避免 header 被忽略或覆盖
Nginx 默认不会转发部分“不安全”或特殊 header（如以 Proxy-、Connection 开头的），但 X-* 和小写字母开头的（如 traceparent）默认可传。需检查：
- 确认没有其他
proxy_set_header重复设置同一 header 导致覆盖； - 若用了
underscores_in_headers on;，确保客户端 header 名不含下划线（Nginx 默认忽略含下划线的 header，除非开启该配置）； - 不要在
http块顶层大量设置proxy_set_header，易被子块继承覆盖，建议在具体location中明确控制。
验证是否生效
最直接方式：在上游服务（如一个简单的 Node.js/Python 接口）中打印所有请求 header，检查对应字段是否存在且值正确；也可用 curl -H "X-Trace-ID: abc123" http://nginx-host/api/test 手动测试透传效果。
不复杂但容易忽略的是 header 名大小写和变量命名规则 —— Nginx 对请求头的映射是自动转为小写下划线格式，写错变量名会导致传空值。
