查看原文
其他

Node.js 项目调试指南

脚本之家 2023-07-16

The following article is from code秘密花园 Author ConardLi译

 脚本之家 设为“星标
第一时间收到文章更新

出处:code秘密花园(ID:ConardLi
如若转载请联系原公众号

Node.js 是一种流行的 JavaScript 运行时,与谷歌 Chrome 浏览器使用相同的 V8 引擎。它是跨平台的,在创建 Web 服务器、构建工具、命令行工具等方面越来越受欢迎。

但是,在我们编写代码并运行它之后,如果出现问题,事情就不会那么清楚了。如果幸运的话,你的代码可能会崩溃并显示一条明显的错误消息。如果你不走运,你的应用程序还是能运行的,但是最后的结果就不尽人意了。

什么是调试?

调试是修复软件 Bug 的艺术。修复 Bug 通常很简单,更正一个字符或编辑一段代码就可能解决了问题。但是找到 Bug 的原因就是另一回事来,开发人员通常会花费非常多的时间来查找问题的根源。

有一些方法可以尽可能的避免 Bug

  • 使用具有行号、颜色编码、lint、自动补全、括号匹配、参数提示等功能的优秀代码编辑器。
  • 使用 Git 等源代码控制系统来管理代码修订。这些工具可以帮助其他人检查更新并定位错误出现的方式、时间和位置。
  • 采用 Bug 跟踪系统,例如 Jira、FogBugzBugzilla。使用这些报告 Bug 、突出重复、记录重现的步骤、确定严重性、计算优先级、分配开发人员、记录讨论和跟踪修复进度。
  • 使用测试驱动开发的模式,TDD 是一种开发模式,它鼓励开发人员在编写代码之前先编写代码来测试函数的运行情况。
  • 尝试使用代码解释或结对编程等技术与其他开发人员合作,新的眼光可能会发现你没有考虑过的问题。

没有任何解决方案可以根除所有的 Bug ,我们可能会在在所有的编程语言中遇到以下类型。

语法错误

当你的代码没有遵循语言的规则时,就会导致错误。通常,它可能是语句拼写错误或缺少括号。

VS Code 等优秀的代码编辑器有助于在我们尝试运行 Node.js 之前发现常见的 Node.js 问题:

  • 颜色编码有效和无效的描述
  • 自动补全函数和变量名
  • 突出显示匹配的括号
  • 自动缩进代码块
  • 函数、属性和方法的参数提示
  • 检测无法访问的代码
  • 重构凌乱的函数

你还可以使用 ESLint 等代码检查器来发现其他语法问题或与正常编码风格的偏差。使用以下命令将 ESLint 安装为全局 Node.js 模块:

npm i eslint -g

然后从命令行检查 JavaScript 文件:

eslint code.js

使用 ESLint for VS Code extension 会更容易,它会在你编码时验证代码:

逻辑错误

逻辑错误意味着你的代码可以正常运行但没有按预期工作。例如,用户无法使用有效的凭据登录;报告显示不正确的统计信息,用户数据未保存到数据库等。原因可能是任何原因:

  • 使用不正确的变量名
  • 使用不正确的条件,例如 if (x > 5) 而不是 if (x < 5)
  • 无效的函数、参数或算法

通常需要单步执行代码并检查执行期间特定点的状态。

运行时错误

当应用程序执行时,运行时错误变得很明显。它可能不会发生并且可能是由无效的用户输入引起的,例如

  • 试图将一个值除以零
  • 访问不再存在的数组项或数据库记录
  • 试图在没有适当访问权限的情况下写入文件
  • 不正确的异步函数实现导致“内存溢出”崩溃。

众所周知,运行时错误最难以复现,因此良好的日志记录必不可少。

Node.js 调试环境变量

操作系统中设置的环境变量可以控制 Node.js 应用程序的设置。最常见的,我们通常在调试时或在实时服务器上把 NODE_ENV 设置为 development、production

你可以在 Linux/macOS 上设置环境变量:

NODE_ENV=development

Windows(传统 DOS)命令提示符下:

set NODE_ENV=development

Windows Powershell

$env:NODE_ENV="development"

我们的应用程序可以检测环境设置并在必要时启用调试消息,例如:

// running in development mode?
const DEVMODE = (process.env.NODE_ENV === 'development');

if (DEVMODE) {
  console.log('application started in development mode');
}

NODE_DEBUG 使用 Node.js util.debuglog 启用调试消息。(下面的章节会详细讲解)。

使用 Node.js 命令行选项进行调试

你可以在启动应用程序时将命令行选项传递给 node 或运行时。nodemon 最有用的一个选项是 --trace-warnings,它在 promise 无法解决或拒绝时输出堆栈跟踪:

node --trace-warnings index.js

其他选项包括:

  • --enable-source-maps:在使用 TypeScript 等转译器时启用 SourceMap
  • --throw-deprecation: 使用不推荐使用的功能时抛出错误
  • --inspect:激活 V8 Inspector(请参阅下面的 Node.js V8 Inspector 部分)。

使用控制台日志记录进行调试

调试应用程序最简单的方法就是在执行期间将值输出到控制台:

console.log(`ConardLi: ${ myVariable }`);

一些开发人员声称你永远不应该使用 console.log(), 因为这样会变更代码,并且存在更好的调试选项。但我还是认为控制台打印日志记录是一种更快速实用的选择,查找和修复错误比你使用的查找方法更重要。我们还应该考虑使用 console.log() 之外的其他方法:

console.log() 接受逗号分隔的值列表。例如:

let x = 17;
console.log('x:', x);
// x: 17

使用 ES6 解构也可以提供类似的输出:

console.log({ x });
// { x: 123 }

util.inspect 可以格式化对象以便于阅读,console.dir() 会为你完成更复杂的工作:

console.dir(myObject, { depth: null, color: true });

使用 Node.js util.debuglog 进行调试

Node.js 标准 util 模块提供了一个 debuglog 方法,它可以有条件地将日志消息写入 STDERR

const util = require('util');
const debuglog = util.debuglog('myapp');

debuglog('myapp debug message [%d]', 123);

当你将 NODE_DEBUG 环境变量设置为 myapp 或通配符 (如或my) 时,控制台将显示这些调试信息:

MYAPP 4321: myapp debug message [123]

使用 Node.js V8 Inspector 进行调试

Node.js 实际上是包装了 V8 JavaScript 引擎。V8 包含自己的检查器和调试客户端,你可以从 inspect 参数开始(注意不要将其与下面使用 Chrome 调试 Node.js 应用程序 --inspect 中描述的标志混淆):

node inspect index.js

调试器在第一行暂停并显示 debug 提示:

$ node inspect index.js
< Debugger listening on ws://127.0.0.1:9229/b9b6639c-bbca-4f1d-99f9-d81928c8167c
< For help, see: https://nodejs.org/en/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
<
Break on start in index.js:17
  2
  3 const
> 4   port = (process.argv[2] || process.env.PORT || 3000),
  5   http = require('http');
  6

我们可以输入 help 来查看命令列表:

  • cont 或者 c:继续执行
  • next 或者 n:运行下一个命令
  • step 或 s: 进入一个被调用的函数
  • outor: 跳出一个被调用的函数并返回它的调用者
  • pause: 暂停运行代码

您还可以:

  • 使用 watch ('x') 查看变量值
  • 使用 setBreakpoint()/sb() 命令设置断点(或者你也可以插入 debugger; 语句)
  • 重新启动脚本
  • .exit 退出调试器

这听起来确实有点笨拙,不过在没有其他选择或者你想自虐的话,可以尝试使用下内置的调试客户端。

使用 Chrome 调试 Node.js 应用程序

使用 --inspect 标志启动 Node.js V8 检查器(nodemon 也支持这个标志。):

node --inspect index.js

它会启动调试器,并且侦听 127.0.0.1:9229

Debugger listening on ws://127.0.0.1:9229/4b0c9bad-9a25-499e-94ff-87c90afda461

如果你在另一台设备或 Docker 容器上运行 Node.js 应用程序,请确保端口 9229 可访问并使用以下方式授予远程访问权限:

node --inspect=0.0.0.0:9229 index.js

您可以使用 --inspect-brk 替代 --inspect 来停止第一个语句的处理,这样你就可以逐行执行。然后打开 Chrome 浏览器(或任何其他基于 Chromium 的浏览器)并在地址栏中输入 chrome://inspect

几秒钟后,你的 Node.js 应用程序应就会显示为远程目标。如果没有找到,请选中 Discover network targets 并单击 Configure 按钮来添加运行应用程序的设备的 IP 地址和端口。单击目标的检查链接来启动 DevTools,如果你使用之前使用过浏览器调试客户端应用程序,这应该很熟悉。

要直接从 DevTools 加载、编辑和保存文件,请打开 Sources 看板,单击 Add folder to workspace,选择 Node.js 文件的位置,然后单击 Agree。现在可以从左侧窗格或按 Ctrl| 打开你应用程序的任何脚本,Cmd+P 并输入文件名。单击任意行号来设置断点(显示为蓝色标记):

断点指定调试器可以暂停处理的位置,这允许我们可以检查程序的状态,包括局部和全局变量。我们可以定义任意数量的断点或向代码中添加 debugger 语句,这些语句在调试器运行时也会停止处理。

右侧面板提供以下内容:

  • 一个 Watch 面板,你可以在其中通过单击+图标并输入其名称来监视变量
  • Breakpoints面板,你可以在其中查看、启用或禁用断点
  • Scope面板,你可以在其中检查所有变量
  • Call Stack 面板,你可以在其中查看为达到这一断点而调用的函数。

Paused on breakpoint 消息上方出现一行图标。

从左到右,这些图标执行以下操作:

  • resume execution : 继续处理到下一个断点
  • step over : 执行下一个命令但停留在当前函数内,不要跳入它调用的任何函数
  • step into:执行下一个命令并跳转到它调用的任何函数
  • step out : 继续处理到函数结束,返回调用命令
  • step : 类似于 step into,只是它不会跳转到 async 函数中
  • 停用所有断点
  • pause on exceptions:每当发生错误时停止处理。

在 Chrome 中设置条件断点

假设你有一个运行 1700 次迭代的循环,但你对最后一次的状态感兴趣:

for (let i = 0; i < 1700; i++) {
  // set breakpoint here?
}

您可以右键单击该行,选择 Add conditional breakpoint,然后输入条件,例如 :

i = 999

条件断点将会显示为黄色而不是蓝色。

在 Chrome 中设置日志点

日志点就像 console.log(),没有代码! 当代码执行一行时输出表达式,但与断点不同的是,处理不会暂停。想要添加日志点,只需右键单击任意一行,选择 “Add log point”,输入表达式,例如:

'loop counter i', i

使用 VS Code 调试 Node.js 应用程序

VS Code 支持 Node.js 并具有内置的调试客户端。在本地系统上运行 Node.js 应用程序时无需配置。打开你的启动脚本(通常是 index.js),激活 Run and Debug 看板,单击运行和调试 Node.js 按钮,然后选择 Node.js 环境,单击任意行来激活断点。

如果你正在运行一个 Web 应用,可以在浏览器中打开它,VS Code 会在遇到断点或 debugger 语句时停止执行:

VS Code 调试类似于带有 Variables、Watch、Call stackBreakpoints 面板的 Chrome DevToolsLoaded Scripts 面板显示应用程序加载的脚本,可能也包括 Node.js 内部的脚本。下面是一些工具栏的操作:

  • resume execution : 继续处理到下一个断点
  • step over : 执行下一个命令但停留在当前函数内,不要跳入它调用的任何函数
  • step into:执行下一个命令并跳转到它调用的任何函数
  • step out : 继续处理到函数结束,返回调用命令
  • 重新启动应用程序和调试器
  • 停止应用程序和调试器

Chrome DevTools 一样,你可以右击任何一行来添加:

  • 一个标准的断点。
  • 一个条件断点,让程序在指定条件下停止,例如 x > 3.
  • 计算花括号中表达式的日志点,例如 URL: { req.url }

其他的详细信息,可以查看这篇文章:https://code.visualstudio.com/docs/introvideos/debugging

VS Code 高级调试配置

如果你想在另一台设备、虚拟机上调试代码,或者需要使用其他启动选项(例如 nodemon

编辑器将启动配置存储在项目隐藏文件夹内的 launch.json 文件中。要生成文件,请单击 “create a launch” 面板顶部的 create launch.json 文件链接,然后选择 Node.js 环境。

您可以使用 add configuration 按钮将任意数量的配置设置对象添加到 "configurations" 数组。VS Code 可以:

  • 启动一个 Node.js 进程本身,或者
  • 附加到调试 Web Socket 服务器,可能在远程机器或 Docker 容器上运行。

上面的屏幕截图显示了 nodemon 启动配置。Add Configration 按钮提供了一个 nodemon 选项,因此你应该编辑该 "program" 属性来指向你的入口脚本 ( ${workspaceFolder}/index.js )。

保存 launch.json,然后从 “Run and Debug” 面板顶部的下拉列表中选择 nodemon,然后单击绿色运行图标:

nodemon 将启动你的应用程序,然后你就可以像以前一样编辑代码并设置断点或日志点。

要了解更多信息,请参考 https://code.visualstudio.com/docs/editor/debugging#_launch-configurations

VS Code 可以调试任何 Node.js 应用程序,但下面的扩展可以让调试变得更简单:

  • Remote - Containers:连接运行在 Docker 容器中的应用程序
  • Remote - SSH:连接到远程服务器上运行的应用程序
  • Remote - WSL:通过 Windows 上的 WSL 连接 Linux 上运行的应用程序

最后

大家还有什么 Node.js 项目的调试技巧,可以在留言区分享出来~

本文译自:https://blog.openreplay.com/an-introduction-to-debugging-in-nodejs

参考:

  • https://code.visualstudio.com/docs/editor/debugging#_launch-configurations
  • https://github.com/ibm/report-toolkit
  • https://nodejs.org/en/docs/guides/debugging-getting-started/
  • https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl
  • https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh
  • https://code.visualstudio.com/docs/introvideos/debugging
  • https://nodejs.org/api/debugger.html#debugger_breakpoints
  • https://nodejs.org/api/debugger.html
  • https://blog.openreplay.com/an-introduction-to-debugging-in-nodejs/#debugging-nodejs-apps-with-chrome
  • https://nodejs.org/api/cli.html#environment-variables

  推荐阅读:
据说,这是一件程序员才懂的T恤
Node.js 是如何跑起来的
2年过去了,谁还记得曾想取代Node.js的他?
如何调试你的 Node.js 代码?
TS、Vue、React、SSR、Node、Deno、Bun:回顾2022,展望2023
Office 2019/2021专业增强版,正版终身授权!

您可能也对以下帖子感兴趣

文章有问题?点此查看未经处理的缓存