Ubuntu 下 Node.js 调试实用指南
一 内置调试与 Chrome DevTools
- 启动方式
- 普通启动：运行命令：node --inspect app.js，调试器在默认端口 9229 监听，程序继续运行直至遇到断点。
- 首行暂停：运行命令：node --inspect-brk app.js，在第一行暂停，便于从入口处逐步调试。
- 连接与断点
- 在 Chrome 打开：chrome://inspect，在 Remote Target 中看到 Node 进程，点击 inspect 打开 DevTools。
- 在 Sources 面板可直接点击行号设置断点，支持单步、观察表达式、查看调用栈与作用域变量。
- 命令行辅助
- 代码中插入 debugger; 语句，运行到该行会自动中断。
- 旧式命令行调试可用 node inspect app.js，常用命令：cont（继续）、next（下一行）、step（进入函数）、out（跳出）、repl（进入 REPL）。
二 使用 Visual Studio Code 调试
- 安装与配置
- 打开项目后，进入左侧 Run and Debug，点击 create a launch.json file，选择 Node.js 环境。
- 常用配置示例（.vscode/launch.json）：
{
“version”: “0.2.0”,
“configurations”: [
{
“type”: “node”,
“request”: “launch”,
“name”: “Launch Program”,
“program”: “${workspaceFolder}/app.js”,
“skipFiles”: [“<node_internals>/”]
}
]
}
- 调试操作
- 在代码行号左侧点击设置断点，按 F5 或点击绿色运行按钮启动。
- 支持断点、单步、观察、调用栈、作用域与控制台等完整调试能力。
三 附加场景与工具
- 附加到已运行进程
- 进程已以 –inspect 启动时，可用 VS Code 的 Attach to Process 配置连接端口 9229，或在命令行使用 node inspect -p 附加调试。
- 选择性日志
- 使用 debug 模块输出命名空间日志：
const debug = require(‘debug’)(‘myapp:server’);
debug(‘server starting on port 3000’);
- 启动时开启日志：DEBUG=myapp: node app.js*（或指定命名空间如 myapp:server）。
- 辅助工具
- nodemon 监听文件变更并自动重启，可与调试器配合使用，提高迭代效率。
四 常见问题与排查
- 看不到 Remote Target
- 确认启动命令包含 –inspect 或 –inspect-brk，且端口 9229 未被占用；必要时在 chrome://inspect 的 Configure 中添加 localhost:9229。
- 端口被占用
- 更换端口启动：node --inspect=9228 app.js，并在 chrome://inspect 或 VS Code 配置对应端口。
- 无法命中断点
- 使用 –inspect-brk 从入口暂停；确保文件未被构建工具（如打包器）改动路径或内容，必要时在 DevTools 的 Sources 中通过 Filesystem 添加工作区映射后再设断点。