在 Debian 上调试 Node.js 的实用方法
一 环境准备
- 安装运行时与包管理工具：sudo apt update && sudo apt install nodejs npm；验证版本：node -v、npm -v。若系统仓库版本较旧，可考虑使用 nvm 或 NodeSource 官方仓库安装更新版本。
- 建议准备一个最小示例用于验证调试链路：创建 app.js，内容为 console.log(‘Hello, Node.js!’); 先确保能正常运行，再进入调试。
二 内置与命令行调试
- 使用 node inspect 进入调试控制台：node inspect app.js。常用命令：c（continue 继续）、n（next 下一步）、s（step 进入）、repl（进入 REPL）、sb（设置断点）、cb（清除断点）。
- 使用 –inspect 或 –inspect-brk 启动调试服务器：node --inspect app.js（程序启动后等待调试器连接），node --inspect-brk app.js（在首行暂停，便于从入口断点开始）。默认调试端口为 9229。
三 图形化与 IDE 调试
- 使用 Chrome DevTools：启动应用后，在 Chrome 打开 chrome://inspect，点击“为 Node 打开专用 DevTools”，添加对 localhost:9229 的连接，即可设置断点、查看调用栈与变量。
- 使用 Visual Studio Code：在项目根目录创建 .vscode/launch.json，常用配置示例：
- 直接启动调试
{
“version”: “0.2.0”,
“configurations”: [
{
“type”: “node”,
“request”: “launch”,
“name”: “Launch App”,
“program”: “${workspaceFolder}/app.js”,
“skipFiles”: [“<node_internals>/**”]
}
]
}
- 附加到已运行的进程
{
“version”: “0.2.0”,
“configurations”: [
{
“type”: “node”,
“request”: “attach”,
“name”: “Attach to Process”,
“port”: 9229,
“skipFiles”: [“<node_internals>/**”]
}
]
}
启动方式：F5 或“运行和调试”面板选择相应配置。
四 日志与问题定位
- 快速打印：在代码中临时加入 console.log 输出关键变量与执行流，便于定位问题。
- 使用 debug 模块做命名空间日志：
- 安装：npm install debug
- 使用：
const debug = require(‘debug’)(‘myapp’);
debug(‘Hello, debug!’);
- 运行时开启：DEBUG=myapp node app.js；也可按命名空间细化：DEBUG=myapp:* node app.js。
- 生产环境建议接入日志库（如 winston、pino）或进程管理工具（如 PM2）统一收集与轮转日志，便于回溯：
- PM2 日志：pm2 logs、pm2 logs aggregate
- 系统日志：journalctl -u 服务名；实时查看：tail -f /var/log/syslog
- 日志轮换：使用 logrotate 定期压缩归档，避免磁盘占满。
五 常见问题与排查要点
- 端口与地址：调试默认端口 9229；如远程或容器环境，需确保监听 0.0.0.0 并在防火墙放行该端口，Chrome/VS Code 才能连接。
- 服务与权限：若以 systemd 管理服务，可在单元中设置环境变量（Environment=NODE_ENV=development）并启用日志转发（StandardOutput/StandardError=syslog），再用 journalctl 跟踪；必要时在开发阶段改用直接命令行调试以简化链路。
- 断点与暂停：代码未暂停时，可在 DevTools 的 Sources 面板手动暂停，或在启动命令中使用 –inspect-brk 从首行断点开始。