Debugging Guide【译文】

原文：https://nodejs.org/en/docs/guides/debugging-getting-started/

Debugging Guide 调试指导

This guide will help you get started debugging your Node.js apps and scripts.

本指南将帮助您开始调试Node.js应用程序和脚本。

Enable Inspector 启用检查器

When started with the --inspect switch, a Node.js process listens for a debugging client. By default, it will listen at host and port 127.0.0.1:9229. Each process is also assigned a unique UUID.

从--inspect开关开始时，Node.js进程侦听调试客户机。默认情况下，它将在主机和端口127.0.0.1:9229监听。每个进程还被分配一个唯一的UUID。

Inspector clients must know and specify host address, port, and UUID to connect. A full URL will look something like ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.

检查器客户端必须知道并指定要连接的主机地址、端口和UUID。完整的URL将类似于ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e。

Node.js will also start listening for debugging messages if it receives a SIGUSR1 signal. (SIGUSR1 is not available on Windows.) In Node.js 7 and earlier, this activates the legacy Debugger API. In Node.js 8 and later, it will activate the Inspector API.

如果Node.js接收到SIGUSR1信号，它也会开始监听调试消息。(SIGUSR1在Windows上不可用。)在Node.js 7和更早的版本中，这将激活遗留调试器API。在Node.js 8和更高版本中，它将激活Inspector API。

---

Security Implications 安全影响

Since the debugger has full access to the Node.js execution environment, a malicious actor able to connect to this port may be able to execute arbitrary code on behalf of the Node process. It is important to understand the security implications of exposing the debugger port on public and private networks.

由于调试器可以完全访问Node.js执行环境，因此能够连接到该端口的恶意参与者可能能够代表节点进程执行任意代码。理解在公共网络和私有网络上公开调试器端口的安全含义非常重要。

Exposing the debug port publicly is unsafe 公开调试端口是不安全的

If the debugger is bound to a public IP address, or to 0.0.0.0, any clients that can reach your IP address will be able to connect to the debugger without any restriction and will be able to run arbitrary code.

如果调试器被绑定到一个公共IP地址，或者绑定到0.0.0.0，那么任何能够到达您的IP地址的客户机都能够不受任何限制地连接到调试器，并且能够运行任意代码。

By default node --inspect binds to 127.0.0.1. You explicitly need to provide a public IP address or 0.0.0.0, etc., if you intend to allow external connections to the debugger. Doing so may expose you a potentially significant security threat. We suggest you ensure appropriate firewalls and access controls in place to prevent a security exposure.

默认节点--inspect绑定到127.0.0.1。如果要允许外部连接到调试器，则显式地需要提供公共IP地址或0.0.0.0等。这样做可能会给您带来潜在的重大安全威胁。我们建议您确保适当的防火墙和访问控制到位，以防止安全暴露。

See the section on 'Enabling remote debugging scenarios' on some advice on how to safely allow remote debugger clients to connect.

有关如何安全地允许远程调试器客户机连接的一些建议，请参阅“启用远程调试场景”一节。

Local applications have full access to the inspector 本地应用程序可以完全访问检查器

Even if you bind the inspector port to 127.0.0.1 (the default), any applications running locally on your machine will have unrestricted access. This is by design to allow local debuggers to be able to attach conveniently.

即使将inspector端口绑定到127.0.0.1(默认值)，在计算机上本地运行的任何应用程序都将具有无限制的访问权限。这在设计上是为了让本地调试器能够方便地附加。

Browsers, WebSockets and same-origin policy 浏览器、WebSockets和同源策略

Websites open in a web-browser can make WebSocket and HTTP requests under the browser security model. An initial HTTP connection is necessary to obtain a unique debugger session id. The same-origin-policy prevents websites from being able to make this HTTP connection. For additional security against DNS rebinding attacks, Node.js verifies that the 'Host' headers for the connection either specify an IP address or localhostor localhost6 precisely.

