Node.js v24.16.0 文档

探测模式#>

🌐 Probe mode

node inspect 支持通过标志 --probe 以非交互式探测模式检查应用中的运行时值。探测模式会启动应用，设置一个或多个源断点，每当触发匹配的断点时评估一个表达式，并在会话结束时（无论是正常完成还是超时）打印最终报告。这使开发者能够执行类似 printf 式的调试，而无需修改应用代码并在之后进行清理，同时它还支持用于工具的结构化输出。

$ node inspect [--json] [--preview] [--timeout=<ms>] [--port=<port>] \
    --probe app.js:10 --expr 'x' \
    [--probe app.js:20 --expr 'y' ...] \
    [--] [<node-option> ...] <script.js> [args...] 拷贝

• --probe <file>:<line>[:<col>]：要探查的源位置。行号和列号从 1 开始。
• --timeout=<ms>：整个探测会话的全局实时时钟截止时间。默认值为 30000。这可以用来探测可以被外部终止的长时间运行的应用。
• --json：如果使用，将打印结构化的 JSON 报告，而不是默认的文本报告。
• --preview：如果使用，非原始值将包括对象类 JSON 探针值的 CDP 属性预览。
• --port=<port>：选择用于 --inspect-brk 启动路径的本地检查器端口。探测模式默认为 0，它会请求一个随机端口。
• -- 是可选的，除非子级需要它自己专用的 Node.js 标志。

--probe 和 --expr 参数的附加规则：

🌐 Additional rules about the --probe and --expr arguments:

• --probe <file>:<line>[:<col>] 和 --expr <expr> 是严格配对的。每个 --probe 必须紧跟着正好一个 --expr。
• --timeout、--json、--preview 和 --port 是整个探测会话的全局探测选项。它们可以出现在探测对之前或之间，但不能出现在 --probe 与其匹配的 --expr 之间。

如果单个探针需要评估多个值，请评估 --expr 中的结构化值，例如 --expr "{ foo, bar }" 或 --expr "[foo, bar]"，并使用 --preview 在输出中包含任何类似对象的值的属性预览。

🌐 If a single probe needs to evaluate more than one value, evaluate a structured value in --expr, for example --expr "{ foo, bar }" or --expr "[foo, bar]", and use --preview to include property previews for any object-like values in the output.

探测模式仅将最终探测报告打印到标准输出，并且在其他情况下会静音子进程的标准输出/标准错误。如果子进程在探测会话开始后以错误退出，最终报告会记录一个带有退出代码和捕获的子进程标准错误的终端 error 事件。无效参数以及严重的启动或连接失败仍可能在没有最终探测结果的情况下将诊断信息打印到标准错误。

🌐 Probe mode only prints the final probe report to stdout, and otherwise silences stdout/stderr from the child process. If the child exits with an error after the probe session starts, the final report records a terminal error event with the exit code and captured child stderr. Invalid arguments and fatal launch or connect failures may still print diagnostics to stderr without a final probe result.

考虑这个脚本：

🌐 Consider this script:

// cli.js
let maxRSS = 0;
for (let i = 0; i < 2; i++) {
  const { rss } = process.memoryUsage();
  maxRSS = Math.max(maxRSS, rss);
} 拷贝

如果未使用 --json，输出将以人类可读的文本格式打印：

🌐 If --json is not used, the output is printed in a human-readable text format:

$ node inspect --probe cli.js:5 --expr 'rss' cli.js
Hit 1 at cli.js:5
  rss = 54935552
Hit 2 at cli.js:5
  rss = 55083008
Completed 拷贝

原始结果会直接打印，而对象和数组在可用时会使用 Chrome 开发者工具协议预览数据。其他非原始值会回退到 Chrome 开发者工具协议 description 字符串。表达式失败会记录为 [error] ... 行，并且不会导致整体会话失败。如果需要更丰富的文本格式，可以将表达式封装在 JSON.stringify(...) 或 util.inspect(...) 中。

🌐 Primitive results are printed directly, while objects and arrays use Chrome DevTools Protocol preview data when available. Other non-primitive values fall back to the Chrome DevTools Protocol description string. Expression failures are recorded as [error] ... lines and do not fail the overall session. If richer text formatting is needed, wrap the expression in JSON.stringify(...) or util.inspect(...).

当使用 --json 时，输出形状如下：

🌐 When --json is used, the output shape looks like this:

$ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
{"v":1,"probes":[{"expr":"rss","target":["cli.js",5]}],"results":[{"probe":0,"event":"hit","hit":1,"result":{"type":"number","value":55443456,"description":"55443456"}},{"probe":0,"event":"hit","hit":2,"result":{"type":"number","value":55574528,"description":"55574528"}},{"event":"completed"}]} 拷贝

{
  "v": 1, // Probe JSON schema version.
  "probes": [
    {
      "expr": "rss", // The expression paired with --probe.
      "target": ["cli.js", 5] // [file, line] or [file, line, col].
    }
  ],
  "results": [
    {
      "probe": 0, // Index into probes[].
      "event": "hit", // Hit events are recorded in observation order.
      "hit": 1, // 1-based hit count for this probe.
      "result": {
        "type": "number",
        "value": 55443456,
        "description": "55443456"
      }
      // If the expression throws, "error" is present instead of "result".
    },
    {
      "probe": 0,
      "event": "hit",
      "hit": 2,
      "result": {
        "type": "number",
        "value": 55574528,
        "description": "55574528"
      }
    },
    {
      "event": "completed"
      // The final entry is always a terminal event, for example:
      // 1. { "event": "completed" }
      // 2. { "event": "miss", "pending": [0, 1] }
      // 3. {
      //      "event": "timeout",
      //      "pending": [0],
      //      "error": {
      //       "code": "probe_timeout",
      //       "message": "Timed out after 30000ms waiting for probes: app.js:10"
      //      }
      //    }
      // 4. {
      //      "event": "error",
      //      "pending": [0],
      //      "error": {
      //       "code": "probe_target_exit",
      //       "exitCode": 1,
      //       "stderr": "[Error: boom]",
      //       "message": "Target exited with code 1 before probes: app.js:10"
      //      }
      //    }
    }
  ]
} 拷贝

监视器#>

🌐 Watchers

在调试时可以查看表达式和变量的值。在每个断点处，监视器列表中的每个表达式都会在当前上下文中进行求值，并在断点的源代码列表之前立即显示。

🌐 It is possible to watch expression and variable values while debugging. On every breakpoint, each expression from the watchers list will be evaluated in the current context and displayed immediately before the breakpoint's source code listing.

要开始观察一个表达式，输入 watch('my_expression')。命令 watchers 会显示当前有效的观察者。要移除一个观察者，输入 unwatch('my_expression')。

🌐 To begin watching an expression, type watch('my_expression'). The command watchers will print the active watchers. To remove a watcher, type unwatch('my_expression').

命令参考资料#>

🌐 Command reference

步进#>

🌐 Stepping

• cont，c：继续执行
• next，n：执行下一步
• step，s：步骤
• out，o：走出去
• pause：暂停运行代码（类似开发者工具中的暂停按钮）

断点#>

🌐 Breakpoints

• setBreakpoint()，sb()：在当前行设置断点
• setBreakpoint(line)、sb(line)：在特定行设置断点
• setBreakpoint('fn()')、sb(...)：在函数体的第一条语句上设置断点
• setBreakpoint('script.js', 1)，sb(...)：在 script.js 的第一行设置断点
• setBreakpoint('script.js', 1, 'num < 4')，sb(...)：在 script.js 的第一行设置条件断点，只有当 num < 4 计算结果为 true 时才会中断
• clearBreakpoint('script.js', 1)，cb(...)：清除 script.js 第 1 行的断点

也可以在尚未加载的文件（模块）中设置断点：

🌐 It is also possible to set a breakpoint in a file (module) that is not loaded yet:

$ node inspect main.js
< Debugger listening on ws://127.0.0.1:9229/48a5b28a-550c-471b-b5e1-d13dd7165df9
< For help, see: https://nodejs.cn/learn/getting-started/debugging
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
<
Break on start in main.js:1
> 1 const mod = require('./mod.js');
  2 mod.hello();
  3 mod.hello();
debug> setBreakpoint('mod.js', 22)
Warning: script 'mod.js' was not loaded yet.
debug> c
break in mod.js:22
 20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 21
>22 exports.hello = function() {
 23   return 'hello from module';
 24 };
debug> 拷贝

也可以设置一个条件断点，仅当给定表达式计算结果为 true 时才会中断：

🌐 It is also possible to set a conditional breakpoint that only breaks when a given expression evaluates to true:

