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";
- 注意：这些变量仅在模块启用且成功提取上下文时才有效，建议搭配
mapfallback 防空值
注意事项与常见陷阱
动态注入看似简单，但几个细节极易导致链路断裂或重复：
-
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，引发解析错误
