Nginx中动态注入Request-ID需优先透传上游X-Request-ID，否则用内置$request_id；配合map实现fallback，再add_header注入；集成OpenTracing时可用$opentracing_trace_id等变量，并注意子请求、缓存、大小写及重复注入问题。

在 Nginx 中使用 add_header 动态注入分布式链路追踪的 Request-ID，关键在于：该 ID 必须在请求进入 Nginx 时就生成（或透传），且需确保每次请求唯一、可跨服务传递。Nginx 本身不内置链路 ID 生成器，因此需借助变量（如 $request_id 或自定义变量）配合模块实现。

启用并利用内置 $request_id 变量

Nginx 从 1.11.0 起原生支持 $request_id 变量，它会在每个请求初始化时自动生成一个 32 位随机十六进制字符串（例如 9e4d5a2b3c7f8a1e6d4b9c2f0a8e7d1b），无需额外模块，开箱即用。

• 确保 Nginx 版本 ≥ 1.11.0（推荐 ≥ 1.19.0 以获得更稳定行为）
• 在 server 或 location 块中直接使用：
  add_header X-Request-ID $request_id;
• 若上游服务（如后端 API）也依赖该 ID，需同时透传给后端：
  proxy_set_header X-Request-ID $request_id;

从上游透传已有 Request-ID（如来自网关或客户端）

在真实微服务链路中，Request-ID 通常由最外层网关（如 Kong、Spring Cloud Gateway）或前端 SDK 注入。此时应优先复用该 ID，而非覆盖重写。

• 用 map 指令定义安全的透传变量：
  

  map $http_x_request_id $trace_id {<br>  "" $request_id;<br>  default $http_x_request_id;<br>}

• 这样：若客户端/上游已带 X-Request-ID，则用它；否则 fallback 到 Nginx 自生成的 $request_id
• 再统一注入响应头：
  add_header X-Request-ID $trace_id;

结合 opentracing / nginx-opentracing 模块注入 TraceID/SpanID

若已集成 OpenTracing（如通过 nginx-opentracing 模块），可获取更丰富的链路上下文，如 trace_id 和 span_id。

• 安装并加载对应模块（如 Jaeger 或 Zipkin 的 Nginx 插件）
• 模块会暴露新变量，例如：$opentracing_trace_id、$opentracing_span_id
• 直接注入：
  

  add_header X-B3-TraceId $opentracing_trace_id;<br>add_header X-B3-SpanId $opentracing_span_id;<br>add_header X-B3-Sampled "1";

• 注意：这些变量仅在模块启用且成功提取上下文时才有效，建议搭配 map fallback 防空值

注意事项与常见陷阱

动态注入看似简单，但几个细节极易导致链路断裂或重复：

• add_header 不继承子请求：子请求（如 SSI、auth_request）默认不携带父请求头，需显式配置 include 或 proxy_pass_request_headers on
• 缓存场景下 header 可能被固化：若开启 proxy_cache，需在 cache key 中加入 $request_id 或禁用该资源缓存，避免不同请求返回相同 ID
• 大小写敏感：HTTP 头名是规范化的，X-Request-ID 和 x-request-id 在大多数系统中等价，但部分 APM 工具（如 Datadog）严格匹配首字母大写形式
• 避免重复注入：检查后端是否已输出同名 header，Nginx 默认不会覆盖，而是追加——这会导致响应头出现多个 X-Request-ID，引发解析错误