Debian Node.js调试技巧有哪些

Debian 上常用的 Node.js 调试技巧

一 核心方法与常用命令

• 使用 –inspect 或 –inspect-brk 启动调试服务器，默认监听 9229 端口；在 Chrome 打开 chrome://inspect 即可进行断点、单步、查看调用栈与变量等图形化调试。示例：node --inspect app.js 或 node --inspect-brk app.js。Node.js 20+ 新增 –inspect-wait，会等待调试器连接后再执行代码，便于从启动阶段介入。必要时可用 node --inspect=8888 app.js 指定端口。
• 使用 node inspect app.js 进入命令行调试器，支持常用命令：cont/c（继续）、next/n（下一步）、step/s（进入）、out/o（跳出）、pause（暂停）、sb()/cb()（设置/清除断点）、bt（调用栈）、repl（进入上下文 REPL）、profile/profileEnd（CPU 分析）、takeHeapSnapshot（堆快照）。
• 在代码中插入 debugger; 语句，配合 –inspect 会在该处自动中断，便于快速定位问题。

二 在 VS Code 中高效调试

• 直接启动：在 .vscode/launch.json 使用 request=launch，指定入口文件即可一键调试。示例：
  { “version”: “0.2.0”, “configurations”: [ { “type”: “node”, “request”: “launch”, “name”: “Launch Program”, “program”: “${workspaceFolder}/index.js” } ] }
• 附加到已运行进程：先用 node --inspect app.js 启动，再用 request=attach 指定端口 9229 附加。示例：
  { “type”: “node”, “request”: “attach”, “name”: “Attach to Process”, “port”: 9229, “skipFiles”: [“<node_internals>/**”] }
• 远程调试：在 attach 配置中添加 address 字段指向远程 debugger server IP；或使用 VS Code 的 远程开发扩展包 实现远程开发与调试一体化。
• 开发体验优化：启用 javascript: Auto Attach 可快速附加；使用 skipFiles 忽略 <node_internals>/ 减少干扰；对 npm run dev 等脚本可直接配置 “command”: “npm run dev” 启动调试。

三 开发期热重载与日志追踪

• 使用 nodemon 自动重启并结合调试：nodemon --inspect app.js；或在 nodemon.json 中配置 “exec”: “node --inspect-brk src/your-script.js”，保存即自动进入断点等待。
• 使用 debug 模块做命名空间日志：npm i debug；代码中 const debug = require(‘debug’)(‘myapp:*’)；运行时通过环境变量控制输出，如 DEBUG=myapp: node app.js*，也可设置 DEBUG_COLORS=true DEBUG_FD=3 自定义格式与输出目标。

四 生产环境可观测与问题定位

• 使用 PM2 管理服务并保留调试能力：sudo npm i -g pm2；通过 /etc/systemd/system/node.service 配置 ExecStart 指向 Node，必要时在 Environment 中设置 NODE_ENV=production 等变量，结合日志与进程管理进行问题排查。
• 使用 inspector 模块进行按需性能采集：
  import { Session } from ‘node:inspector/promises’;
  const session = new Session();
  await session.connect();
  await session.post(‘Profiler.enable’);
  await session.post(‘Profiler.start’);
  // …执行业务逻辑…
  const { profile } = await session.post(‘Profiler.stop’);
  fs.writeFileSync(‘./profile.cpuprofile’, JSON.stringify(profile));
  生成的 .cpuprofile 可在 Chrome DevTools 的 Profiles 面板分析。
• 结构化日志：在本地开发可用 console.log 快速定位，生产环境建议使用 Pino 或 Winston 设置 INFO/WARN/ERROR 等级，便于过滤与聚合分析。

五 常见问题与排查要点

• 端口与防火墙：调试默认端口 9229，如改用 8888 需同步在 chrome://inspect 或 VS Code 的 attach 配置中指定；服务器环境需放行对应端口（如 ufw/iptables）。
• 远程连接：确保 Debian 主机与调试客户端网络可达；远程 attach 时在 VS Code 配置 address 为服务器 IP。
• 启动阶段问题：对初始化逻辑难介入的场景，优先用 –inspect-brk（首行即停）或 –inspect-wait（等待连接后再执行）。
• 代码变更频繁：开发期用 nodemon + --inspect(-brk) 提升效率；避免频繁改动导致断点失效。
• 输出干扰：VS Code 中用 skipFiles 忽略 <node_internals>/；日志用 debug 的命名空间按需开启，减少噪音。