调试 Node.js
本指南将帮助您开始调试 Node.js 应用程序和脚本。
启用 Inspector
使用 --inspect 开关启动时，Node.js 进程会监听调试客户端。默认情况下，它将在主机和端口 127.0.0.1:9229 上监听。每个进程还会分配一个唯一的 UUID。
Inspector 客户端必须知道并指定主机地址、端口和 UUID 才能连接。完整的 URL 将类似于 ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e。
如果 Node.js 接收 SIGUSR1 信号，它也会开始监听调试消息。（SIGUSR1 在 Windows 上不可用。）在 Node.js 7 及更早版本中，这会激活旧版 Debugger API。在 Node.js 8 及更高版本中，它将激活 Inspector API。
安全隐患
由于调试器可以完全访问 Node.js 执行环境，因此能够连接到此端口的恶意攻击者可能能够代表 Node.js 进程执行任意代码。了解在公共和私有网络上公开调试器端口的安全隐患非常重要。
公开调试端口是不安全的
如果调试器绑定到公共 IP 地址或 0.0.0.0，任何可以访问您 IP 地址的客户端都可以在没有任何限制的情况下连接到调试器，并可以运行任意代码。
默认情况下，node --inspect 绑定到 127.0.0.1。如果您打算允许外部连接到调试器，则需要显式提供公共 IP 地址或 0.0.0.0 等。这样做可能会使您面临潜在的重大安全威胁。我们建议您确保适当的防火墙和访问控制到位，以防止安全漏洞。
有关如何安全地允许远程调试器客户端连接的建议，请参阅“启用远程调试场景”部分。
本地应用程序可以完全访问检查器
即使您将检查器端口绑定到 127.0.0.1（默认值），在您的机器上本地运行的任何应用程序都将拥有不受限制的访问权限。这是为了让本地调试器能够方便地附加而设计的。
浏览器、WebSockets 和同源策略
在 Web 浏览器中打开的网站可以在浏览器安全模型下进行 WebSocket 和 HTTP 请求。需要进行初始 HTTP 连接才能获取唯一的调试器会话 ID。同源策略阻止网站进行此 HTTP 连接。为了进一步防止 DNS 重绑定攻击，Node.js 验证连接的“Host”标头是否精确地指定了 IP 地址或 localhost。
这些安全策略不允许通过指定主机名连接到远程调试服务器。您可以通过指定 IP 地址或使用下面描述的 ssh 隧道来解决此限制。
检查器客户端
node inspect myscript.js 提供了一个最小的 CLI 调试器。许多商业和开源工具也可以连接到 Node.js 检查器。
Chrome DevTools 55+，Microsoft Edge
- 选项 1：在基于 Chromium 的浏览器中打开
chrome://inspect或在 Edge 中打开edge://inspect。单击“配置”按钮，并确保您的目标主机和端口已列出。 - 选项 2：从
/json/list（见上文）的输出或 --inspect 提示文本中复制devtoolsFrontendUrl，并将其粘贴到 Chrome 中。
请注意，Node.js 和 Chrome 需要在同一平台上运行。
Visual Studio Code 1.10+
- 在“调试”面板中，单击设置图标以打开
.vscode/launch.json。选择“Node.js”进行初始设置。
Visual Studio 2017+
- 从菜单中选择“调试 > 开始调试”或按 F5。
- 详细说明.
JetBrains WebStorm 和其他 JetBrains IDE
- 创建一个新的 Node.js 调试配置并点击调试。
--inspect将默认用于 Node.js 7+。要禁用，请在 IDE 注册表中取消选中js.debugger.node.use.inspect。要了解有关在 WebStorm 和其他 JetBrains IDE 中运行和调试 Node.js 的更多信息，请查看 WebStorm 在线帮助。
chrome-remote-interface
- 库，用于简化与 Inspector Protocol 端点的连接。
Gitpod
- 从
Debug视图启动 Node.js 调试配置或按F5。 详细说明
Eclipse IDE 与 Eclipse Wild Web Developer 扩展
- 从 .js 文件中，选择“调试方式... > Node 程序”，或
- 创建一个调试配置以将调试器附加到正在运行的 Node.js 应用程序（已使用
--inspect启动）。
命令行选项
下表列出了各种运行时标志对调试的影响
| 标志 | 含义 |
|---|---|
| --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 标志下运行用户的脚本；并使用主进程运行 CLI 调试器。 |
| node inspect --port=xxxx script.js | 生成子进程以在 --inspect 标志下运行用户的脚本；并使用主进程运行 CLI 调试器。在端口 port（默认：9229）上监听 |
启用远程调试场景
我们建议您永远不要让调试器监听公共 IP 地址。如果您需要允许远程调试连接，我们建议使用 ssh 隧道。我们仅出于说明目的提供以下示例。在继续之前，请了解允许远程访问特权服务的安全风险。
假设您在远程机器 remote.example.com 上运行 Node.js，并且您希望能够调试它。在那台机器上，您应该启动 node 进程，并让检查器只监听 localhost（默认值）。
node --inspect server.js
现在，在您要启动调试客户端连接的本地机器上，您可以设置一个 ssh 隧道
ssh -L 9221:localhost:9229 [email protected]
这将启动一个 ssh 隧道会话，其中本地机器上端口 9221 的连接将被转发到 remote.example.com 上的端口 9229。现在，您可以将 Chrome DevTools 或 Visual Studio Code 等调试器附加到 localhost:9221，它应该能够像 Node.js 应用程序在本地运行一样进行调试。
传统调试器
从 Node.js 7.7.0 开始，传统调试器已弃用。请使用 --inspect 和 Inspector。
在版本 7 及更早版本中使用 **--debug** 或 **--debug-brk** 开关启动时，Node.js 会监听由已停产的 V8 调试协议定义的调试命令，默认情况下为 5858 端口。任何使用此协议的调试器客户端都可以连接并调试正在运行的进程；下面列出了几个流行的调试器客户端。
V8 调试协议不再维护或记录。
内置调试器
启动 node debug script_name.js 以在内置命令行调试器下启动您的脚本。您的脚本在使用 --debug-brk 选项启动的另一个 Node.js 进程中启动，并且初始 Node.js 进程运行 _debugger.js 脚本并连接到您的目标。
node-inspector
通过使用将 Chromium 中使用的 Inspector 协议 转换为 Node.js 中使用的 V8 调试器协议的中介进程，使用 Chrome DevTools 调试您的 Node.js 应用程序。