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” 区域找到你的应用，点击 “inspect”，熟悉的 DevTools 界面就出现了。
  • 在 “Sources” 面板里，你可以自由地设置断点、单步执行、观察作用域变量和调用栈，一切尽在掌握。
  • 还有个偷懒的小技巧：在代码里直接插入 debugger; 语句，配合 --inspect 启动，程序运行到这儿就会自动暂停。
• 无界面/自动重启场景
  • 开发时习惯用 nodemon 实现热重载？调试也没问题。使用 nodemon --inspect app.js 即可。如果偶尔遇到断点不生效的情况，别急，关闭 DevTools 再重新打开连接一次，通常就能解决。

二 使用 VSCode 调试

对于习惯在 VSCode 里编码的开发者来说，其内置的调试功能用起来会更加顺手，几乎无需离开这个强大的编辑器。

• 快速配置
  • 打开项目后，找到左侧的“运行和调试”图标，点击它并创建 .vscode/launch.json 文件，环境选择 Node.js。
  • 一个常用的配置示例如下（记得根据实际情况修改 program 字段指向你的入口文件）：

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

• 启动与常用控制
  • 在代码行号左侧点击即可设置断点，然后按 F5 启动调试。执行控制就靠几个快捷键：F10（跳过）、F11（跳入）、Shift+F11（跳出）。
  • 有个贴心建议：将 console 设置为 integratedTerminal，这样应用的输入输出和调试信息都在终端里，交互起来更清晰。
• 附加到已运行进程
  • 有时候应用已经跑起来了，怎么调试？先确保它以调试模式启动：node --inspect=9229 app.js（或者用 --inspect-brk）。
  • 然后在 launch.json 里增加一个配置：

    {
      “name”: “Attach to Node”,
      “type”: “node”,
      “request”: “attach”,
      “port”: 9229,
      “restart”: true
    }

  • 最后在调试下拉菜单中选择 “Attach to Node”，就能轻松连接到正在运行的进程进行调试了。

三 使用 PM2 运行与调试

当应用进入生产环境或需要进程管理时，PM2 是常见选择。它同样能和调试器完美协作。

• 日志与实时排查
  • 查看全部应用日志：pm2 logs
  • 查看指定应用：pm2 logs
  • 实时跟踪：pm2 logs --follow；查看最近 N 行：pm2 logs --lines 1000
• 与调试器配合
  • 用调试模式启动应用：pm2 start app.js --node-args=“--inspect=9229”
  • 如果需要文件改动热重载：pm2 start app.js --node-args=“--inspect=9229” --watch
  • 启动后，你就可以像之前一样，在 VSCode 里使用 “Attach to Node” 配置连接 9229 端口，或者在 Chrome 中打开 chrome://inspect 进行远程调试了。

四 日志与常见故障排查

调试器是利器，但日志分析才是日常定位问题的基本功。结合一些常见的 Node.js 警告，能帮你快速缩小排查范围。

• 日志定位
  • 应用日志：首先检查项目自身配置的日志文件，比如 app.log、error.log 等。使用 tail -f /path/to/file.log 命令可以实时查看最新动态。
  • 系统日志：如果应用以系统服务方式运行，可以查看 journalctl -u 。更通用的系统日志则位于 /var/log/syslog。
• 常见 Node.js 警告与处理
  • DeprecationWarning：这通常是使用了过时的 API，比如旧的 Buffer() 构造函数。解决办法是改用 Buffer.alloc() 或 Buffer.from()，并记得升级相关依赖和 Node.js 版本。
  • UnhandledPromiseRejectionWarning：未处理的 Promise 拒绝。务必为所有 Promise 链添加 .catch() 处理，或者在 async 函数中使用 try/catch。临时排查时，可以监听 process.on(‘unhandledRejection’) 事件。
  • MaxListenersExceededWarning：事件监听器数量超限，可能存在内存泄漏。检查代码中是否重复添加了监听器而未移除，适时使用 removeListener，或者通过 setMaxListeners 临时调高限制。
  • Ja vaScript heap out of memory：Ja vaScript 堆内存不足。临时解决方案是启动时增加堆上限：node --max-old-space-size=4096 app.js。要根治问题，则需要使用 clinic 等专业工具进行深入的内存分析。

五 实用提示

最后，分享几个能提升调试效率的小贴士。

• 端口与远程调试
  • 记住，调试默认端口是 9229。在远程服务器或 Docker 容器内调试时，务必确保该端口在网络上可达。必要时，可以通过 --inspect=: 来指定监听的地址和端口。
• 条件断点与观察表达式
  • 无论是 Chrome DevTools 还是 VSCode，都支持设置条件断点和日志点（logpoint）。在调试控制台里观察和计算表达式，能让你快速验证假设，精准定位问题。
• 快速输出排查
  • 在复杂的逻辑中，临时使用 console.log 或 console.error 进行输出，依然是快速定位问题的有效手段。为了不影响生产环境，可以通过条件编译或环境变量来控制这些调试日志的输出级别。