Ubuntu Nodejs应用如何调试

在 Ubuntu 环境下调试 Node.js 应用，方法其实远比很多人想象的要灵活。无论你是习惯浏览器里的 DevTools，还是离不开 VS Code 的集成调试面板，甚至需要对付一些特殊场景——比如调试 npm 包、让代码在文件变更后自动重启、或者“无侵入”地附加到一个已经在跑的进程上——都有成熟的方案。下面把这些方法梳理一遍，希望能帮你建立起一个顺手的调试工作流。

一 内置调试与 Chrome DevTools

Node.js 自带了一套基于 Chrome DevTools Protocol 的调试能力，这是最基础也最直接的方式。

启动方式

具体怎么启动呢？有两种常用模式：

• 普通启动：执行 node --inspect app.js。程序会继续运行，同时开启调试端口（默认是 9229），等待调试器连接。适合在程序已经跑起来之后，再附加上去检查状态。
• 首行暂停：执行 node --inspect-brk app.js。程序会在第一行代码执行前自动中断。这个模式非常适合需要从入口处一步步跟踪逻辑的场景，比如分析初始化流程。

连接与调试

怎么连上调试器呢？最推荐的方式是 Chrome 浏览器：

• 在地址栏输入 chrome://inspect，你会看到 Remote Target 一栏下列出了当前可调试的 Node.js 进程。点击下方的 inspect 链接，或者选择 Open dedicated DevTools for Node，就能打开一个专为 Node 设计的 DevTools 窗口。
• 在这个窗口里，Sources、Console、Network、Memory、Profiler 这些面板一应俱全，完全可以像调试前端代码一样进行断点、单步执行、观察表达式和性能分析。
• 另一种方式：直接在浏览器访问 http://127.0.0.1:9229/json，会返回一个 JSON，里面包含了 DevTools 前端的完整地址，复制打开即可。

原理提示

这里有个值得一提的细节：Node 是通过 Chrome DevTools Protocol（CDP）与 DevTools 建立 WebSocket 通信的。当你在 Console 面板中展开一个深层对象时，Node 会向 V8 引擎实时查询该对象的详细信息。这意味着，如果程序本身没有阻塞或等待事件（比如一个立即退出的脚本），对象可能来不及完全序列化。所以，这种交互式调试更适合在会等待的场景下进行，比如 HTTP 请求处理中、定时任务执行时。

二 使用 VS Code 调试

对于日常开发来说，VS Code 的集成调试体验可能更顺手一些。

快速开始

在 VS Code 中打开项目，点击左侧的 运行与调试 图标。首次使用时，需要创建一个 .vscode/launch.json 配置文件，选择 Node.js 环境即可。

常用配置

主要有两种启动模式需要了解：

• 直接启动：这是最常见的场景。launch.json 的配置示例如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "program": "${workspaceFolder}/app.js",
            "console": "integratedTerminal",
            "env": { "NODE_ENV": "development" }
        }
    ]
}

• 附加到已运行进程：有时候我们不想让 VS Code 自动启动程序，而是想附加到一个已经通过命令行启动并开启了 --inspect 或 --inspect-brk 的进程上。比如先手动执行 node --inspect-brk app.js，然后在 VS Code 中配置 attach 模式：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "attach",
            "name": "Attach to Process",
            "port": 9229
        }
    ]
}

调试能力

VS Code 的 Node.js 调试器功能很全面，支持普通断点、条件断点、函数断点、监视表达式、调用栈查看、变量面板，甚至可以在调试过程中实时求值。对于日常的闭环开发调试，这基本上就是首选方案。

三 进阶场景与技巧

当遇到一些不那么常规的需求时，下面这几个技巧可能会派上用场。

调试 npm 包或 CLI

想调试一个 npm 包或者命令行工具，比如 webpack？很简单，在 package.json 的 scripts 里新增一个专门用于调试的脚本，显式指定可执行文件并开启调试端口即可。举个例子：

"scripts": {
    "build:debug": "node --inspect --inspect-brk ./node_modules/webpack/bin/webpack.js"
}

运行 npm run build:debug 后，用 VS Code 的 attach 模式或者 chrome://inspect 连上去就可以了。

监听文件变更自动重启并调试

开发时改完代码希望自动重启并保持调试能力，有两种常见的做法：

• 使用 Node.js 自带的实验性 watch 功能：node --watch --inspect-brk app.js。
• 使用 nodemon，这是更成熟的选择。在 VS Code 的 launch.json 里这样配置：

{
    "type": "node",
    "request": "launch",
    "name": "Debug with nodemon",
    "runtimeExecutable": "nodemon",
    "program": "${workspaceFolder}/app.js",
    "restart": true,
    "console": "integratedTerminal",
    "env": { "NODE_ENV": "development" }
}

已运行进程“无侵入”附加

如果一个 Node.js 进程已经跑起来了，之前没有加 --inspect 参数，怎么在不重启的情况下开启调试？方法是向它发送一个特殊信号。首先找到进程的 PID：ps aux | grep app.js。然后有两种方式：

• 方式一：node -e 'process._debugProcess(PID)'。
• 方式二：对于 Node.js 8 及以上版本，直接发送 SIGUSR1 信号即可：kill -SIGUSR1 PID。这个信号会触发 Node 切换到调试模式，非常方便。

选择性日志

调试时如果只想关注特定模块的日志，可以试试 debug 这个库。在代码里这样写：

const debug = require('debug')('myapp:server');
debug('start');

然后通过环境变量来控制启用哪些日志：DEBUG=myapp:* node app.js，或者更精确地 DEBUG=myapp:server node app.js。

TypeScript 调试

如果项目是用 TypeScript 写的，推荐使用 tsx（一个对 node 的封装，原生支持 --inspect 和 --watch）。安装方式：npm i -D tsx。然后直接启动：tsx --inspect server.ts。调试体验和 Ja vaScript 几乎一致。

四 常见问题与排查

最后，汇总几个经常遇到的问题和对应的排查思路。

看不到目标进程

如果在 chrome://inspect 或 VS Code 里找不到目标进程，先确认启动命令里是否包含了 --inspect 或 --inspect-brk。然后检查端口 9229 是否被占用（比如 lsof -i:9229），以及防火墙是否放行了该端口。必要时可以显式指定地址和端口，比如 --inspect=127.0.0.1:9229。

无法展开深层对象或数据不完整

前面提到过，在 DevTools Console 中展开对象时，Node 通过 CDP 向 V8 拉取信息。如果程序在执行完某个操作后立即退出（没有任何等待或阻塞），对象可能来不及完全序列化就被回收了。解决办法：在会等待的事件中查看，比如 HTTP 请求的处理函数里、定时任务的回调里，或者直接使用 --inspect-brk 在断点处逐步检查。

附加失败

确认目标进程确实是以 --inspect 启动并正在监听 9229 端口。如果是远程调试，要确保网络访问没有被限制。如果是本地调试，建议使用回环地址 127.0.0.1 来避免不必要的网络问题。