Ubuntu Nodejs应用如何调试

Ubuntu 上调试 Node.js 的高效方法

一 内置调试与 Chrome DevTools

• 启动方式
  • 普通启动：node --inspect app.js（程序继续运行，等待调试器连接，默认调试端口为 9229）
  • 首行暂停：node --inspect-brk app.js（在第一行自动中断，便于从入口处逐步调试）
• 连接与调试
  • 在 Chrome 打开：chrome://inspect，在 Remote Target 中点击 inspect 或 Open dedicated DevTools for Node，即可使用熟悉的 Sources/Console/Network/Memory/Profiler 面板进行断点、单步、观察表达式与性能分析。
  • 也可直接访问 http://127.0.0.1:9229/json 获取 DevTools 前端地址并打开。
• 原理提示
  • Node 通过 Chrome DevTools Protocol（CDP） 与 DevTools 建立 WebSocket 通信；在 Console 中展开深层对象时，Node 会向 V8 查询对象信息，因此更适合在存在阻塞/等待的场景（如 HTTP 监听）下进行交互式调试。

二 使用 VS Code 调试

• 快速开始
  • 在 VS Code 中打开项目，点击左侧 运行与调试，创建 .vscode/launch.json，选择 Node.js 环境。
• 常用配置
  • 直接启动
    • 配置示例：
      • {
        • “version”: “0.2.0”,
        • “configurations”: [
          • {
            • “type”: “node”,
            • “request”: “launch”,
            • “name”: “Launch Program”,
            • “program”: “${workspaceFolder}/app.js”,
            • “console”: “integratedTerminal”,
            • “env”: { “NODE_ENV”: “development” }
          • }
        • ]
      • }
  • 附加到已运行进程
    • 先在应用中启动：node --inspect-brk app.js
    • 配置示例：
      • {
        • “version”: “0.2.0”,
        • “configurations”: [
          • {
            • “type”: “node”,
            • “request”: “attach”,
            • “name”: “Attach to Process”,
            • “port”: 9229
          • }
        • ]
      • }
• 调试能力
  • 支持断点、条件断点、函数断点、监视表达式、调用栈查看、变量面板与实时求值，适合日常开发闭环调试。

三 进阶场景与技巧

• 调试 npm 包或 CLI
  • 在 package.json 中新增脚本，显式指向可执行脚本并开启调试，例如调试 webpack：
    • “scripts”: { “build:debug”: “node --inspect --inspect-brk ./node_modules/webpack/bin/webpack.js” }
    • 运行：npm run build:debug，再用 VS Code attach 或 chrome://inspect 连接。
• 监听文件变更自动重启并调试
  • 使用 Node.js 实验性 watch：node --watch --inspect-brk app.js
  • 使用 nodemon：在 VS Code 配置
    • {
      • “type”: “node”,
      • “request”: “launch”,
      • “name”: “Debug with nodemon”,
      • “runtimeExecutable”: “nodemon”,
      • “program”: “${workspaceFolder}/app.js”,
      • “restart”: true,
      • “console”: “integratedTerminal”,
      • “env”: { “NODE_ENV”: “development” }
    • }
• 已运行进程“无侵入”附加
  • 查找进程 PID：ps aux | grep app.js
  • 方式一：node -e ‘process._debugProcess(PID)’
  • 方式二：kill -SIGUSR1 PID（Node.js ≥8 支持，将进程切换到调试模式）
• 选择性日志
  • 代码：const debug = require(‘debug’)(‘myapp:server’); debug(‘start’);
  • 启用：DEBUG=myapp:* node app.js（或 DEBUG=myapp:server node app.js）
• TypeScript 调试
  • 使用 tsx（对 node 的封装，支持 –inspect 与 –watch）：
    • npm i -D tsx
    • tsx --inspect server.ts

四 常见问题与排查

• 看不到目标进程
  • 确认启动时包含 –inspect 或 –inspect-brk，并检查端口 9229 是否被占用或被防火墙拦截；必要时显式指定地址：–inspect=127.0.0.1:9229。
• 无法展开深层对象或数据不完整
  • 在 DevTools Console 中展开对象时，Node 会通过 CDP 向 V8 拉取信息；若程序不阻塞（立即退出或无等待），对象可能来不及序列化。建议在 HTTP 请求处理、定时任务 等会等待的事件中查看，或使用 –inspect-brk 从断点处逐步检查。
• 附加失败
  • 确认目标进程已以 –inspect 启动并监听 9229，且本机访问未被限制；必要时改用 127.0.0.1 回环地址进行本地调试。