Linux环境中Node.js如何调试

Linux 下 Node.js 调试实用指南

一 内置检查器与 Chrome DevTools

• 启动方式
  • 普通启动并在需要时连接：node –inspect your_script.js
  • 启动即在第一行暂停：node –inspect-brk your_script.js
  • 指定调试端口：node –inspect=9229 your_script.js（默认端口为 9229）
• 连接步骤
  • 在 Chrome 打开：chrome://inspect
  • 在 Remote Target 中找到你的 Node 进程，点击 Inspect 进入 DevTools（Sources、Console、Scope、Call Stack 等面板可用）
• 适用场景
  • 快速排查逻辑错误、异步堆栈、性能热点，支持断点、单步、观察表达式等

二 使用 Visual Studio Code 调试

• 生成配置
  • 在项目根目录创建 .vscode/launch.json，选择 Node.js 环境
• 常用配置示例
  • 启动程序

    {
      "version": "0.2.0",
      "configurations": [
        {
          "type": "node",
          "request": "launch",
          "name": "Launch Program",
          "program": "${workspaceFolder}/your_script.js",
          "skipFiles": ["<node_internals>/**"]
        }
      ]
    }
    

  • 附加到已运行进程

    {
      "version": "0.2.0",
      "configurations": [
        {
          "type": "node",
          "request": "attach",
          "name": "Attach to Process",
          "port": 9229
        }
      ]
    }
    

• 使用要点
  • 在代码行号左侧点击设置断点，按 F5 启动；需要远程或容器场景优先用 attach 方式

三 命令行与代码级辅助手段

• 命令行检查器
  • 逐步调试：node inspect your_script.js
  • 结合 debugger; 语句：在代码中插入 debugger;，当执行到该行时会暂停，配合 node inspect 使用
• 运行时诊断选项
  • 输出 Promise 警告栈：node –trace-warnings index.js
  • 使用 TypeScript 等转译器时启用源映射：node –enable-source-maps app.ts
  • 对废弃 API 直接报错：node –throw-deprecation app.js
• 日志与命名空间调试
  • 简单打印：console.log(‘state:’, state)
  • 使用 debug 库按命名空间控制输出：

    const debug = require('debug')('myapp');
    debug('current user: %o', user);
    

  • 启动时开启命名空间（示例）：DEBUG=myapp node app.js*

四 远程与应急调试

• 远程调试（安全做法）
  • 服务器启动：node –inspect=9229 app.js
  • 本地建立 SSH 隧道（将远端 9229 映射到本地 9221）：ssh -L 9221:localhost:9229 user@remote.example.com
  • 本地 Chrome 访问 chrome://inspect 连接 localhost:9221
• 应急附加（已启动进程）
  • 查找进程号：ps aux | grep app.js
  • 触发调试：node -e ‘process._debugProcess()’
  • 或发送信号：kill -SIGUSR1 （仅 Linux/Unix，注意权限与安全性）

五 进阶 源码级 GDB 调试 Node.js

• 适用场景
  • 排查 Node.js 引擎/原生模块 问题、崩溃、性能瓶颈等
• 构建调试版 Node

  git clone https://github.com/nodejs/node.git
  cd node
  ./configure --debug && make -j$(nproc)
  

• 常见内存不足导致构建被杀（SIGKILL）
  • 临时增加交换分区（示例创建 10G）：

    sudo mkdir -p /opt/swap
    sudo dd if=/dev/zero of=/opt/swap/swap bs=1M count=10240
    sudo mkswap /opt/swap/swap
    sudo swapon /opt/swap/swap
    

• GDB 调试

  gdb --args ./node_g src/node_main.cc
  (gdb) b main
  (gdb) r
  

• 提示
  • 调试版构建体积大、性能慢，仅在需要深入底层时使用