Nginx用内置变量$request_id生成唯一32位十六进制请求ID并透传X-Request-ID头，轻量可靠；需在proxy_set_header中配置，并与后端日志、OpenTelemetry等协同实现全链路追踪闭环。
在微服务架构中，全链路追踪的关键之一是为每个请求生成唯一标识，并贯穿整个调用链。Nginx 作为最常用的边缘网关或反向代理层，天然适合承担“注入请求 ID”这一职责。利用内置变量 $request_id，无需额外模块或复杂配置，即可实现轻量、可靠、标准化的链路标识传递。
为什么用 $request_id 而不是自定义 header？
$request_id 是 Nginx 官方提供的内置变量（1.11.0+ 版本默认启用），在请求进入 worker 进程时自动生成一个 32 位十六进制字符串（如 e9a8b7c6d5f4a3b2c1e0f9d8a7b6c5d4），具备以下优势：
- 无需依赖第三方模块（如 ngx_http_random_index_module 或 Lua）
- 线程安全，每个请求独立生成，无冲突风险
- 格式统一、长度固定，便于日志解析与系统间对齐
- 即使后端服务未主动生成 traceId，Nginx 已兜底提供，避免空值断链
在 Nginx 中注入并透传 request_id 的标准写法
只需两步：在 proxy 请求头中添加 X-Request-ID，并确保后端能接收该 header。典型配置如下：
location /api/ {
# 启用 request_id（高版本默认开启，显式声明更清晰）
proxy_set_header X-Request-ID $request_id;
<pre class="brush:php;toolbar:false;"># 同时可透传给下游服务用于日志标记或 trace 上报
proxy_set_header X-Trace-ID $request_id;
# 其他常规代理设置
proxy_pass http://backend_cluster;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;}
注意：$request_id 在 Nginx 内部生命周期内始终有效，包括日志、proxy headers、map 指令等上下文，无需手动初始化。
与后端服务协同完成链路闭环
仅 Nginx 注入还不够，需后端服务配合消费并延续该 ID：
- Spring Cloud 项目可在
application.yml中配置logging.pattern.console，将%X{X-Request-ID:-}加入日志模板 - Go Gin 框架可通过中间件读取
c.Request.Header.Get("X-Request-ID")并注入 zap 日志字段 - 若使用 OpenTelemetry，可将
X-Request-ID映射为trace_id字段（需适配器逻辑，不直接等价但可作为 fallback） - 所有跨服务 HTTP 调用，务必在发起请求时将当前
X-Request-ID复制到下游 header 中
验证与排查技巧
快速确认是否生效，推荐组合使用 curl + Nginx 日志：
- 发起带调试头的请求：
curl -H "X-Debug: 1" http://gateway/api/users - 在 Nginx access_log 中加入
$request_id变量：log_format main '$request_id - $remote_addr - $request_time ...'; - 检查响应 header 是否返回：
curl -I http://gateway/api/users | grep "X-Request-ID" - 若后端日志未出现该 ID，优先排查是否禁用了 header 传递（如某些框架默认过滤下划线 header）或拼写错误（
X-Request-ID区分大小写）
不复杂但容易忽略：只要 Nginx 版本够新、header 名规范、后端愿意接，$request_id 就是最省心的链路起点。
