Ubuntu 上调试 Node.js 应用的实用方法
一 本地调试
- 使用 Chrome DevTools
- 启动应用：在终端执行 node --inspect app.js（首行暂停用 node --inspect-brk app.js）。
- 打开浏览器访问 chrome://inspect，在 Remote Target 中点击 inspect 进入调试器，可设置断点、查看调用栈与变量。
- 使用 VS Code
- 打开项目，按 Ctrl+Shift+D 进入“运行和调试”，点击“创建 launch.json”，选择 Node.js 环境。
- 使用默认配置或按需修改，例如：
{
“version”: “0.2.0”,
“configurations”: [
{
“type”: “node”,
“request”: “launch”,
“name”: “Launch Program”,
“program”: “${workspaceFolder}/app.js”
}
]
}
- 在代码行号左侧点下断点，按 F5 启动调试。
- 使用 node inspect 命令行
- 执行 node inspect app.js 进入 CLI 调试器。
- 常用命令：cont/c（继续）、next/n（下一步）、step/s（进入）、out/o（跳出）、pause（暂停）、sb(line/file)（设断点）、bt（堆栈）、repl（求值）。
- 辅助输出
- 临时使用 console.log/error 快速定位。
- 使用 debug 模块做选择性日志：
const debug = require(‘debug’)(‘myapp:server’); debug(‘start’);
启动时开启：DEBUG=myapp:server node app.js。
二 远程服务器调试
- 场景一：服务器上直接调试
- 在服务器启动：node --inspect-brk app.js（首行暂停便于附加）。
- 本地浏览器访问 chrome://inspect，在 Remote Target 中点击 inspect 打开 DevTools 调试。
- 场景二：使用 VS Code Remote-SSH
- 本地 VS Code 安装 Remote-SSH 扩展，连接 Ubuntu 服务器。
- 在远程窗口打开项目，按 F5 选择 Node.js 调试配置即可（断点、变量、调用栈与本地一致）。
- 场景三：CLI 附加到远程调试端口
- 服务器启动后，终端会打印调试地址（如 ws://127.0.0.1:9229/…）。
- 在本地或服务器上执行 node inspect <调试地址> 进行命令行调试。
三 常见问题与排查
- 端口与地址
- 调试默认端口为 9229；如远程访问不到，确认监听地址为 0.0.0.0 而非 127.0.0.1，并在云服务器安全组/防火墙放行 9229。
- 程序立即退出
- 使用 –inspect-brk 让程序在首行暂停，便于及时附加调试器。
- 断点不生效
- 确保以调试模式启动（–inspect），且代码确实被执行到；使用 debugger; 语句辅助暂停。
- 依赖或构建产物问题
- 若入口是打包后的文件（如 dist/），请在构建完成后再启动调试，或在 source map 就绪后再附加。
- 权限与路径
- 远程调试时，确保工作目录与入口文件路径正确，SSH 登录用户具备相应权限。
四 高效调试建议
- 组合使用 –inspect-brk + Chrome DevTools 或 VS Code 进行断点与单步；配合 debug 模块做条件日志，减少侵入式 console.log。
- 长期运行的服务建议使用进程管理工具（如 systemd）托管，并在服务配置中开启调试端口与重启策略，便于问题复现与定位。