Debian上Node.js应用如何调试

Debian上Node.js应用调试指南

一 核心方法与常用命令

• 使用 Node.js 内置检查器启动应用：开发时推荐用 –inspect，需要在入口处暂停时用 –inspect-brk。默认调试端口为 9229。示例：
  • 启动并在断点处暂停：node --inspect-brk app.js
  • 启动并允许远程调试：node --inspect=0.0.0.0:9230 app.js
• 连接调试前端：
  • 在 Chrome 打开 chrome://inspect，点击 Open dedicated DevTools for Node 或目标下的 inspect 进入调试界面。
• 代码中插入 debugger; 语句，配合 –inspect 可在指定位置中断。
• 使用 console.log/debug 模块输出关键变量与执行流，便于快速定位问题。

二 使用 VS Code 调试

• 启动配置（.vscode/launch.json）：
  • 直接启动应用（适合开发）： { “version”: “0.2.0”, “configurations”: [ { “type”: “node”, “request”: “launch”, “name”: “Launch Program”, “program”: “${workspaceFolder}/app.js”, “env”: { “NODE_ENV”: “development” }, “skipFiles”: [“<node_internals>/**”] } ] }
  • 附加到已启动的调试进程（适合调试 npm 脚本、守护进程等）： { “version”: “0.2.0”, “configurations”: [ { “type”: “node”, “request”: “attach”, “name”: “Attach to Node”, “port”: 9229, “protocol”: “inspector” } ] }
• 操作要点：在代码行号左侧点击设置断点，按 F5 启动；使用 F10/F11 单步跳过/进入；必要时在配置中设置 skipFiles 忽略 node_internals。调试 npm scripts（如 npm run dev）可将 request 设为 launch 并在 runtimeArgs 中传入 –inspect-brk。

三 远程与服务器场景

• 服务器本机调试：使用 –inspect=127.0.0.1:9229 限制监听地址，避免外网访问；在本地机器通过 chrome://inspect 或 VS Code attach 连接 localhost:9229。
• 跨机调试：在服务器启动 node --inspect=0.0.0.0:9229 app.js，并在防火墙放行 9229；本地 Chrome/VS Code 连接服务器的 <服务器IP>:9229。出于安全，建议仅在受信网络中开放调试端口。
• 无图形界面环境：使用 node inspect app.js 进入命令行调试；或在 VS Code 中 attach 到远程端口进行图形化调试。

四 常见问题与进阶技巧

• 端口被占用：检查是否已有 Node 调试进程占用 9229（或自定义端口），必要时更换端口或结束旧进程后再启动。
• 断点不生效：确认以 –inspect/–inspect-brk 启动；使用 debugger; 语句需配合检查器；VS Code 中确保未过滤 node_internals 导致源码不可见。
• 源码映射与依赖调试：调试 node_modules 或打包工具时，直接对可执行脚本启动调试，例如：
  • npm 脚本：“build:debug”: “node --inspect-brk ./node_modules/webpack/bin/webpack.js”
  • 然后 npm run build:debug 并在 chrome://inspect 或 VS Code 中连接。
• 性能与内存问题：使用 0x、clinic.js 等进行 CPU/内存剖析；生产问题可采集堆快照并用 llnode 分析。
• 日志与命名空间：使用 debug 模块并设定 DEBUG=namespace 环境变量，按需输出不同模块日志，避免 console.log 泛滥。