Ubuntu 下 Node.js 调试实用指南

在 Ubuntu 环境下进行 Node.js 开发，高效的调试能力是提升效率的关键。今天，我们就来梳理一下那些真正实用、能帮你快速定位问题的调试方法。

一 内置调试与 Chrome DevTools

Node.js 自带了一套强大的调试协议，而 Chrome DevTools 则是它最直观的搭档。用好这对组合，大部分调试场景都能轻松应对。

• 启动方式
  • 普通启动：执行命令 node --inspect app.js。调试器会在默认的 9229 端口开始监听，程序会继续运行，直到遇到你设置的断点才会停下。
  • 首行暂停：如果你希望从程序入口就开始一步步跟踪，那就用 node --inspect-brk app.js。这个命令会让程序在第一行代码执行前就暂停，方便你从头开始。
• 连接与断点
  • 接下来，打开 Chrome 浏览器，在地址栏输入 chrome://inspect。在 “Remote Target” 区域，你应该能看到你的 Node 进程，点击旁边的 “inspect” 按钮，一个熟悉的 DevTools 窗口就会弹出来。
  • 在 Sources 面板里，你可以直接点击行号来设置断点。单步执行、观察表达式、查看调用栈和作用域变量，这些功能一应俱全，和调试前端 Ja vaScript 的体验几乎一样。
• 命令行辅助
  • 除了在 DevTools 里点选，你还可以在代码中直接插入 debugger; 语句。当程序以调试模式运行到这一行时，会自动中断。
  • 如果习惯纯命令行操作，可以使用旧式的 node inspect app.js 命令。常用的调试指令包括：cont（继续执行）、next（执行下一行）、step（进入函数）、out（跳出函数）以及 repl（进入交互式环境）。

二 使用 Visual Studio Code 调试

对于习惯在 IDE 里完成所有工作的开发者来说，Visual Studio Code 提供了无缝集成的调试体验，无需在浏览器和编辑器之间来回切换。

• 安装与配置
  • 用 VS Code 打开你的项目，点击左侧活动栏的 “Run and Debug” 图标，然后点击 “create a launch.json file”，选择 Node.js 环境即可。
  • 一个最常用的配置示例（位于 .vscode/launch.json）是这样的：

    {
      “version”: “0.2.0”,
      “configurations”: [{
        “type”: “node”,
        “request”: “launch”,
        “name”: “Launch Program”,
        “program”: “${workspaceFolder}/app.js”,
        “skipFiles”: [“/”]
      }]
    }

• 调试操作
  • 配置好后，直接在代码行号的左侧点击就能设置断点。按下 F5 键或者点击绿色的运行按钮，调试就开始了。
  • VS Code 的调试面板提供了完整的能力：断点管理、单步执行、变量观察、调用栈查看、作用域分析以及一个集成的控制台，所有信息一目了然。

三 附加场景与工具

实际开发中，总有些特殊场景。比如程序已经跑起来了，或者你只想看特定模块的日志。这时候，下面这些工具和技巧就派上用场了。

• 附加到已运行进程
  • 如果进程已经用 --inspect 参数启动了，你依然可以“附加上去”。在 VS Code 中，可以使用 “Attach to Process” 配置来连接对应的端口（默认 9229）。命令行里，则可以用 node inspect -p 来附加到指定进程。
• 选择性日志
  • 满屏的 console.log 让人头疼？试试 debug 模块。通过命名空间来管理日志输出，既清晰又灵活。

    const debug = require(‘debug’)(‘myapp:server’);
    debug(‘server starting on port 3000’);

  • 启动时，通过环境变量 DEBUG=myapp:* node app.js 来开启所有日志。如果只想看某个子模块，比如 myapp:server，那就把星号换成具体的命名空间。
• 辅助工具
  • nodemon：这个工具值得单独一提。它会监听文件变化并自动重启应用，与调试器配合起来，能极大提升代码修改和测试的迭代效率。

四 常见问题与排查

方法虽好，偶尔也会遇到些小麻烦。这里有几个常见问题的排查思路，帮你快速扫清障碍。

• 看不到 Remote Target
  • 首先确认启动命令确实包含了 --inspect 或 --inspect-brk。然后检查默认的 9229 端口是否被其他进程占用。如果一切无误，可以尝试在 chrome://inspect 页面的 “Configure” 按钮下，手动添加 localhost:9229 地址。
• 端口被占用
  • 端口冲突很常见。解决起来也简单，换一个端口启动就行：node --inspect=9228 app.js。别忘了，在 Chrome 的调试页面或者 VS Code 的配置里，也要把连接端口相应地改为 9228。
• 无法命中断点
  • 这可能是最让人困惑的情况。首先，可以尝试用 --inspect-brk 启动，确保程序能在入口处暂停，这能验证调试连接本身是否正常。
  • 如果还不行，就要警惕了：你的源代码文件路径，是不是被构建工具（比如 Webpack 等打包器）改变了？一个有效的办法是，在 Chrome DevTools 的 Sources 面板中，通过 “Filesystem” 功能将你的本地工作区添加进去，建立正确的源文件映射，然后再设置断点。

说到底，调试的本质是清晰地观察和控制程序状态。无论是借助强大的 Chrome DevTools，还是依赖高度集成的 VS Code，亦或是搭配上 debug 模块和 nodemon 这样的效率工具，核心目的只有一个：让你更快地找到问题所在，把时间花在创造上，而不是寻找 Bug 上。