在浏览器中打开的网站可以在浏览器安全模型下发出WebSocket和HTTP请求。初始HTTP连接是获得唯一调试器会话id所必需的。同源策略阻止网站能够进行此HTTP连接。为了防止DNS重绑定攻击的额外安全性，Node.js验证连接的“主机”报头是否准确地指定了IP地址或localhostor localhost6。

These security policies disallow connecting to a remote debug server by specifying the hostname. You can work-around this restriction by specifying either the IP address or by using ssh tunnels as described below.

这些安全策略不允许通过指定主机名连接到远程调试服务器。您可以通过指定IP地址或使用下面描述的ssh隧道来解决这个限制。

Inspector Clients 检查器客户端

Several commercial and open source tools can connect to Node's Inspector. Basic info on these follows:

node-inspect 

• CLI Debugger supported by the Node.js Foundation which uses the Inspector Protocol. 由使用Inspector协议的Node.js Foundation支持的CLI调试器。
• A version is bundled with Node and can be used with node inspect myscript.js. 版本与Node绑定，可以与Node inspect myscript.js一起使用。
• The latest version can also be installed independently (e.g. npm install -g node-inspect) and used with node-inspect myscript.js. 最新版本也可以独立安装(例如npm install -g node-inspect)，并与node-inspect myscript.js一起使用。

Chrome DevTools 55+

• Option 1: Open chrome://inspect in a Chromium-based browser. Click the Configure button and ensure your target host and port are listed.
• Option 2: Copy the devtoolsFrontendUrl from the output of /json/list (see above) or the --inspect hint text and paste into Chrome.
• Option 3: Install the Chrome Extension NIM (Node Inspector Manager):
  https://chrome.google.com/webstore/detail/nim-node-inspector-manage/gnhhdgbaldcilmgcpfddgdbkhjohddkj

选项1: 在基于chrome的浏览器中打开chrome://inspect。单击Configure按钮并确保列出了目标主机和端口。
选项2: 从/json/list的输出中复制devtoolsFrontendUrl(见上面)，或者--inspect提示文本并粘贴到Chrome中。
选项3: 安装Chrome扩展NIM(节点检查器管理器):https://chrome.google.com/webstore/detail/nim-node-inspector-manage/gnhhdgbaldcilmgcpfddgdbkhjohddkj

Visual Studio Code 1.10+

• In the Debug panel, click the settings icon to open .vscode/launch.json. Select "Node.js" for initial setup.    在Debug面板中，单击settings图标打开.vscode/launch.json。选择“节点。初始设置。

Visual Studio 2017

• Choose "Debug > Start Debugging" from the menu or hit F5. 从菜单中开始调试，或者按F5。
• Detailed instructions.

JetBrains WebStorm 2017.1+ and other JetBrains IDEs

• Create a new Node.js debug configuration and hit Debug. --inspect will be used by default for Node.js 7+. To disable uncheck js.debugger.node.use.inspect in the IDE Registry.   
  创建一个新的Node.js调试配置并点击debug。--inspect默认用于Node.js 7+。要禁用取消选中js.debug .node.use.inspect在IDE注册表中。

chrome-remote-interface

• Library to ease connections to Inspector Protocol endpoints.
  库来简化与Inspector协议端点的连接。

Gitpod

• Start a Node.js debug configuration from the Debug view or hit F5. Detailed instructions
    从debug视图中启动Node.js调试配置，或者单击F5

---

Command-line options   命令行选项

The following table lists the impact of various runtime flags on debugging:

下表列出了各种运行时标志对调试的影响:

