在Node.js服务端开发中，当系统并发处理大量HTTP请求时，传统的日志输出往往只记录单行信息，无法把一个请求从进入到响应的全过程串联起来。AsyncLocalStorage是Node.js内置模块async_hooks提供的能力，它允许我们在一次异步执行上下文中存储和读取数据，且这些数据会自动跟随异步调用链传递，非常适合用来做全链路日志追踪。
一、为什么需要全链路日志追踪
没有上下文关联的日志在排查问题时效率很低。比如一个用户下单请求，内部会经过鉴权、库存校验、创建订单、发送消息等多个步骤，这些步骤可能由不同的函数甚至不同的模块处理。如果日志里没有统一的请求标识，我们只能靠时间勉强猜测哪些日志属于同一次请求，一旦并发量高，日志就会完全交错在一起。
过去常见的做法是把traceId作为函数参数，从入口层一层层往下传。这种方式侵入性强，任何新增函数都要修改签名；如果某层忘记传递，链路就断了。AsyncLocalStorage的出现解决了这个问题，它让上下文与代码解耦，业务函数不需要感知traceId的存在。
二、AsyncLocalStorage基本原理
AsyncLocalStorage构建在async_hooks之上。Node.js在运行时会为每个异步操作（如setTimeout、Promise.then、fs回调）分配一个asyncId，并形成父子关系的异步资源树。当我们调用asyncLocalStorage.run(store, callback)时，callback内产生的所有异步任务都会继承这个store，无论中间经过多少层await或回调。
需要注意的是，store只在run方法包裹的同步及衍生异步逻辑中有效。如果在run外部启动了新的异步任务，或者使用了不受async_hooks跟踪的第三方原生绑定，就可能读取不到上下文。因此理解异步边界非常关键，这也是很多初学者误以为它失效的原因。
核心API示例
const { AsyncLocalStorage } = require('async_hooks');
// 创建一个全链路存储实例
const asyncLocalStorage = new AsyncLocalStorage();
function logWithTrace(message) {
// 在任意深处读取入口写入的traceId
const store = asyncLocalStorage.getStore();
const traceId = store ? store.traceId : 'no-trace';
console.log(`[${traceId}] ${message}`);
}
function doBusiness() {
logWithTrace('开始处理业务');
setTimeout(() => {
logWithTrace('异步任务完成');
}, 10);
}
// 模拟请求入口
asyncLocalStorage.run({ traceId: 'req-12345' }, () => {
logWithTrace('请求进入');
doBusiness();
});
上面代码中，run方法传入了包含traceId的对象，doBusiness及内部的setTimeout回调都能通过getStore拿到同一个对象。这就是全链路追踪的数据基础。
三、在HTTP服务中落地
以Express为例，我们可以在中间件里为每个请求生成唯一ID，并放入AsyncLocalStorage。后续路由处理、数据库查询中调用的日志函数都会自动带上该ID，无需手动传递。
下面示例展示了一个最小实现。我们在请求进来时生成traceId，在响应结束时无需额外清理，因为run的上下文随本次请求异步链结束而销毁，不会污染下一个请求。
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const crypto = require('crypto');
const asyncLocalStorage = new AsyncLocalStorage();
const app = express();
app.use((req, res, next) => {
const traceId = crypto.randomUUID();
asyncLocalStorage.run({ traceId }, () => {
// 把traceId挂到响应头方便前端排查
res.setHeader('X-Trace-Id', traceId);
next();
});
});
function info(msg) {
const store = asyncLocalStorage.getStore();
const traceId = store && store.traceId;
console.log(`[${traceId}] ${msg}`);
}
app.get('/order', async (req, res) => {
info('收到下单请求');
await new Promise(r => setTimeout(r, 20));
info('订单处理完毕');
res.json({ ok: true });
});
app.listen(3000);
启动服务后访问/order接口，控制台会输出两行带相同traceId的日志。即使我们在info函数外层又包了多层service和dao，只要它们处于同一次请求异步链内，就不会丢失上下文。
四、与日志库集成
实际项目中我们通常用Winston或Pino等日志库。可以通过自定义日志格式，在每次写日志时从AsyncLocalStorage读取traceId并附加到字段中。这样所有日志天然带有链路信息，接入ELK等系统后就能按traceId聚合。
以Winston为例，可以使用format回调获取store。下面代码演示了格式化器的写法，它和前面中间件配合，即可实现无侵入埋点。
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');
const asyncLocalStorage = new AsyncLocalStorage();
const logger = winston.createLogger({
format: winston.format.combine(
winston.format((info) => {
const store = asyncLocalStorage.getStore();
info.traceId = store ? store.traceId : undefined;
return info;
})(),
winston.format.json()
),
transports: [new winston.transports.Console()]
});
// 在请求入口使用同样的asyncLocalStorage实例run即可
这种写法把上下文读取逻辑收敛到日志库内部，业务代码只需要像平时一样调用logger.info，完全不用关心traceId。比起在每行日志手动拼接，可维护性明显更好。
五、注意事项与常见误区
第一个误区是认为AsyncLocalStorage是全局变量。它并不是全局共享，而是按异步上下文隔离的。如果在run外面调用getStore，拿到的是undefined，这是正常设计，不要试图用全局变量替代它。
第二个问题是第三方库如果自己创建了独立的异步资源且未正确继承，可能导致上下文丢失。遇到这类情况，可以检查该库是否支持async_hooks，或者手动用AsyncResource包裹。此外，在大量短生命周期请求下，async_hooks本身有轻微性能开销，通常可以忽略，但极端性能敏感场景需做压测。
| 方案 | 侵入性 | 链路稳定性 | 实现复杂度 |
|---|---|---|---|
| 参数透传traceId | 高 | 易断链 | 低 |
| AsyncLocalStorage | 低 | 自动继承 | 中 |
| 全局变量 | 无 | 并发错乱 | 极低 |
通过上面的对比可以看出，AsyncLocalStorage在侵入性和链路稳定性之间取得了最好的平衡，是现代Node.js服务做全链路追踪的首选方案。
Node.jsAsyncLocalStorage全链路日志修改时间：2026-08-10 11:18:39