Node.js v18.20.8 文档

调试器#>

【Debugger】

稳定性： 2 - 稳定

Node.js 包含一个命令行调试工具。Node.js 调试器客户端并不是一个功能齐全的调试器，但可以进行简单的逐步执行和检查。

【Node.js includes a command-line debugging utility. The Node.js debugger client is not a full-featured debugger, but simple stepping and inspection are possible.】

要使用它，请使用 inspect 参数启动 Node.js，然后跟上要调试的脚本路径。

【To use it, start Node.js with the inspect argument followed by the path to the script to debug.】

$ node inspect myscript.js
< Debugger listening on ws://127.0.0.1:9229/621111f9-ffcb-4e82-b718-48a145fa5db8
< For help, see: https://nodejs.cn/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
<
 ok
Break on start in myscript.js:2
  1 // myscript.js
> 2 global.x = 5;
  3 setTimeout(() => {
  4   debugger;
debug>

调试器会自动在第一个可执行行处中断。若希望运行到第一个断点（由 debugger 语句指定），请将环境变量 NODE_INSPECT_RESUME_ON_START 设置为 1。

【The debugger automatically breaks on the first executable line. To instead run until the first breakpoint (specified by a debugger statement), set the NODE_INSPECT_RESUME_ON_START environment variable to 1.】

$ cat myscript.js
// myscript.js
global.x = 5;
setTimeout(() => {
  debugger;
  console.log('world');
}, 1000);
console.log('hello');
$ NODE_INSPECT_RESUME_ON_START=1 node inspect myscript.js
< Debugger listening on ws://127.0.0.1:9229/f1ed133e-7876-495b-83ae-c32c6fc319c2
< For help, see: https://nodejs.cn/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
<
< hello
<
break in myscript.js:4
  2 global.x = 5;
  3 setTimeout(() => {
> 4   debugger;
  5   console.log('world');
  6 }, 1000);
debug> next
break in myscript.js:5
  3 setTimeout(() => {
  4   debugger;
> 5   console.log('world');
  6 }, 1000);
  7 console.log('hello');
debug> repl
Press Ctrl+C to leave debug repl
> x
5
> 2 + 2
4
debug> next
< world
<
break in myscript.js:6
  4   debugger;
  5   console.log('world');
> 6 }, 1000);
  7 console.log('hello');
  8
debug> .exit
$

repl 命令允许远程评估代码。next 命令会执行到下一行。输入 help 查看其他可用命令。

【The repl command allows code to be evaluated remotely. The next command steps to the next line. Type help to see what other commands are available.】

在未输入命令而按下 enter 时，将会重复上一条调试命令。

【Pressing enter without typing a command will repeat the previous debugger command.】

监视器#>

【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/docs/inspector
<
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/docs/inspector
<
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行上下文（前后各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-brk 标志，而不是 --inspect。

【To break on the first line of the application code, pass the --inspect-brk flag instead of --inspect.】

$ node --inspect index.js
Debugger listening on ws://127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29
For help, see: https://nodejs.cn/docs/inspector

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

如果 Chrome 浏览器版本低于 66.0.3345.0，请在上述 URL 中使用 inspector.html 而不是 js_app.html。

【If the Chrome browser is older than 66.0.3345.0, use inspector.html instead of js_app.html in the above URL.】

Chrome 开发者工具尚不支持调试 工作线程。可以使用 ndb 来调试它们。

【Chrome DevTools doesn't support debugging worker threads yet. ndb can be used to debug them.】

Node.js 中文网 - 粤ICP备13048890号