Node.js的--trace-event-loop-timestamps是一个用于调试事件循环运行情况的启动标志，开启后会在事件循环的每个阶段输出对应的时间戳信息，帮助开发者分析事件循环各阶段的耗时情况，定位性能瓶颈。
--trace-event-loop-timestamps的基本作用
Node.js的事件循环分为多个阶段，包括定时器阶段、待处理回调阶段、空闲/准备阶段、轮询阶段、检查阶段、关闭回调阶段等。默认情况下，我们很难直接获取到每个阶段的精确执行时间，而--trace-event-loop-timestamps标志就是为了解决这个问题而存在的。
开启该标志后，Node.js会在事件循环进入和离开每个阶段时，向标准错误流输出时间戳信息，这些时间戳包含了阶段名称、进入时间、离开时间等核心数据，开发者可以通过分析这些数据，判断事件循环中哪个阶段耗时过长，是否存在阶段阻塞导致事件循环延迟的问题。
如何使用--trace-event-loop-timestamps
使用该标志的方式非常简单，只需要在启动Node.js应用时，将该标志作为参数添加到启动命令中即可，不需要额外安装任何依赖。
基本启动示例
假设我们有一个简单的Node.js应用文件app.js，内容如下：
// app.js 简单示例，模拟一个定时器任务
setTimeout(() => {
console.log('定时器任务执行完成');
}, 1000);
// 模拟一个微任务
Promise.resolve().then(() => {
console.log('微任务执行完成');
});
使用--trace-event-loop-timestamps标志启动该应用的命令为：
node --trace-event-loop-timestamps app.js
输出内容示例
启动后，除了应用本身的输出外，标准错误流会输出类似下面的事件循环时间戳信息：
trace_event_loop_timestamps: enter timers 1620000000000 trace_event_loop_timestamps: exit timers 1620000000010 trace_event_loop_timestamps: enter pending callbacks 1620000000010 trace_event_loop_timestamps: exit pending callbacks 1620000000010 trace_event_loop_timestamps: enter idle, prepare 1620000000010 trace_event_loop_timestamps: exit idle, prepare 1620000000010 trace_event_loop_timestamps: enter poll 1620000000010 trace_event_loop_timestamps: exit poll 1620000001010 trace_event_loop_timestamps: enter check 1620000001010 trace_event_loop_timestamps: exit check 1620000001010 trace_event_loop_timestamps: enter close callbacks 1620000001010 trace_event_loop_timestamps: exit close callbacks 1620000001010
其中时间戳的单位是毫秒，从上述输出可以看到，poll阶段从1620000000010到1620000001010，耗时1000毫秒，正好对应了我们设置的1秒定时器等待时间。
实际应用场景
--trace-event-loop-timestamps标志在以下场景中非常实用：
- 事件循环延迟排查：当应用出现响应变慢、请求处理延迟升高的问题时，可以通过该标志查看事件循环各阶段的耗时，判断是否存在某个阶段长时间阻塞的情况。
- 性能优化验证：在对事件循环相关代码进行优化后，开启该标志对比优化前后的时间戳数据，验证优化是否生效。
- 学习事件循环机制：对于想要深入了解Node.js事件循环执行流程的开发者，该标志输出的时间戳可以直观展示各阶段的执行顺序和耗时情况，辅助理解事件循环的运行逻辑。
注意事项
使用--trace-event-loop-timestamps标志时需要注意以下几点：
- 该标志的输出是写入标准错误流（stderr）的，不会和标准输出（stdout）的内容混合，如果需要保存分析，可以将标准错误流重定向到文件，例如：
node --trace-event-loop-timestamps app.js 2> loop_trace.log。 - 开启该标志会带来一定的性能开销，因为需要在每个事件循环阶段插入时间戳记录的逻辑，所以不建议在生产环境长期开启，仅用于调试场景。
- 输出的时间戳是Node.js进程运行时的相对时间，不同进程的时间戳没有直接可比性，仅能用于单进程内的事件循环分析。
结合其他调试工具使用
--trace-event-loop-timestamps可以和其他Node.js调试标志配合使用，比如--trace-events-enabled标志，后者可以输出更全面的跟踪事件，两者结合可以更全面地分析应用的运行性能。如果需要更可视化的分析，还可以将输出的时间戳数据导入到性能分析工具中，生成时间线图表，更直观地查看事件循环的运行情况。
Node.jstrace_event_loop_timestamps事件循环性能调试修改时间：2026-06-27 18:39:32