应优先复用上游 x-request-id 并通过 map 生成 $trace_id，再用 proxy_set_header 注入；nginx 1.11.0+ 原生支持 $request_id，需在 location 块内配置，同时日志和后端须协同透传该 id。
在 Linux 的 Nginx 中为代理请求添加自定义追踪 ID，核心是用 $request_id（推荐）或自定义变量生成唯一标识，并通过 proxy_set_header 注入到发往后端的 HTTP 请求头中。关键不在于“自定义”，而在于“统一、稳定、可透传”——避免覆盖已有 ID，也别让后端重复生成。
确认并启用内置 $request_id
Nginx 1.11.0+ 原生支持 $request_id，每次请求自动产生一个 32 位小写十六进制字符串（如 8f3a1b2c4d5e6f7g8h9i0j1k2l3m4n5o），无需模块、不依赖 Lua：
- 运行
nginx -v确认版本 ≥ 1.11.0；低于则必须升级 - 该变量天然可用，不要在配置里写
set $req_id $request_id或类似初始化语句 - 它在整个请求生命周期内稳定存在，可用于日志、header、map 等任意上下文
优先复用上游 X-Request-ID（推荐做法）
若请求已由前端网关、API 网关或客户端携带 X-Request-ID，应直接透传，而非覆盖——这是保证全链路 ID 一致的前提：
- 在
http块顶部添加 map 规则：
"" $request_id;
default $http_x_request_id;
}
- 后续所有 header 注入和透传都使用
$trace_id，例如：proxy_set_header X-Request-ID $trace_id;add_header X-Request-ID $trace_id always;
在 location 中正确透传给后端
proxy_set_header 必须放在 location 块内，且紧邻 proxy_pass，否则不生效：
- ✅ 正确示例：
proxy_set_header X-Request-ID $trace_id;
proxy_set_header X-Real-IP $remote_addr;
proxy_pass http://backend;
}
- ❌ 错误写法：把
proxy_set_header放在http或server块顶层——Nginx 不识别 - 若配置了多个 upstream 或路径，每个
location都需单独设置
配套：记录到日志并确保后端配合
仅加 header 不够，还需可观测性和下游协同：
- 在
log_format中显式包含$trace_id（不是$http_x_request_id）：
'$status $body_bytes_sent "$http_referer" "$http_user_agent" '
'req_id:"$trace_id"';
- 后端服务（Spring Boot/Go/Node.js 等）必须禁用自身 ID 生成逻辑，只读取并透传
X-Request-ID，并在日志中打印同一字段名（如trace_id） - 若后端使用 OpenTelemetry 或 Jaeger，需将该 header 映射为 trace context 的 fallback 字段，不能直接等价但要可关联
