在 Debian 环境里调试 Node.js，很多问题并不是“看不到”，而是日志零散、字段不统一，导致真正有用的信息埋在大量输出里。本文按“先把日志打好、再分层查看、最后补上调试器和日志治理”的顺序整理一套实用方法，帮助你判断问题究竟出在应用代码、进程管理，还是系统与内核层面。
先把日志变成可检索的结构化输出
如果还在大量使用 console.log 打点，项目一旦变大，日志很快就会变得难以筛选。更适合线上和日常排查的做法，是统一输出 JSON 结构日志，这样后续无论用 grep、jq，还是接入日志平台，都能按字段快速定位。
常见方案里，winston 功能更完整，pino 更强调性能。下面沿用原文的 winston 配置，重点在三件事：按环境切换日志级别、同时写入控制台与文件、为每条日志补齐时间戳和 JSON 格式。
const winston = require('winston');
const logger = winston.createLogger({
level: process.env.NODE_ENV === 'production' ? 'warn' : 'debug', // 动态调整级别
format: winston.format.combine(
winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), // 添加时间戳
winston.format.json() // 结构化输出
),
transports: [
new winston.transports.Console(), // 开发时输出到终端
new winston.transports.File({ filename: 'error.log', level: 'error' }), // 错误日志单独存储
new winston.transports.File({ filename: 'combined.log' }) // 所有日志汇总
]
});
// 示例：记录请求和错误
app.use((req, res, next) => {
logger.info(`Request: ${req.method} ${req.url}`, { userId: req.user?.id }); // 关联用户上下文
next();
});
app.use((err, req, res, next) => {
logger.error(`Unhandled Error: ${err.message}`, { stack: err.stack, url: req.url }); // 记录堆栈跟踪
res.status(500).send('Internal Server Error');
});
这样做的直接好处，是后续可以围绕 userId、url、stack 这些字段检索，而不是在整段自然语言日志里手工翻找。对于接口报错、特定用户异常、某一路由偶发失败这类问题，定位速度会明显提升。
排查时先看哪类日志：应用、系统还是内核
Debian 下的 Node.js 故障，通常可以分成三层：应用自身日志、系统服务日志、内核日志。先分层看，再决定是否需要进入断点调试，效率会高很多。
应用日志：先确认业务请求和错误堆栈
如果应用已经把日志写入文件，例如 combined.log 和 error.log，第一步通常就是实时跟踪输出：
tail -f /path/to/your/app/combined.log
# 实时查看所有日志
tail -f /path/to/your/app/error.log
# 仅查看错误日志
只关注错误级别时，可以直接叠加过滤：
grep "ERROR" /path/to/your/app/combined.log
# 提取错误日志
这一层最适合排查接口异常、数据库连接失败、请求上下文缺失、未处理异常等问题。如果你在日志里已经补充了请求方法、URL、用户 ID，这一步往往就能把问题范围缩到很小。
系统日志：确认服务启动、端口和权限问题
如果应用层日志没有给出足够线索，下一步就该看 Debian 的系统日志。像进程启动失败、端口被占用、权限不足、服务被拉起后立刻退出，这类问题经常会先出现在 syslog 或 journalctl 里。
sudo tail -f /var/log/syslog | grep node
# 过滤Node.js相关日志
如果应用通过 systemd 管理，则更建议直接看对应服务：
sudo journalctl -u your-nodejs-service -f
# 替换为你的服务名（如nodeapp.service）
这类日志特别适合确认服务是否被正确拉起、是否反复重启，以及错误到底来自 Node.js 应用本身，还是运行环境配置。
内核日志：处理资源不足和底层冲突
当问题已经超出应用和服务层，例如怀疑内存不足、驱动冲突，或者系统层面对进程做了异常处理，就需要看内核日志：
dmesg | grep node
# 过滤Node.js相关内核日志
这一步不是每次都要用，但一旦遇到进程无故退出、系统资源异常、容器或宿主机环境不稳定，dmesg 往往能补上应用日志里完全没有的信息。
用 PM2 把日志和进程状态集中管理
如果你的 Node.js 应用长期运行在 Debian 服务器上，PM2 仍然是很常见的管理方式。它的价值不只是自动重启，还在于把应用输出和错误输出集中到固定目录，减少手工找日志文件的时间。
常用 PM2 日志查看命令
pm2 logs
# 查看所有应用的实时日志
pm2 logs your-app-name
# 查看特定应用的日志
pm2 logs --lines 100
# 查看最近100行日志
PM2 默认会把日志写到 ~/.pm2/logs/，例如 your-app-name-out.log 和 your-app-name-error.log。这意味着你既可以用 PM2 自带命令看，也可以继续配合 tail、grep 做进一步筛选。
日志轮转要尽早开启
长期运行的服务如果只追加日志、不做清理，磁盘被写满只是时间问题。PM2 可以通过下面的命令启用日志轮转：
pm2 install pm2-logrotate
对线上环境来说，这一步很实际。它不能替代完整的日志治理，但至少能先避免日志文件无限膨胀。
日志不够时，再接入交互式调试器
日志适合回答“哪里出错了”，但遇到复杂逻辑分支、异步流程异常、变量状态和调用顺序需要现场观察时，就该切换到交互式调试。
使用 Node.js 内置调试器
通过 --inspect-brk 启动应用后，进程会停在首行代码，等待调试器连接：
node --inspect-brk app.js
接着打开 Chrome，访问 chrome://inspect，点击“为Node打开专用DevTools”，就可以设置断点、查看变量和单步执行。适合排查代码明明进入了某个分支、但最终结果不符合预期的情况。
在 VS Code 里配置断点调试
如果日常开发主要在 VS Code 中完成，可以直接在项目根目录创建 .vscode/launch.json：
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug Node.js App",
"program": "${workspaceFolder}/app.js",
"preLaunchTask": "npm: start", // 可选：启动应用的任务
"outFiles": ["${workspaceFolder}/**/*.js"],
"sourceMaps": true // 若使用TypeScript，需开启
}
]
}
按 F5 启动后，就能在编辑器里直接看调用栈、变量值和断点命中情况。对需要反复单步排查的业务逻辑来说，这通常比纯日志更省时间。
生产环境要补上的两件事：轮转与集中管理
调试效率高不高，除了看不看日志，还取决于日志会不会失控。线上 Node.js 服务常见的两个管理动作，是文件轮转和集中式收集。
使用 winston-daily-rotate-file 控制文件体积
npm install winston-daily-rotate-file
配置示例如下：
const DailyRotateFile = require('winston-daily-rotate-file');
const logger = winston.createLogger({
transports: [
new DailyRotateFile({
filename: 'application-%DATE%.log', // 文件名格式：application-2025-09-23.log
datePattern: 'YYYY-MM-DD', // 按天分割
zippedArchive: true, // 压缩旧日志
maxSize: '20m', // 单个文件最大20MB
maxFiles: '14d' // 保留14天
})
]
});
这里的重点参数都很实用：datePattern 控制切分周期，maxSize 防止单文件过大，maxFiles 限定保留周期。对多数中小型服务来说，这已经足够应对日常日志增长。
规模变大后，考虑集中式日志平台
当应用实例变多、排查依赖跨机器检索时，单机日志文件就开始吃力了。原文提到的 ELK Stack（Elasticsearch + Logstash + Kibana）和 Graylog，都是常见的集中式方案。
如果要把日志直接发送到 Elasticsearch，可以使用：
npm install winston-elasticsearch
配置示例：
const ElasticsearchTransport = require('winston-elasticsearch');
const logger = winston.createLogger({
transports: [
new ElasticsearchTransport({
level: 'info',
clientOpts: { node: 'http://localhost:9200' } // Elasticsearch地址
})
]
});
集中式平台的意义，不只是把日志“放到一起”，更关键的是支持统一搜索、可视化和告警。对于多服务环境里的端口冲突、依赖缺失、数据库连接失败、跨实例复现问题，这类能力会比单纯翻文件高效得多。
一套更适合 Debian 的 Node.js 调试思路
把整个过程串起来看，Debian 下调试 Node.js 最实用的路径通常是：先输出结构化日志，再按应用、系统、内核三层查看，必要时交给 PM2 集中管理，最后再用 --inspect-brk 或 VS Code 进入交互式调试。这样做的好处，是你能更快判断问题属于代码、服务配置还是系统环境，而不是一上来就在海量日志里盲目搜索。
