Node.js中CLS请求执行期间上下文丢失问题排查

嘿，我来帮你解决这个cls-hooked上下文丢失的排查问题——我之前在Express项目里也遇到过类似的情况，下面是几个亲测有效的方法：

1. 用AsyncHooks手动监控上下文流转 #

cls-hooked本质上依赖Node.js的AsyncHooks API追踪异步上下文，所以我们可以自己写个简单的Hook来监控每一步异步操作的上下文变化，精准定位丢失点。比如：

const async_hooks = require('async_hooks');
const cls = require('cls-hooked');

const appNamespace = cls.createNamespace('my-app-context');

// 创建自定义AsyncHook，记录关键信息
const contextHook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    const currentCtxId = appNamespace.get('requestId');
    console.log(`[Init] 类型: ${type}, 异步ID: ${asyncId}, 触发ID: ${triggerAsyncId}, 当前上下文ID: ${currentCtxId || '无'}`);
  },
  before(asyncId) {
    const currentCtxId = appNamespace.get('requestId');
    console.log(`[Before] 执行异步ID: ${asyncId}, 当前上下文ID: ${currentCtxId || '无'}`);
  },
  after(asyncId) {
    const currentCtxId = appNamespace.get('requestId');
    console.log(`[After] 完成异步ID: ${asyncId}, 当前上下文ID: ${currentCtxId || '无'}`);
  }
});

contextHook.enable();

// 在Express入口中间件初始化上下文
app.use((req, res, next) => {
  // 用请求的唯一ID标记上下文，方便追踪
  req.requestId = `req-${Date.now()}-${Math.random().toString(36).slice(2)}`;
  appNamespace.run(() => {
    appNamespace.set('requestId', req.requestId);
    next();
  });
});

当请求处理中上下文丢失时，看日志里第一次出现“当前上下文ID: 无”的位置，对应的类型（比如PROMISE、TIMERWRAP、TCPWRAP）就能帮你锁定是哪个异步操作出了问题，进而关联到对应的模块。

2. 逐步排查模块（最直接的笨办法） #

如果不想写代码，那就用“排除法”：

• 先把Express路由里的中间件、业务逻辑、第三方依赖逐个移除，直到上下文不再丢失；
• 然后再把模块逐个加回来，每次加完测试一次，找到那个一加回来就丢上下文的模块。
• 重点盯那些涉及底层异步操作的模块：数据库驱动、缓存客户端、文件IO库、第三方API请求工具——这些模块最容易绕过AsyncHooks追踪。

3. 检查模块是否用了未被追踪的异步API #

有些模块会用一些AsyncHooks覆盖不到的操作，比如：

• 同步调用异步回调：比如某些库在同步函数里直接执行异步回调，跳过了AsyncHooks的触发逻辑；
• 原生C++扩展：很多C++写的扩展没有实现AsyncHooks的追踪接口，导致上下文无法传递；
• 手动管理调用栈：比如有些模块自己封装了任务队列，没有正确继承父上下文。

你可以翻可疑模块的源码，或者看它的Issue区，有没有人提过和上下文丢失、AsyncHooks相关的问题。

4. 开启cls-hooked的调试日志 #

cls-hooked本身自带调试模式，只要设置环境变量就能开启详细日志：

DEBUG=cls-hooked node your-app.js

开启后，它会输出上下文创建、传递、切换的每一步细节，你能从中看到上下文是在哪一步突然中断的，直接定位到对应的模块调用。

5. 单独测试可疑模块 #

对怀疑的模块，写个极简测试用例验证它是否破坏上下文：

const cls = require('cls-hooked');
const suspectModule = require('你怀疑的模块');

const testNamespace = cls.createNamespace('test-ctx');

testNamespace.run(() => {
  testNamespace.set('testKey', 'hello-cls');
  
  // 调用模块的异步方法
  suspectModule.someAsyncOperation(() => {
    const value = testNamespace.get('testKey');
    if (!value) {
      console.log('糟了！这个模块破坏了上下文');
    } else {
      console.log('上下文正常传递~');
    }
  });
});

这个方法能快速帮你确认某个模块是不是罪魁祸首。

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