NodeJS官方文档中文版之《代码调试入门指南》

代码调试指南

本篇指南将教你如何调试Node.js应用程序和代码.

开启检查器

注意: --inspect 选项和检查器协议都是实验性的, 它们将来可能会被更改.

如果运行程序时开启了 –inspect 开关, Node.js进程会通过WebSocket监听那些由 检查器协议 定义的诊断命令, 默认情况下地址和端口是127.0.0.1:9229. 每个进程会被分配一个唯一的UUID(即通用唯一识别码, 此处的UUID形如: 0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e).

检查器客户端必须知道并指定地址, 端口和UUID以连接到WebSocket接口. 完整URL为 ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e, 当然, 实际的URL要取决于实际的地址, 端口和UUID.

检查器带有一个HTTP终端用于处理被调试程序的元数据, 包括WebSocket URL, UUID和Chrome DevTools URL(Chrome DevTools指Chrome浏览器的开发者工具, 因为是个专有名词, 就不单独翻译了). 想获取到元数据, 要先发送一个HTTP请求到 http://[host:port]/json/list, 会获取到一个形式如下的JSON对象; 然后用 webSocketDebuggerUrl 字段值作为URL直接连接检查器.

{
  "description": "node.js instance",
  "devtoolsFrontendUrl": "chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e",
  "faviconUrl": "https://nodejs.org/static/favicon.ico",
  "id": "0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e",
  "title": "node",
  "type": "node",
  "url": "file://",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e"
}

对于一个在启动时没有使用 --inspect 的Node.js进程, 我们可以向它发送 SIGUSR1 信号使它开始监听调试信息(在Linux和OS X上可以这么做). 这种发送信号的方式, 在Node 7中会激活遗留的调试器API; 在Node 8及以后版本中会激活检查器API.

检查器客户端

有几款商业性的和开源的工具可以连接到Node的检查器.

node-inspect

• 一款由Node.js基金会支持的, 使用 检查器协议 的命令行调试器.

• 有一个版本和Node绑定在一起了, 执行 node inspect myscript.js 即可使用.

• 最新版本可以独立安装(例如使用 npm install -g node-inspect), 执行 node-inspect myscript.js 即可使用.

Chrome DevTools 55+

• 选项1: 在基于Chromium内核的浏览器中访问 chrome://inspect. 点击”Configure”按钮, 确保你需要的地址和端口已经在列.

• 选项2: 复制 /json/list 的输出内容(上文提到过的JSON对象)中的 devtoolsFrontendUrl, 或复制 “–inspect” 粘贴到Chrome中.

• 选项3: 安装NIM(Node Inspector Manager)这款Chorme插件:
  https://chrome.google.com/webstore/detail/nim-node-inspector-manage/gnhhdgbaldcilmgcpfddgdbkhjohddkj

VS Code 1.10+

• 在调试面板中点击设置图标, 打开 .vscode/launch.json. 选择”Node.js”进行初始化设置.

JetBrains WebStorm 2017.1+ 或其他 JetBrains IDE

• 创建一个新的Node.js调试选项并点击调试. Node.js 7+版本中会默认使用 --inspect. 如果想禁用, 在IDE注册表的 js.debugger.node.use.inspect 取消勾选即可.

chrome-remote-interface

• 这个库简化了对检查器协议终端的连接操作.

命令行选项

下面列出了各种调试相关的flag的作用.

–inspect

• 启用检查器
• 在默认地址和端口(127.0.0.1:9229)监听

–inspect=[host:port]

• 启用检查器
• 将地址绑定到 host (默认为: 127.0.0.1)
• 监听 port 端口 (默认为: 9229)

–inspect-brk

• 启用检查器
• 在默认地址和端口(127.0.0.1:9229)监听
• 在用户代码开始执行前停止检查器

–inspect-brk=[host:port]

• 启用检查器
• 将地址绑定到 host (默认为: 127.0.0.1)
• 监听 port 端口 (默认为: 9229)
• 在用户代码开始执行前停止检查器

node inspect script.js

• 在有 “–inspect” 标记时会生成子进程来运行用户代码, 用主进程运行命令行调试器.

遗留的调试器

自Node 7.7.0以来, 遗留的调试器就被废弃了. 请使用 –inspect 和检查器来代替.

在Node 7或更早版本中, 如果使用了 –debug 或 –debug-brk 标记, Node.js会在一个TCP端口(默认为5858)上监听调试命令, 这些调试命令是由”V8 Debugging Protocol(V8调试协议, 此协议现已不再使用)”定义的. 凡是遵循此协议的调试器客户端都可以连接并调试正在运行的Node进程; 下面列举两个比较流行的调试器.

注意: V8调试协议已经不再维护了.

内置调试器

执行 node debug script_name.js 可以使你的代码在Node内置的命令行调试器下运行. 你的代码会运行在另一个由 --debug-brk 选项启动的Node进程中, 而最初的那个Node进程会执行 _debugger.js 的代码并连接到你要调试的代码.

node-inspector

用Chrome DevTools调试你的Node.js代码, 并通过一个中间进程将Chromium使用的”Inspector Protocol(检查器协议)”转换为Node.js使用的”V8 Debugger protocol(V8调试器协议)”