Node.js v18.18.0 文档

inspector.close()#

停用检查器。 阻塞直到没有活动连接。

使用 Session 时，控制台 API 输出的对象不会被释放，除非我们手动执行 Runtime.DiscardConsoleEntries 命令。

inspector.console#

• <Object> 向远程检查器控制台发送消息的对象。

require('node:inspector').console.log('a message'); 拷贝

检查器控制台没有与 Node.js 控制台的 API 奇偶校验。

inspector.open([port[, host[, wait]]])#

• port <number> 监听检查器连接的端口。 可选的。 默认值： 在 CLI 上指定的内容。
• host <string> 主机监听检查器连接。 可选的。 默认值： 在 CLI 上指定的内容。
• wait <boolean> 在客户端连接之前阻塞。 可选的。 默认值： false。

在主机和端口上激活检查器。 相当于 node --inspect=[[host:]port]，但可以在 node 启动后以编程方式完成。

如果等待为 true，则将阻塞直到客户端连接到检查端口并且流量控制已传给调试器客户端。

有关 host 参数用法，请参阅 安全警告。

inspector.url()#

• 返回： <string> | <undefined>

返回活动检查器的网址，如果没有，则返回 undefined。

$ node --inspect -p 'inspector.url()'
Debugger listening on ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34
For help, see: https://nodejs.cn/docs/inspector
ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34

$ node --inspect=localhost:3000 -p 'inspector.url()'
Debugger listening on ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a
For help, see: https://nodejs.cn/docs/inspector
ws://localhost:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a

$ node -p 'inspector.url()'
undefined 拷贝

inspector.waitForDebugger()#

阻塞直到客户端（现有或稍后连接）发送 Runtime.runIfWaitingForDebugger 命令。

如果没有活动的检查器，则将会抛出异常。

类：inspector.Session#

• 继承： <EventEmitter>

inspector.Session 用于向 V8 检查器后端发送消息并接收消息响应和通知。

new inspector.Session()#

创建 inspector.Session 类的新实例。 检查器会话需要通过 session.connect() 连接才能将消息发送到检查器后端。

使用 Session 时，控制台 API 输出的对象不会被释放，除非我们手动执行 Runtime.DiscardConsoleEntries 命令。

事件：'inspectorNotification'#

• <Object> 通知消息对象

当接收到来自 V8 检查器的任何通知时触发。

session.on('inspectorNotification', (message) => console.log(message.method));
// Debugger.paused
// Debugger.resumed 拷贝

也可以只订阅特定方法的通知：

事件：<inspector-protocol-method>；#

• <Object> 通知消息对象

当接收到检查器通知其方法字段设置为 <inspector-protocol-method> 值时触发。

以下代码片段在 'Debugger.paused' 事件上安装了监听器，并在程序执行暂停时（例如通过断点）打印程序暂停的原因：

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints);
});
// [ '/the/file/that/has/the/breakpoint.js:11:0' ] 拷贝

session.connect()#

将会话连接到检查器后端。

session.connectToMainThread()#

将会话连接到主线程检查器后端。 如果没有在工作线程上调用此 API，则会抛出异常。

session.disconnect()#

立即关闭会话。 所有挂起的消息回调都将使用错误调用。 需要调用 session.connect() 才能再次发送消息。 重新连接的会话将丢失所有检查器状态，例如启用的代理或配置的断点。

session.post(method[, params][, callback])#

• method <string>
• params <Object>
• callback <Function>

向检查器后端发布消息。 callback 将在接收到响应时收到通知。 callback 是一个接受两个可选参数的函数： 错误和消息特定的结果。

session.post('Runtime.evaluate', { expression: '2 + 2' },
             (error, { result }) => console.log(result));
// Output: { type: 'number', value: 4, description: '4' } 拷贝

最新版本的 V8 inspector 协议发布在 Chrome DevTools 协议查看器 上。

Node.js 检查器支持 V8 声明的所有 Chrome 开发者工具协议域。 Chrome 开发者工具协议域提供了一个接口，用于与用于检查应用状态和监听运行时事件的运行时代理之一进行交互。

向 V8 发送 HeapProfiler.takeHeapSnapshot 或 HeapProfiler.stopTrackingHeapObjects 命令时，不能将 reportProgress 设置为 true。

用法示例#

除了调试器之外，还可以通过开发者工具协议使用各种 V8 分析器。

CPU 分析器#

这是一个显示如何使用 CPU 分析器 的示例：

const inspector = require('node:inspector');
const fs = require('node:fs');
const session = new inspector.Session();
session.connect();

session.post('Profiler.enable', () => {
  session.post('Profiler.start', () => {
    // Invoke business logic under measurement here...

    // some time later...
    session.post('Profiler.stop', (err, { profile }) => {
      // Write profile to disk, upload, etc.
      if (!err) {
        fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));
      }
    });
  });
}); 拷贝

堆分析器#

这是一个显示如何使用 堆分析器 的示例：

const inspector = require('node:inspector');
const fs = require('node:fs');
const session = new inspector.Session();

const fd = fs.openSync('profile.heapsnapshot', 'w');

session.connect();

session.on('HeapProfiler.addHeapSnapshotChunk', (m) => {
  fs.writeSync(fd, m.params.chunk);
});

session.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => {
  console.log('HeapProfiler.takeHeapSnapshot done:', err, r);
  session.disconnect();
  fs.closeSync(fd);
}); 拷贝