nginx 1.11.0+ 可直接用内置 $request_id 变量生成唯一 traceid，通过 proxy_set_header 注入 x-request-id 等请求头透传，无需额外模块或配置，默认启用且稳定可靠。
在 Nginx 中为每个请求生成并透传全局唯一的 TraceID，核心是利用 $request_id 变量（Nginx 1.11.0+ 内置），它在请求生命周期内唯一、随机且稳定。你无需额外模块或 Lua 脚本，即可直接在 proxy_pass 转发时注入该 ID 到请求头中。
启用并透传 $request_id 作为 TraceID
Nginx 默认已启用 $request_id，无需配置。只需在 location 或 server 块中使用 proxy_set_header 将其设为自定义 Trace 头：
- 推荐使用标准名
X-Request-ID（广泛支持）或业务约定的X-Trace-ID - 确保后端服务能读取该头，并在日志、链路追踪中使用
- 若需兼容旧版本 Nginx（$pid:$msec:$connection 组合（不推荐，有碰撞风险）
配置示例（HTTP 反向代理场景）
在 location 块中添加以下指令：
location /api/ {
proxy_pass http://backend;
proxy_set_header X-Request-ID $request_id;
proxy_set_header X-Trace-ID $request_id; # 可同时设多个名，按需选择
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
这样每次请求到达 Nginx 时，都会自动携带一个新生成的 32 位十六进制字符串（如 9e4d8a1f5b2c4a7e9d0f1a2b3c4d5e6f）作为 TraceID 向后传递。
与上游服务协同的关键点
仅 Nginx 添加头还不够，需上下游配合才能实现全链路追踪：
- 如果上游服务（如 Spring Cloud、OpenTelemetry 接入服务）收到
X-Request-ID，应优先将其作为当前 trace 的根 ID，而非新建 - 建议统一规范：入口 Nginx 生成并注入，下游服务只继承、不覆盖（除非明确需要分段 trace）
- 若前端也参与追踪（如 JS SDK），可将该 ID 通过响应头（
Access-Control-Expose-Headers: X-Request-ID）返回，供前端日志关联
验证是否生效
可通过 curl 检查响应头和后端日志：
curl -I http://your-nginx/api/test
观察响应中是否有 X-Request-ID；同时查看后端 access log 或应用日志，确认是否记录了该值。多次请求应看到不同的 ID，同一请求在 Nginx 和后端日志中 ID 一致。
