Ubuntu上Node.js应用如何调试

Ubuntu 上 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/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（Step Over）、F11（Step Into）、Shift+F11（Step Out）控制执行。
  • 建议将 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 logs
  • 查看指定应用：pm2 logs <app_name_or_id>
  • 实时跟踪：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 进行远程调试。

四 日志与常见故障排查

• 日志定位
  • 应用日志：检查项目配置的 app.log / error.log 等文件，使用 tail -f /path/to/file.log 实时查看。
  • 系统日志：服务方式运行时查看 journalctl -u <service_name>；通用系统日志 /var/log/syslog。
• 常见 Node.js 警告与处理
  • DeprecationWarning：例如使用了过时 Buffer()，应改为 Buffer.alloc()/Buffer.from()；同时升级依赖与 Node 版本。
  • UnhandledPromiseRejectionWarning：为所有 Promise 添加 .catch() 或 try/catch；可临时监听 process.on(‘unhandledRejection’)。
  • MaxListenersExceededWarning：事件监听泄漏，检查重复添加并适时 removeListener，或调整 setMaxListeners。
  • JavaScript heap out of memory：内存不足，临时提升堆上限：node --max-old-space-size=4096 app.js；进一步用 clinic 等工具分析内存问题。

五 实用提示

• 端口与远程调试
  • 调试默认端口 9229；远程/容器场景需确保端口可达，必要时通过 –inspect=: 指定监听地址与端口。
• 条件断点与观察表达式
  • 在 Chrome DevTools 或 VSCode 中可设置条件断点、日志断点，并在调试控制台观察/执行表达式，快速定位问题。
• 快速输出排查
  • 临时使用 console.log/error 辅助定位，配合条件编译或环境变量控制输出级别，避免生产环境过量日志。