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 工具 | 生产环境监控 | 高 |
:基础类型)
