Ubuntu 上调试 Node.js 应用的实用方法

在 Ubuntu 环境下开发 Node.js 应用，调试是绕不开的一环。面对一个“不听话”的程序，如何快速定位问题？别急，下面这份从本地到远程的调试指南，或许能帮你理清思路。

一 本地调试

本地调试是最高效的起点，工具选择也最多样。

• 使用 Chrome DevTools
  1. 启动应用：在终端执行 node --inspect app.js。如果想在程序启动的第一行就暂停，方便立即附加调试器，可以使用 node --inspect-brk app.js。
  2. 连接调试器：打开 Chrome 浏览器，访问 chrome://inspect。在 “Remote Target” 区域，你应该能看到你的应用，点击旁边的 “inspect” 按钮，熟悉的 DevTools 调试界面就会打开。接下来，设置断点、查看调用栈和变量，就和调试前端代码一样顺畅。
• 使用 VS Code
  1. 配置环境：在 VS Code 中打开你的项目，按下 Ctrl+Shift+D 进入“运行和调试”侧边栏。点击“创建 launch.json”文件，选择 Node.js 环境。
  2. 调整配置：编辑器会生成一个默认配置，通常可以直接使用。如果需要，可以按需修改，例如一个基础的配置是这样的：

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

  3. 开始调试：在代码行号的左侧点击设置断点，然后按下 F5，程序就会在调试模式下启动，并在断点处暂停。
• 使用 node inspect 命令行
  1. 进入 CLI 调试器：直接在终端执行 node inspect app.js，会进入一个命令行交互式的调试环境。
  2. 掌握常用命令：记住几个核心命令能极大提升效率：
     • cont 或 c：继续执行。
     • next 或 n：执行下一步（不进入函数）。
     • step 或 s：进入函数内部。
     • out 或 o：跳出当前函数。
     • pause：暂停运行中的程序。
     • sb(line/file)：设置断点。
     • bt：打印调用堆栈。
     • repl：进入 REPL 模式，对当前上下文进行求值。
• 辅助输出
  • 快速定位：临时使用 console.log 或 console.error 输出关键信息，是最直接（虽然稍显“粗暴”）的方法。
  • 选择性日志：对于更结构化的日志需求，可以使用 debug 模块。先在代码中引入并创建调试器：const debug = require(‘debug’)(‘myapp:server’); 然后在需要的地方调用 debug(‘start’);。启动应用时，通过环境变量开启：DEBUG=myapp:server node app.js。这样一来，日志可以按需开关，非常灵活。

二 远程服务器调试

当问题出现在测试或生产服务器时，远程调试能力就至关重要了。

• 场景一：服务器上直接调试
  1. 在服务器启动：通过 SSH 连接到你的 Ubuntu 服务器，使用 node --inspect-brk app.js 启动应用。加上 -brk 参数让程序在首行暂停，确保你有足够时间附加调试器。
  2. 本地连接：在你自己电脑的 Chrome 浏览器中，同样打开 chrome://inspect。如果网络可达，你的服务器应用会出现在 “Remote Target” 列表中，点击 “inspect” 即可开始远程调试。
• 场景二：使用 VS Code Remote-SSH
  1. 建立连接：在本地 VS Code 安装 “Remote - SSH” 扩展，然后配置并连接到你的 Ubuntu 服务器。
  2. 无缝调试：连接成功后，在 VS Code 的远程窗口中打开项目目录。此时，按 F5 启动调试，VS Code 会自动在远程服务器上启动 Node.js 进程。设置断点、观察变量、查看调用栈的体验，与在本地调试完全一致。
• 场景三：CLI 附加到远程调试端口
  1. 获取调试地址：在服务器上以调试模式启动应用后，终端会打印出 WebSocket 调试地址，格式类似于 ws://127.0.0.1:9229/...。
  2. 附加调试：在本地或服务器的另一个终端里，执行 node inspect <调试地址>，就能以命令行方式附加到正在运行的程序上进行调试。

三 常见问题与排查

调试路上难免遇到些“小坑”，这里有几个常见问题的排查思路。

• 端口与地址
  • Node.js 调试默认监听 9229 端口。如果从远程无法访问，首先检查启动时是否将监听地址绑定到了 0.0.0.0（使用 --inspect=0.0.0.0:9229），而不是默认的 127.0.0.1。其次，务必在云服务器的安全组或系统防火墙中放行 9229 端口。
• 程序立即退出
  • 如果程序启动后瞬间结束，来不及附加调试器，请使用 --inspect-brk 参数，它能确保脚本在第一行用户代码执行前就暂停。
• 断点不生效
  • 确认应用确实是以调试模式（带有 --inspect 参数）启动的。同时检查你设置的断点所在代码路径是否确实被执行。如果仍有疑问，可以在代码中直接插入 debugger; 语句，这是一个强制的断点。
• 依赖或构建产物问题
  • 如果你的入口文件是 Webpack 等工具打包后的产物（例如 dist/ 目录下的文件），请确保在构建完成后再启动调试。如果涉及 Source Map，也需要确认其配置正确且可访问。
• 权限与路径
  • 进行远程调试时，特别是使用 VS Code Remote-SSH，请确保工作目录和入口文件路径设置正确。同时，SSH 登录用户需要对项目文件具备读/写/执行的相关权限。

四 高效调试建议

最后，分享几个提升调试效率的心得。

• 组合工具，各取所长：可以组合使用 --inspect-brk 与 Chrome DevTools 或 VS Code 进行直观的断点与单步调试。同时，配合 debug 模块输出条件化的日志，既能深入追踪，又能减少到处插入 console.log 对代码的侵入。
• 管理长期服务：对于需要长期运行的后台服务，建议使用 systemd 等进程管理工具进行托管。在其服务配置文件中，可以设置环境变量来开启调试端口，并配置合理的重启策略。这样，当问题复现时，你能快速连接到指定进程进行诊断，而不必手动维护进程的运行。