npm debug指南

1. 前言

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

2. 开启npm debug

开启npm debug的方式有多种.

1, 如果是使用node运行脚本, 那么在node后面加上–inspect选项即可开启debug模式.

2, 如果是使用npm运行run-script, 而且run-script中不包含node命令, 则可以使用–node-options=–inspect选项, 例如

npm run buildDev --node-options=--inspect

当使用–inspect开关启动时，Node.js进程会侦听调试客户端。默认情况下，它将在主机和端口127.0.0.1:9229上侦听。每个进程还被分配了一个唯一的UUID。
调试客户端必须知道并指定要连接的主机地址、端口和UUID。完整的URL看起来像ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e。
如果Node.js接收到SIGUSR1信号，它也将开始监听调试消息。（SIGUSR1在Windows上不可用。）在Node.js 7和更早版本中，这将激活旧版debug API。在Node.js 8及更高版本中，它将激活Inspector API。

3. 安全影响

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

如果调试器绑定到公网IP地址或0.0.0.0，则可以访问您的IP地址的任何客户端都可以无任何限制地连接到调试器，并且可以运行任意代码。
默认情况下，节点–inspect绑定到127.0.0.1。如果您打算允许外部连接到调试器，则明确需要提供公共IP地址或0.0.0.0等。这样做可能会使您面临潜在的重大安全威胁。我们建议您确保适当的防火墙和访问控制措施到位，以防止安全暴露。
有关如何安全地允许远程调试器客户端连接的一些建议，请参阅“启用远程调试方案”一节。

即使您将inspector端口绑定到127.0.0.1（默认值），在您的计算机上本地运行的任何应用程序都将具有不受限制的访问权限。这是为了让本地调试器能够方便地连接。

4. 浏览器、WebSockets和同源策略

初始HTTP连接是获得唯一debugger session id所必需的。同源策略阻止网站建立此HTTP连接。为了增强抵御DNS重新绑定攻击的安全性，Node.js验证连接的http “Host”头部信息是否精确指定了IP地址或localhost。
这些安全策略禁止通过主机名连接到远程调试服务器。您可以通过指定IP地址或使用ssh隧道来绕过此限制。

5. debug客户端连接

虽然正规的名称叫inspector客户端, 但是我还是比较喜欢debug客户端这个名词, 因为不用引入额外的概念, debug客户端非常容易理解不用做过多解释.

debug客户端有多种, 例如: Chrome DevTools 55+, Microsoft Edge, Visual Studio Code 1.10+, Visual Studio 2017+, JetBrains WebStorm 和其它 JetBrains IDEs, chrome-remote-interface, Gitpod, Eclipse IDE with Eclipse Wild Web Developer extension.

这里重点介绍如何使用Chrome DevTools进行debug 和vscode.

5.1. Chrome DevTools进行npm debug

首先打开Chrome, 在输入网址的输入框中输入chrome://inspect, 然后点击Open dedicated DevTools for Node对话框, 在source tab页将要debug的包含源文件的文件夹添加到workspace, 设置好断点.

然后按前面介绍的开启npm debug的方式启动npm, 然后回到chrome://inspect界面, npm一旦启动会自动与Chrome DevTools建立连接. 当程序运行到断点位置会自动停下来, 后面就是我们熟悉的debug的过程了, 这里不做过多解释了.

以下是一些注意事项:
在将源代码文件夹添加到workspace时, devtools将会依照以下规则将一些文件夹过滤掉

/node_modules/|/bower_components/|/\.devtools|/\.git/|/\.sass-cache/|/\.hg/|/\.idea/|/\.svn/|/\.cache/|/\.project/|/Thumbs.db$|/ehthumbs.db$|/Desktop.ini$|/\$RECYCLE.BIN/

有时候第三方依赖包我们也需要debug, 此时可以导航到devtools=>settings 的workspace tab页将folder exclude pattern修改掉, 这样我们就可以node_modules下面的package了.
更多设置请参考https://developer.chrome.com/docs/devtools/settings

5.1.1. vscode npm debug

打开vscode左侧 run and debug视图, 点击左上方 run and debug下拉列表. 选中 add config (your project),
或者用文本编辑器在项目的.vscode/launch.json文件中添加如下内容.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "My Backend",
            "command": "npm run buildDev",
            "request": "launch",
            "type": "node-terminal"
        }
    ]
}

注意: 将command替换为合适的command
commands 可以在 package.json 的 “scripts” 节点找到

设置断点, 点击开始debug按钮(绿色三角图标)

6. Nodejs 系列文章

最新更新以及更多Nodejs相关文章请访问 鹏叔的技术博客 - Nodejs

7. 参考文档

debugging gettingstarted