Linux 下 Node.js 日志管理实操指南
日志，是应用在服务器上留下的“足迹”。一套清晰、高效的日志管理体系，不仅是排查问题的“时光机”，更是洞察系统健康状况的“听诊器”。今天，我们就来聊聊在 Linux 环境下，如何为你的 Node.js 应用构建一套既专业又易于维护的日志方案。
一 核心原则与选型
在动手之前，先明确几个核心原则，这能帮你少走弯路。
- 使用结构化日志：这是生产环境的黄金标准。优先选择 JSON 格式，它天生便于后续的检索、聚合与分析。开发环境则可以灵活一些，同时输出可读性更好的文本到控制台，方便调试。社区里成熟的库不少，比如 Winston、Pino、Bunyan、Log4js。其中，Pino 以其卓越的高性能著称，尤其适合高并发场景。关于日志级别，一个实用的建议是按环境区分：生产环境通常设为 info 或 warn 级别，避免海量的 debug 日志；开发环境则可以放开 debug，以便洞察细节。最后，切记避免滥用
console.log，它不仅性能不佳，也缺乏可控的级别和输出渠道。
二 快速落地方案
理论说再多，不如动手一试。下面提供三种即拿即用的方案，你可以根据项目复杂度选择。
- 使用 Winston 的文件与控制台输出（按级别分流）
- 安装：
npm i winston - 配置与用法：
这个配置实现了按级别分流：错误日志单独存文件，所有日志汇总到另一个文件，并且在非生产环境同时输出到控制台。const winston = require('winston'); const logger = winston.createLogger({ level: 'info', format: winston.format.json(), transports: [ new winston.transports.File({ filename: 'error.log', level: 'error' }), new winston.transports.File({ filename: 'combined.log' }), ...(process.env.NODE_ENV !== 'production' ? [new winston.transports.Console({ format: winston.format.simple() })] : []), ], }); logger.info('上线完成', { version: '1.2.3' }); logger.error('异常发生', { err: err.message, stack: err.stack });
- 安装：
- 使用 Pino（高吞吐、低开销）
- 安装：
npm i pino - 配置与用法：
Pino 的 API 非常简洁，性能是其最大卖点，适合对吞吐量要求极高的服务。const pino = require('pino'); const logger = pino({ level: process.env.NODE_ENV === 'production' ? 'info' : 'debug' }); logger.info({ path: '/health' }, '健康检查通过'); logger.error({ err: err }, '请求处理失败');
- 安装：
- 使用 PM2 运行与聚合日志
- 启动：
pm2 start app.js -n myapp - 实时查看：
pm2 logs myapp - 保存当前进程列表：
pm2 sa ve - PM2 不仅是一个进程管理器，它还提供了开箱即用的多进程日志聚合与内置的日志轮转能力。这对于集群或多实例部署的场景来说，能极大地简化日志收集的复杂度。
- 启动：
三 日志轮换与清理
日志文件不能任其无限增长，否则迟早会撑满磁盘。轮换与清理是生产环境运维的必修课，主要有两种思路。
- 应用内轮换（代码可控、与进程生命周期一致）
- Winston + DailyRotateFile（按天/按大小）
这种方式通过代码配置，可以精确控制轮换策略（如按日期、按文件大小）和压缩选项。const { createLogger, format, transports } = require('winston'); const DailyRotateFile = require('winston-daily-rotate-file'); const transport = new DailyRotateFile({ filename: 'logs/app-%DATE%.log', datePattern: 'YYYY-MM-DD', zippedArchive: true, maxSize: '20m', maxFiles: '14d', }); const logger = createLogger({ level: 'info', format: format.combine(format.timestamp(), format.json()), transports: [transport, new transports.Console({ format: format.simple() })], }); - Pino 生态：可使用 pino-rotate 等社区插件来实现类似的按周期或大小轮转与压缩功能。
- Winston + DailyRotateFile（按天/按大小）
- 系统级轮换（通用、与 Node 无关，适合容器/多进程）
- logrotate 配置示例（/etc/logrotate.d/nodejs）：
这是 Linux 系统的标准方案，通过 cron 任务驱动。它独立于应用，即使应用重启也不影响轮换。/path/to/your/nodejs/logs/*.log { daily missingok rotate 7 compress notifempty create 0640 root adm } - 定时清理（可选）：
0 0 * * * find /path/to/your/nodejs/logs -type f -name "*.log" -mtime +7 -delete这条 crontab 命令可以辅助清理超过一定天数的旧日志文件。
- logrotate 配置示例（/etc/logrotate.d/nodejs）：
- 选择建议：单进程或容器化部署，优先考虑应用内轮换，集成度高；如果是多实例部署或物理机混部，系统级的 logrotate 往往是更通用、更稳妥的选择，能减少对特定语言或库的依赖，降低运维复杂度。
四 集中式日志与监控
当服务数量增多、架构变得复杂后，登录一台台服务器去查日志就变得不现实了。这时，集中式日志管理便提上日程。
- 将日志发送到 ELK Stack（Elasticsearch、Logstash、Kibana）或 Graylog 这类专业平台，可以实现跨服务器的日志统一检索、可视化图表展示以及基于日志内容的告警。Fluentd 也是一个优秀的统一日志采集与转发工具。
- 示例：Winston 写入 Elasticsearch
const { createLogger } = require('winston'); const ElasticsearchTransport = require('winston-elasticsearch'); const logger = createLogger({ level: 'info', transports: [ new ElasticsearchTransport({ level: 'info', clientOpts: { node: 'https://localhost:9200' }, index: 'logs-app-%DATE%', }), ], }); - 更进一步，可以结合 Prometheus + Grafana 来监控错误率、请求延迟等关键指标，并设置告警。这样就构建起了“日志（问题定位）+ 指标（态势感知）”一体化的可观测性体系，让系统状态一目了然。
五 错误与异常治理
最后，也是最重要的一环：如何优雅地记录错误。混乱的错误日志等于没有日志。
- 统一错误日志：确保在所有的 try/catch 块和 Promise.catch 中，都使用结构化的方式记录错误。同时，必须为未捕获的异常（uncaughtException）和未处理的 Promise 拒绝（unhandledRejection）设置全局兜底处理。
process.on('unhandledRejection', (reason, promise) => { logger.error('Unhandled Rejection', { reason, promise }); // 视情况安全退出或降级 }); process.on('uncaughtException', (err) => { logger.error('Uncaught Exception', { err, stack: err.stack }); // 记录后安全退出，由进程管理器（如PM2）重启 process.exit(1); }); - 建议始终输出的字段：为了让日志在排查时真正有用，每条日志，尤其是错误日志，建议至少包含以下几个核心字段：timestamp（时间戳）、level（级别）、message（消息）、以及 context（上下文，如 requestId、userId）。这就像给每条日志打上了多维度的“标签”，让追踪和定位问题变得高效精准。
