ThinkPHP中需在入口中间件生成唯一TraceID并注入日志上下文，HTTP出站请求必须透传X-Trace-ID头，日志格式需含{context}占位符，队列任务须手动恢复TraceID以保障链路贯穿。
ThinkPHP中如何生成和注入全局TraceID
接口调用链路追踪的前提，是每个请求进来就有一个唯一、稳定、可透传的标识。ThinkPHP本身不内置TraceID，得自己在请求入口生成并绑定到上下文。
推荐在 app/middleware/TraceIdMiddleware.php 中统一处理，利用 Request 对象的 header 或 param 优先读取上游传入的 X-Trace-ID，没有则用 uniqid('t', true) 生成（注意避免纯时间戳碰撞）。
- 务必用
$request->header('X-Trace-ID')而非input('trace_id')，防止被业务参数污染 - 生成后必须立刻写入
Log::setContext(['trace_id' => $traceId])，否则日志里看不到 - 不要用
session()或cookie()存TraceID，跨服务时无效
ThinkPHP发起HTTP请求时如何透传TraceID
下游服务要能继续链路，你发出去的每个HTTP请求（比如用 think\Http 或 cURL）都得带上 X-Trace-ID 头。漏掉这一步，链路就在你这里断了。
常见错误是只在日志里打了ID，但没往外传。尤其注意 think\facade\Http 的 post()、get() 方法默认不带任何自定义头，必须显式传 headers 参数。
立即学习“PHP免费学习笔记（深入）”；
- 正确写法：
Http::withHeaders(['X-Trace-ID' => $traceId])->post($url, $data) - 如果用了 Guzzle，记得在
headers数组里补上'X-Trace-ID' => $traceId - 调用第三方 SDK（如阿里云OSS、微信支付）时，它们通常不支持透传，得改造成手动HTTP请求或包装一层代理
Log::write() 日志中为什么没出现trace_id
即使你调用了 Log::setContext()，日志文件里仍可能看不到 trace_id，根本原因是 ThinkPHP 默认日志格式没启用上下文变量插值。
检查你的日志配置 config/log.php，确保 'format' 字段包含 {context} 占位符，例如：'format' => '[{datetime}] {level} {message} {context}'。否则 setContext 完全无效。
- 别依赖
Log::info('msg', ['trace_id' => $id])这种写法——它只是把数组当附加参数打进去，不会自动合并进上下文 - 如果用了 Monolog 驱动，确认
Monolog\Handler\StreamHandler的 formatter 已设置为支持 context 的版本 - 本地开发时可用
Log::getLog()手动查当前上下文，快速验证是否生效
多级子服务调用时TraceID被覆盖或丢失
一个请求经过 A → B → C → D 四层服务，如果B在调用C前没把收到的 X-Trace-ID 原样透传，或者C自己又生成了一个新ID，链路就分裂成两段。
最容易被忽略的是「中间件顺序」和「异步任务」：ThinkPHP 的中间件执行顺序影响 Request 解析时机；而用 queue:work 启动的队列任务，默认不继承父请求的上下文，Log::getContext() 是空的。
- 队列任务中必须手动从 job payload 或 Redis key 中提取原始
trace_id，再调用Log::setContext() - 多个中间件都操作
Request时，确保 TraceID 中间件排在最前面（app/middleware.php中靠前注册） - 不要在模型事件、钩子函数里重新生成 ID，它们可能跨请求复用对象实例
TraceID 生效的关键不在“有没有”，而在“能不能贯穿整个生命周期”——从入口解析、日志写入、出站透传，到异步任务延续，每一步漏掉，链路就断一次。真正难的不是代码量，是排查哪一环静默丢掉了它。
