Node.js v25.0.0 文档
- Node.js v25.0.0
-
目录
- 检查器
- Promises API
- 回调 API
- 通用对象
- 与 DevTools 集成
inspector.Network.dataReceived([params])
inspector.Network.dataSent([params])
inspector.Network.requestWillBeSent([params])
inspector.Network.responseReceived([params])
inspector.Network.loadingFinished([params])
inspector.Network.loadingFailed([params])
inspector.Network.webSocketCreated([params])
inspector.Network.webSocketHandshakeResponseReceived([params])
inspector.Network.webSocketClosed([params])
inspector.NetworkResources.put
- 断点支持
- 检查器
-
索引
- 断言测试
- 异步上下文跟踪
- 异步钩子
- 缓冲区
- C++ 插件
- 使用 Node-API 的 C/C++ 插件
- C++ 嵌入器 API
- 子进程
- 集群
- 命令行选项
- 控制台
- 加密
- 调试器
- 已弃用的 API
- 诊断通道
- DNS
- 域
- 环境变量
- 错误
- 事件
- 文件系统
- 全局对象
- HTTP
- HTTP/2
- HTTPS
- 检查器
- 国际化
- 模块:CommonJS 模块
- 模块:ECMAScript 模块
- 模块:
node:module
API - 模块:包
- 模块:TypeScript
- 网络
- 操作系统
- 路径
- 性能钩子
- 权限
- 进程
- Punycode
- 查询字符串
- 逐行读取
- REPL
- 报告
- 单一可执行文件应用
- SQLite
- 流
- 字符串解码器
- 测试运行器
- 定时器
- TLS/SSL
- 跟踪事件
- TTY
- UDP/数据报
- URL
- 实用工具
- V8
- 虚拟机
- WASI
- Web Crypto API
- Web Streams API
- 工作线程
- Zlib
- 其他版本
- 选项
Inspector#
源代码: lib/inspector.js
node:inspector
模块提供了一个与 V8 检查器交互的 API。
它可以通过以下方式访问
import * as inspector from 'node:inspector/promises';
const inspector = require('node:inspector/promises');
或
import * as inspector from 'node:inspector';
const inspector = require('node:inspector');
Promises API#
类:inspector.Session
#
- 继承自:<EventEmitter>
inspector.Session
用于向 V8 检查器后端分派消息,并接收消息响应和通知。
new inspector.Session()
#
创建 inspector.Session
类的新实例。在向检查器后端分派消息之前,需要通过 session.connect()
连接检查器会话。
使用 Session
时,除非我们手动执行 Runtime.DiscardConsoleEntries
命令,否则由控制台 API 输出的对象将不会被释放。
事件:'inspectorNotification'
#
- 类型:<Object> 通知消息对象
当收到来自 V8 检查器的任何通知时触发。
session.on('inspectorNotification', (message) => console.log(message.method));
// Debugger.paused
// Debugger.resumed
注意:不建议在同线程会话中使用断点,请参阅断点支持。
也可以只订阅具有特定方法的通知。
事件:<inspector-protocol-method>
#
- 类型:<Object> 通知消息对象
当收到一个检查器通知,且其 method 字段设置为 <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])
#
向检查器后端发送一条消息。
import { Session } from 'node:inspector/promises';
try {
const session = new Session();
session.connect();
const result = await session.post('Runtime.evaluate', { expression: '2 + 2' });
console.log(result);
} catch (error) {
console.error(error);
}
// Output: { result: { type: 'number', value: 4, description: '4' } }
最新版本的 V8 检查器协议发布在 Chrome DevTools 协议查看器上。
Node.js 检查器支持 V8 声明的所有 Chrome DevTools 协议域。Chrome DevTools 协议域提供了一个接口,用于与用于检查应用程序状态和监听运行时事件的运行时代理进行交互。
用法示例#
除了调试器,还可以通过 DevTools 协议使用各种 V8 分析器。
CPU 分析器#
这是一个展示如何使用 CPU 分析器的示例。
import { Session } from 'node:inspector/promises';
import fs from 'node:fs';
const session = new Session();
session.connect();
await session.post('Profiler.enable');
await session.post('Profiler.start');
// Invoke business logic under measurement here...
// some time later...
const { profile } = await session.post('Profiler.stop');
// Write profile to disk, upload, etc.
fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile));
堆分析器#
这是一个展示如何使用 堆分析器的示例。
import { Session } from 'node:inspector/promises';
import fs from 'node:fs';
const session = new Session();
const fd = fs.openSync('profile.heapsnapshot', 'w');
session.connect();
session.on('HeapProfiler.addHeapSnapshotChunk', (m) => {
fs.writeSync(fd, m.params.chunk);
});
const result = await session.post('HeapProfiler.takeHeapSnapshot', null);
console.log('HeapProfiler.takeHeapSnapshot done:', result);
session.disconnect();
fs.closeSync(fd);
回调 API#
类:inspector.Session
#
- 继承自:<EventEmitter>
inspector.Session
用于向 V8 检查器后端分派消息,并接收消息响应和通知。
new inspector.Session()
#
创建 inspector.Session
类的新实例。在向检查器后端分派消息之前,需要通过 session.connect()
连接检查器会话。
使用 Session
时,除非我们手动执行 Runtime.DiscardConsoleEntries
命令,否则由控制台 API 输出的对象将不会被释放。
事件:'inspectorNotification'
#
- 类型:<Object> 通知消息对象
当收到来自 V8 检查器的任何通知时触发。
session.on('inspectorNotification', (message) => console.log(message.method));
// Debugger.paused
// Debugger.resumed
注意:不建议在同线程会话中使用断点,请参阅断点支持。
也可以只订阅具有特定方法的通知。
事件:<inspector-protocol-method>
;#
- 类型:<Object> 通知消息对象
当收到一个检查器通知,且其 method 字段设置为 <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 检查器协议发布在 Chrome DevTools 协议查看器上。
Node.js 检查器支持 V8 声明的所有 Chrome DevTools 协议域。Chrome DevTools 协议域提供了一个接口,用于与用于检查应用程序状态和监听运行时事件的运行时代理进行交互。
在向 V8 发送 HeapProfiler.takeHeapSnapshot
或 HeapProfiler.stopTrackingHeapObjects
命令时,不能将 reportProgress
设置为 true
。
用法示例#
除了调试器,还可以通过 DevTools 协议使用各种 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);
});
通用对象#
inspector.close()
#
尝试关闭所有剩余的连接,阻塞事件循环直到所有连接都已关闭。一旦所有连接都关闭,就停用检查器。
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
。- 返回:<Disposable> 一个调用
inspector.close()
的 Disposable 对象。
在指定的主机和端口上激活检查器。等同于 node --inspect=[[host:]port]
,但可以在 Node 启动后以编程方式执行。
如果 `wait` 为 `true`,将阻塞直到有客户端连接到检查端口并且流控制已传递给调试器客户端。
请参阅有关 `host` 参数使用的安全警告。
inspector.url()
#
- 返回:<string> | <undefined>
返回活动检查器的 URL,如果没有则返回 `undefined`。
$ node --inspect -p 'inspector.url()'
Debugger listening on ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34
For help, see: https://node.org.cn/en/docs/inspector
ws://127.0.0.1:9229/166e272e-7a30-4d09-97ce-f1c012b43c34
$ node --inspect=localhost:3000 -p 'inspector.url()'
Debugger listening on ws://:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a
For help, see: https://node.org.cn/en/docs/inspector
ws://:3000/51cf8d0e-3c36-4c59-8efd-54519839e56a
$ node -p 'inspector.url()'
undefined
inspector.waitForDebugger()
#
阻塞直到一个客户端(现有的或稍后连接的)发送了 `Runtime.runIfWaitingForDebugger` 命令。
如果没有活动的检查器,将抛出异常。
与 DevTools 集成#
node:inspector
模块提供了一个 API,用于与支持 Chrome DevTools 协议的开发工具集成。连接到正在运行的 Node.js 实例的 DevTools 前端可以捕获从该实例发出的协议事件,并相应地显示它们以方便调试。以下方法向所有连接的前端广播一个协议事件。传递给这些方法的 params
可以是可选的,具体取决于协议。
// The `Network.requestWillBeSent` event will be fired.
inspector.Network.requestWillBeSent({
requestId: 'request-id-1',
timestamp: Date.now() / 1000,
wallTime: Date.now(),
request: {
url: 'https://node.org.cn/en',
method: 'GET',
},
});
inspector.Network.dataReceived([params])
#
params
<Object>
此功能仅在启用 --experimental-network-inspection
标志时可用。
向连接的前端广播 Network.dataReceived
事件,或者如果尚未为给定请求调用 Network.streamResourceContent
命令,则缓冲数据。
还启用了 Network.getResponseBody
命令来检索响应数据。
inspector.Network.dataSent([params])
#
params
<Object>
此功能仅在启用 --experimental-network-inspection
标志时可用。
启用 Network.getRequestPostData
命令来检索请求数据。
inspector.Network.requestWillBeSent([params])
#
params
<Object>
此功能仅在启用 --experimental-network-inspection
标志时可用。
向连接的前端广播 Network.requestWillBeSent
事件。此事件表示应用程序即将发送一个 HTTP 请求。
inspector.Network.responseReceived([params])
#
params
<Object>
此功能仅在启用 --experimental-network-inspection
标志时可用。
向连接的前端广播 Network.responseReceived
事件。此事件表示 HTTP 响应已可用。
inspector.Network.loadingFinished([params])
#
params
<Object>
此功能仅在启用 --experimental-network-inspection
标志时可用。
向连接的前端广播 Network.loadingFinished
事件。此事件表示 HTTP 请求已完成加载。
inspector.Network.loadingFailed([params])
#
params
<Object>
此功能仅在启用 --experimental-network-inspection
标志时可用。
向连接的前端广播 Network.loadingFailed
事件。此事件表示 HTTP 请求加载失败。
inspector.Network.webSocketCreated([params])
#
params
<Object>
此功能仅在启用 --experimental-network-inspection
标志时可用。
向连接的前端广播 Network.webSocketCreated
事件。此事件表示一个 WebSocket 连接已启动。
inspector.Network.webSocketHandshakeResponseReceived([params])
#
params
<Object>
此功能仅在启用 --experimental-network-inspection
标志时可用。
向连接的前端广播 Network.webSocketHandshakeResponseReceived
事件。此事件表示已收到 WebSocket 握手响应。
inspector.Network.webSocketClosed([params])
#
params
<Object>
此功能仅在启用 --experimental-network-inspection
标志时可用。
向连接的前端广播 Network.webSocketClosed
事件。此事件表示一个 WebSocket 连接已关闭。
inspector.NetworkResources.put
#
此功能仅在启用 --experimental-inspector-network-resource
标志时可用。
inspector.NetworkResources.put 方法用于为通过 Chrome DevTools 协议(CDP)发出的 loadNetworkResource 请求提供响应。这通常在源映射(source map)由 URL 指定时触发,并且 DevTools 前端(如 Chrome)请求该资源以检索源映射。
此方法允许开发者预定义要为响应此类 CDP 请求而提供的资源内容。
const inspector = require('node:inspector');
// By preemptively calling put to register the resource, a source map can be resolved when
// a loadNetworkResource request is made from the frontend.
async function setNetworkResources() {
const mapUrl = 'https://:3000/dist/app.js.map';
const tsUrl = 'https://:3000/src/app.ts';
const distAppJsMap = await fetch(mapUrl).then((res) => res.text());
const srcAppTs = await fetch(tsUrl).then((res) => res.text());
inspector.NetworkResources.put(mapUrl, distAppJsMap);
inspector.NetworkResources.put(tsUrl, srcAppTs);
};
setNetworkResources().then(() => {
require('./dist/app');
});
更多详情,请参阅官方 CDP 文档:Network.loadNetworkResource
断点支持#
Chrome DevTools 协议的 Debugger
域允许 inspector.Session
附加到程序并设置断点以单步调试代码。
但是,应避免使用由 session.connect()
连接的同线程 inspector.Session
设置断点,因为被附加和暂停的程序正是调试器本身。相反,应尝试通过 session.connectToMainThread()
连接到主线程,并在工作线程中设置断点,或者通过 WebSocket 连接使用 调试器 程序进行连接。