Node.js 项目调试指南

Node.js 项目调试指南

🧭 一、调试工具和方式总览

方式	难度	场景	说明
console.log 调试	★	简单问题定位	最常见，但效率低
debug 模块	★★	模块化输出日志	支持命名空间的调试日志
VSCode 断点调试	★★★	跟踪函数调用、变量状态	推荐使用
node inspect / ndb	★★★★	CLI 下高级调试	脚本、远程调试
日志管理工具（如 winston）	★★	生产调试	日志分级管理
APM 工具（如 New Relic）	★★★★★	生产级监控	对系统性能进行监控

---

📌 二、使用 console.log() 基础调试（初级）

这是最常见的调试方式：

app.get('/user/:id', (req, res) => {
  console.log('User ID:', req.params.id);
  res.send('OK');
});

优点： 简单直接
缺点： 多处嵌套或异步函数中难以追踪，不适合生产环境

---

🎯 三、使用 debug 模块进行模块化日志调试（推荐）

1. 安装

npm install debug

2. 使用方法

const debug = require('debug')('myapp:server');

app.get('/test', (req, res) => {
  debug('This is a test log');
  res.send('debugging');
});

3. 开启调试

运行项目时开启对应命名空间：

DEBUG=myapp:* node app.js

---

🛠️ 四、使用 VSCode 进行断点调试（强烈推荐）

1. 配置 launch.json

在 .vscode/launch.json 中添加如下配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Express App",
      "program": "${workspaceFolder}/app.js",
      "env": {
        "NODE_ENV": "development"
      },
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

2. 添加断点并运行调试

• 在代码行号左侧点击添加断点；
• 在 VSCode 左侧点击 ▶️ “Debug Express App”；
• 使用调试控制台查看变量、调用栈等信息。

---

🔍 五、使用 node inspect CLI 调试

1. 启动带调试的 Node.js 程序

node inspect app.js

或使用 Chrome DevTools：

node --inspect-brk app.js

然后打开 Chrome，访问：chrome://inspect

---

📜 六、集成日志记录工具（如 winston）

1. 安装

npm install winston

2. 使用示例

const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.simple()
  ),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'logs/app.log' })
  ]
});

logger.info('Server started');
logger.error('Something went wrong');

---

📡 七、远程和生产环境调试

• 使用 PM2 管理进程并查看日志：

npm install pm2 -g
pm2 start app.js --name my-app
pm2 logs my-app

• 使用 APM 工具（如 New Relic、Datadog）监控性能、内存、错误。

---

🧠 八、调试 Express 中间件和异步代码注意事项

1. 异步代码中的错误追踪

app.get('/', async (req, res, next) => {
  try {
    const data = await fetchData();
    res.send(data);
  } catch (err) {
    next(err);
  }
});

2. 错误处理中间件

app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('Something broke!');
});

---

✅ 总结

调试方式	推荐场景	难度
console.log	快速测试	低
debug	日志分类调试	中
VSCode 调试	开发断点、变量跟踪	中高
node inspect	命令行调试	高
winston	日志归档、记录	中
APM 工具	生产环境监控	高

---