$ node inspect main.js
< Debugger listening on ws://127.0.0.1:9229/ce24daa8-3816-44d4-b8ab-8273c8a66d35
< For help, see: https://nodejs.cn/learn/getting-started/debugging
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
Break on start in main.js:7
  5 }
  6
> 7 addOne(10);
  8 addOne(-1);
  9
debug> setBreakpoint('main.js', 4, 'num < 0')
  1 'use strict';
  2
  3 function addOne(num) {
> 4   return num + 1;
  5 }
  6
  7 addOne(10);
  8 addOne(-1);
  9
debug> cont
break in main.js:4
  2
  3 function addOne(num) {
> 4   return num + 1;
  5 }
  6
debug> exec('num')
-1
debug> 拷贝

信息#>

🌐 Information

• backtrace，bt：打印当前执行帧的回溯
• list(5)：列出脚本源代码及其上下文（前后各5行）
• watch(expr)：将表达式添加到监视列表
• unwatch(expr)：从观察列表中移除表情
• unwatch(index)：从监视列表中移除特定索引的表达式
• watchers：列出所有观察者及其值（在每个断点自动列出）
• repl：在调试脚本的上下文中打开调试器的 REPL 进行评估
• exec expr，p expr：在调试脚本的上下文中执行一个表达式并打印其值
• profile：开始 CPU 性能分析会话
• profileEnd：停止当前的 CPU 分析会话
• profiles：列出所有已完成的 CPU 分析会话
• profiles[n].save(filepath = 'node.cpuprofile')：将 CPU 分析会话保存为 JSON 文件到磁盘
• takeHeapSnapshot(filepath = 'node.heapsnapshot')：拍摄堆快照并以 JSON 格式保存到磁盘

执行控制#>

🌐 Execution control

• run：运行脚本（在调试器启动时自动运行）
• restart：重启脚本
• kill：结束脚本

其他#>

🌐 Various

• scripts：列出所有已加载的脚本
• version：显示 V8 的版本

高级用法#>

🌐 Advanced usage

Node.js 的 V8 检查器集成#>

🌐 V8 inspector integration for Node.js

V8 Inspector 集成允许将 Chrome DevTools 附加到 Node.js 实例以进行调试和分析。它使用 Chrome 开发者工具协议。

🌐 V8 Inspector integration allows attaching Chrome DevTools to Node.js instances for debugging and profiling. It uses the Chrome DevTools Protocol.

可以通过在启动 Node.js 应用时传递 --inspect 标志来启用 V8 Inspector。也可以通过该标志指定自定义端口，例如 --inspect=9222 将在端口 9222 上接受 DevTools 连接。

🌐 V8 Inspector can be enabled by passing the --inspect flag when starting a Node.js application. It is also possible to supply a custom port with that flag, e.g. --inspect=9222 will accept DevTools connections on port 9222.

使用 --inspect 标志会在调试器连接之前立即执行代码。这意味着代码会在你开始调试之前就开始运行，如果你想从一开始就进行调试，这可能不太理想。

🌐 Using the --inspect flag will execute the code immediately before debugger is connected. This means that the code will start running before you can start debugging, which might not be ideal if you want to debug from the very beginning.

在这种情况下，你有两种选择：

🌐 In such cases, you have two alternatives:

1. --inspect-wait 标志：这个标志会在执行代码前等待调试器附加。这使你可以从执行开始就进行调试。
2. --inspect-brk 标志：与 --inspect 不同，这个标志会在调试器附加后立即在代码的第一行中断。这在你希望从一开始就逐步调试代码，而不在调试前执行任何代码时非常有用。

因此，在决定使用 --inspect、--inspect-wait 还是 --inspect-brk 时，需要考虑你是希望代码立即开始执行、在执行前等待调试器附加，还是在第一行就中断以进行逐步调试。

🌐 So, when deciding between --inspect, --inspect-wait, and --inspect-brk, consider whether you want the code to start executing immediately, wait for debugger to be attached before execution, or break on the first line for step-by-step debugging.

$ node --inspect index.js
Debugger listening on ws://127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29
For help, see: https://nodejs.cn/learn/getting-started/debugging 拷贝

（在上面的示例中，URL 末尾的 UUID dc9010dd-f8b8-4ac5-a510-c1a114ec7d29 是动态生成的，在不同的调试会话中会有所不同。）