Ubuntu 下调试 Node.js 项目的实用指南
一 内置调试与 Chrome DevTools
- 启动方式
- 普通调试：运行命令：node --inspect app.js，调试器默认监听 9229 端口。
- 首行即停：运行命令：node --inspect-brk app.js，在程序入口处暂停，便于从第一行开始跟踪。
- 附加方式
- 打开 Chrome，访问：chrome://inspect。
- 在 Remote Target 中选中你的 Node 进程，点击 inspect 打开 DevTools，进行断点、单步、观察表达式与调用栈等操作。
- 代码内断点
- 在代码中插入：debugger;，当以 –inspect 启动时会在该处自动中断。
二 使用 Visual Studio Code 调试
- 基本配置
- 在 VS Code 中打开项目，点击左侧 运行与调试，创建 .vscode/launch.json。
- 使用如下配置启动程序：
{
“version”: “0.2.0”,
“configurations”: [
{
“type”: “node”,
“request”: “launch”,
“name”: “Launch Program”,
“program”: “${workspaceFolder}/app.js”
}
]
}
- 在代码行号左侧点击设置断点，按 F5 启动调试，可查看变量、调用堆栈并逐步执行。
- 进阶用法
- 附加到已运行进程：配置
{
“type”: “node”,
“request”: “attach”,
“name”: “Attach to Process”,
“port”: 9229
}
先用 node --inspect=9229 app.js 启动应用，再在 VS Code 选择 “Attach to Process” 连接。
- 远程开发（WSL/Ubuntu）：在 VS Code 使用 Remote-WSL 打开项目后，按上述方式调试，如同本地一样设置断点与查看变量。
三 命令行与日志辅助
- 快速输出
- 使用 console.log / console.error 输出关键变量与错误信息，便于快速定位问题。
- 选择性日志
- 使用 debug 模块输出命名空间日志：
const debug = require(‘debug’)(‘myapp:server’);
debug(‘server starting on port 3000’);
- 启动时开启命名空间：DEBUG=myapp: node app.js*（或指定 myapp:server）。
四 常见问题与实用技巧
- 端口与远程访问
- 调试默认端口为 9229。如需远程调试，确保该端口在 防火墙/云安全组 放行，或改用本机可达端口并在 chrome://inspect 中正确连接。
- 自动重启与调试配合
- 开发时可用 nodemon 监听文件变化并自动重启，便于快速验证修复：
- 安装：npm install -D nodemon
- 运行：nodemon app.js
- 注意：每次重启会重新分配调试端口，调试器需重新附加；也可在 nodemon 启动命令中加入 –inspect 以保留调试能力。
- 多进程与子进程
- 对 cluster/child_process/worker_threads，建议为主进程与子进程分别分配端口（如 9229/9230），或在 VS Code 中启用 autoAttachChildProcesses 以同时调试多进程。