Flag	Meaning
--inspect	Enable inspector agent 启动检查器 Listen on default address and port (127.0.0.1:9229) 监听默认地址和端口
--inspect=[host:port]	Enable inspector agent 启动检查器 Bind to address or hostname host (default: 127.0.0.1) 绑定地址或者域名 Listen on port port (default: 9229) 监听端口
--inspect-brk	Enable inspector agent 启动检查器 Listen on default address and port (127.0.0.1:9229) 监听默认地址和端口 Break before user code starts 在用户代码开始之前中断
--inspect-brk=[host:port]	Enable inspector agent 启动检查器 Bind to address or hostname host (default: 127.0.0.1) 监听默认地址 Listen on port port (default: 9229) 监听端口 Break before user code starts 在用户代码开始之前中断
node inspect script.js	Spawn child process to run user's script under --inspect flag; and use main process to run CLI debugger. 生成子进程，在--inspect标志下运行用户脚本;并使用主进程运行CLI调试器。
node inspect --port=xxxx script.js	Spawn child process to run user's script under --inspect flag; and use main process to run CLI debugger. 生成子进程，在--inspect标志下运行用户脚本;并使用主进程运行CLI调试器。 Listen on port port (default: 9229)

---

Enabling remote debugging scenarios 启用远程调试场景

We recommend that you never have the debugger listen on a public IP address. If you need to allow remote debugging connections we recommend the use of ssh tunnels instead. We provide the following example for illustrative purposes only. Please understand the security risk of allowing remote access to a privileged service before proceeding.

我们建议您永远不要让调试器监听公共IP地址。如果需要允许远程调试连接，我们建议使用ssh隧道。我们提供以下示例只是为了说明。在继续之前，请了解允许远程访问特权服务的安全风险。

Let's say you are running Node on remote machine, remote.example.com, that you want to be able to debug. On that machine, you should start the node process with the inspector listening only to localhost (the default).

假设您在希望能够调试的远程机器remote.example.com上运行Node。在那台机器上，应该启动节点进程，检查器只监听本地主机(默认情况)。

$ node --inspect server.js

Now, on your local machine from where you want to initiate a debug client connection, you can setup an ssh tunnel:

现在，在您希望启动调试客户机连接的本地机器上，您可以设置ssh隧道:

$ ssh -L 9221:localhost:9229 user@remote.example.com

This starts a ssh tunnel session where a connection to port 9221 on your local machine will be forwarded to port 9229 on remote.example.com. You can now attach a debugger such as Chrome DevTools or Visual Studio Code to localhost:9221, which should be able to debug as if the Node.js application was running locally.

这将启动ssh隧道会话，其中本地机器上到端口9221的连接将被转发到remote.example.com上的端口9229。现在可以将诸如Chrome DevTools或Visual Studio代码之类的调试器附加到localhost:9221，它应该能够像本地运行Node.js应用程序那样进行调试。

---

Legacy Debugger 遗留的调试器

The legacy debugger has been deprecated as of Node 7.7.0. Please use --inspect and Inspector instead.

从节点7.7.0开始，遗留调试器已被弃用。请使用--inspection and Inspector代替。

When started with the --debug or --debug-brk switches in version 7 and earlier, Node.js listens for debugging commands defined by the discontinued V8 Debugging Protocol on a TCP port, by default 5858. Any debugger client which speaks this protocol can connect to and debug the running process; a couple popular ones are listed below.

在版本7和更早版本中，当开始使用--debug或--debug-brk开关时，Node.js监听TCP端口上停止的V8调试协议定义的调试命令，默认情况下是5858。任何使用此协议的调试器客户机都可以连接并调试正在运行的进程;下面列出了几个流行的例子。

The V8 Debugging Protocol is no longer maintained or documented.

V8调试协议不再得到维护或文档化。

Built-in Debugger

Start node debug script_name.js to start your script under Node's builtin command-line debugger. Your script starts in another Node process started with the --debug-brk option, and the initial Node process runs the _debugger.js script and connects to your target.

启动节点调试script_name.js，以在节点的内置命令行调试器下启动脚本。脚本在另一个节点进程中启动，该节点进程使用——debug-brk选项启动，初始节点进程运行_debug .js脚本并连接到目标。

node-inspector

Debug your Node.js app with Chrome DevTools by using an intermediary process which translates the Inspector Protocol used in Chromium to the V8 Debugger protocol used in Node.js.

使用一个中间进程，将Chromium中使用的Inspector协议转换为Node.js中使用的V8调试器协议，用Chrome DevTools调试你的Node.js应用程序。