如何排查Node.js libuv线程池阻塞致异步操作停滞问题？

(a) 验证线程池是否被阻塞 #

• 用async_hooks追踪线程池任务状态
  编写代码监控异步资源的创建与销毁，统计pending的线程池任务数量：

  const async_hooks = require('async_hooks');
  const fs = require('fs');
  
  const pendingTasks = new Set();
  
  const hook = async_hooks.createHook({
    init(id, type) {
      // 匹配libuv线程池相关的异步操作类型
      if (['FSREQWRAP', 'GETADDRINFOREQWRAP', 'WORKER'].includes(type)) {
        pendingTasks.add(id);
        console.log(`新增线程池任务: ${type}, 当前pending数: ${pendingTasks.size}`);
      }
    },
    destroy(id) {
      if (pendingTasks.has(id)) {
        pendingTasks.delete(id);
        console.log(`完成线程池任务, 当前pending数: ${pendingTasks.size}`);
      }
    }
  });
  
  hook.enable();
  
  // 执行测试用的fs操作
  fs.open("/etc/hostname", (err, fd) => { 
    console.log("Opened hostname");
    fs.close(fd, () => {});
  });
  
  // 定时打印pending任务数
  setInterval(() => {
    console.log(`当前pending线程池任务数: ${pendingTasks.size}`);
  }, 1000);
  

  若运行后pending数始终等于UV_THREADPOOL_SIZE（默认4），且测试fs操作的回调迟迟不触发，即可验证线程池被占满阻塞。

• 观察进程线程状态
  在树莓派终端执行：

  1. ps -T -p <你的Node进程PID>：查看进程下的线程数量，正常情况下线程池线程数为配置的UV_THREADPOOL_SIZE，若线程数长期固定且无动态变化，说明线程池线程全在忙碌。
  2. top -H -p <你的Node进程PID>：查看单个线程的状态，若某线程长期处于100%CPU占用或D状态（不可中断睡眠，通常是阻塞在系统调用/IO），说明该线程被阻塞。

(b) 定位阻塞操作 #

• 用--trace-sync-io启动应用
  执行node --trace-sync-io app.js，该参数会打印所有同步IO操作及相关调用栈，同时能追踪到那些被包装成异步但底层实际阻塞的操作，从输出的栈信息里锁定占用线程池的代码来源。

• 用perf工具分析（树莓派需先安装）

  1. 安装perf：sudo apt install linux-tools-$(uname -r)
  2. 采样线程调用栈：sudo perf record -F 99 -p <你的Node进程PID> -g -- sleep 30（采样30秒）
  3. 分析结果：sudo perf report
     在报告中找到线程池线程的调用栈，重点关注长期处于运行状态的函数，比如第三方库的同步IO、耗时加密计算等。

• 排查第三方依赖
  线程池阻塞常源于第三方库误用同步API或长时间占用线程池。可以逐个禁用依赖模块，或用npm ls列出所有依赖，重点排查涉及CPU密集型操作、IO操作的库（如数据库驱动、压缩工具等）。

• 打印活跃请求与句柄
  定时调用Node.js内部API查看pending任务：

  setInterval(() => {
    const activeReqs = process._getActiveRequests();
    console.log(`活跃请求数: ${activeReqs.length}`);
    activeReqs.forEach(req => {
      if (req.type === 'FSREQWRAP') {
        console.log(`待处理FS请求路径: ${req.path}`);
      }
    });
  }, 2000);
  

  该API在Node.js14、18版本均支持，能直接看到未完成的线程池任务细节。

内容的提问来源于stack exchange，提问作者TvE