Linux环境下Node.js日志配置指南

Linux环境下Node.js日志配置指南

在Linux服务器上部署Node.js应用，日志管理是保障应用可观测性和稳定性的基石。一套清晰、高效且易于维护的日志方案，能让你在问题发生时快速定位，在日常运维中洞察趋势。接下来，我们就从选型到实践，系统地梳理一遍。

一 基础方案与日志库选型

万事开头难，选对工具就成功了一半。在Node.js生态里，日志方案的选择相当丰富。

最直接的方式是使用内置的console对象。它上手零成本，非常适合快速原型开发和调试阶段。不过，到了生产环境，它的局限性就暴露出来了——缺乏级别控制、无法结构化输出、难以持久化。因此，生产环境通常建议将其输出重定向到文件，或者直接接入更专业的日志框架。

说到专业的日志框架，市面上有几个久经考验的选择：

• Winston：可以说是社区生态最成熟的选手。它的优势在于“灵活”，支持多种传输方式（文件、控制台、HTTP等），格式可定制，通过扩展能轻松满足各种奇葩需求。
• Pino：如果你追求极致的性能，Pino会是你的菜。它的设计目标就是低开销和高吞吐量，特别适合高并发场景。配合pino-pretty，在开发时也能获得友好的可读性。
• Bunyan：由Node.js之父创建，默认采用JSON格式输出，一切为了机器解析和日志检索服务，与ELK等日志系统是天作之合。
• Log4js：功能非常全面，从按日期、文件大小滚动日志，到多输出目标配置，它都能很好地支持，灵感来源于Ja va界的经典框架Log4j。

选好了库，接下来得定规矩：日志级别。通常建议按重要性从低到高使用：error, warn, info, http, verbose, debug。关键技巧在于，通过环境变量（例如LOG_LEVEL）来动态控制输出级别。这样一来，在开发环境可以放开到debug看细节，在生产环境收紧到error或warn，既灵活又安全。

二 快速上手示例

理论说再多，不如代码看一眼。下面用几个例子，带你快速实现几种常见需求。

使用 Winston 输出到控制台与文件（按级别分流）

// logger.js
const winston = require('winston');
const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
    winston.format.errors({ stack: true }),
    winston.format.splat(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
    new winston.transports.File({ filename: 'logs/combined.log' })
  ]
});

if (process.env.NODE_ENV !== 'production') {
  logger.add(new winston.transports.Console({
    format: winston.format.combine(
      winston.format.colorize(),
      winston.format.simple()
    )
  }));
}
module.exports = logger;

这个配置做了几件事：设置了默认日志级别，统一了带时间戳的JSON格式，把错误日志单独输出到error.log，所有日志汇总到combined.log，并且在非生产环境额外输出彩色的控制台日志，方便调试。

使用 Pino 高性能输出（开发环境美化）

// logger-pino.js
const pino = require('pino');
const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  timestamp: pino.stdTimeFunctions.isoTime
}, pino.destination('./logs/app.log'));

// 开发时可在控制台美化输出
if (process.env.NODE_ENV !== 'production') {
  const pretty = require('pino-pretty');
  logger.info = (...args) => require('pino').info(pretty({ colorize: true }), ...args);
}
module.exports = logger;

Pino的配置非常简洁，核心就是高性能。这里同样根据环境变量切换级别，并指定了日志文件路径。下面的代码片段演示了如何在开发环境“劫持”一下info方法，接入pino-pretty来获得彩色输出，兼顾了生产性能与开发体验。

使用 Log4js 按日期滚动

// logger-log4js.js
const log4js = require('log4js');
log4js.configure({
  appenders: {
    out: { type: 'stdout' },
    app: {
      type: 'dateFile',
      filename: 'logs/app',
      pattern: 'yyyy-MM-dd.log',
      alwaysIncludePattern: true,
      daysToKeep: 90,
      compress: true
    }
  },
  categories: {
    default: { appenders: ['out', 'app'], level: 'info' }
  }
});
const logger = log4js.getLogger();
module.exports = logger;

Log4js的强项在于其强大的Appender机制。这个配置定义了两个输出：标准输出和按日期滚动的文件。注意dateFile类型，它会自动生成类似logs/app-2023-10-27.log的文件，并保留90天，过期自动清理和压缩，非常省心。

运行与级别控制

LOG_LEVEL=debug node app.js

启动应用时，通过环境变量临时调整日志级别，是排查问题的常用手段。上面这行命令就将日志级别设置为了debug。

以上几个示例，基本覆盖了控制台与文件输出、按级别分流、JSON结构化、开发/生产差异化以及按日期滚动这些核心需求。

三 日志轮转与保留策略

日志文件不能任由其无限增长，否则迟早会撑爆磁盘。这就引出了日志轮转（Log Rotation）的概念。主要有两种思路：系统级方案和应用内方案。

系统级方案 logrotate（推荐与 Node.js 解耦）

这是Linux系统的标准姿势，优点是与应用进程完全解耦，由系统统一管理，策略一致。

• 安装：如果系统还没装，可以执行命令安装。Debian/Ubuntu系用sudo apt-get install logrotate；CentOS/RHEL系用sudo yum install logrotate。
• 创建配置：在/etc/logrotate.d/目录下为你的应用创建一个配置文件，比如/etc/logrotate.d/nodejs-app：

/path/to/your/nodejs/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 640 root adm
    sharedscripts
    postrotate
        # 若你的进程支持 USR1 触发重新打开日志，可在此发送信号
        # [ ! -f /var/run/nodeapp.pid ] || kill -USR1 $(cat /var/run/nodeapp.pid)
    endscript
}

这个配置的意思是：每天轮转一次，保留最近7天的日志，启用压缩（延迟到下一次轮转时压缩），如果日志文件不存在也不报错，空文件不轮转，轮转后创建新的日志文件并设置权限。

• 测试与强制执行：配置好后，可以先干跑测试一下：sudo logrotate -d /etc/logrotate.d/nodejs-app。确认无误后，可以用sudo logrotate -f /etc/logrotate.d/nodejs-app强制执行一次轮转。

应用内方案（库自带轮转）

有些日志库自身就集成了轮转功能，用起来更直接。

• Winston + winston-daily-rotate-file：这是一个第三方传输器，专为Winston打造。

const DailyRotateFile = require('winston-daily-rotate-file');
const transport = new DailyRotateFile({
  filename: 'logs/application-%DATE%.log',
  datePattern: 'YYYY-MM-DD',
  zippedArchive: true,
  maxSize: '20m',
  maxFiles: '14d'
});

• Log4js dateFile：正如上一节的示例所示，其dateFile类型的appender原生支持按日期滚动、保留天数（daysToKeep）和压缩（compress）。

何时选择哪种方案

这没有绝对答案，但可以遵循一些原则：系统级方案适合追求运维统一、多进程多实例的场景，它能避免应用内文件句柄竞争和轮转逻辑不一致的问题。应用内方案则提供了更细粒度的控制（比如按文件大小触发），并且配置跟随应用代码，打包和迁移更方便。

四 运行方式与系统日志集成

应用怎么跑，也决定了日志怎么管。

使用 PM2 管理进程与日志

PM2不仅是进程守护工具，其日志管理功能也相当强大。

• 安装与启动：sudo npm install -g pm2安装后，用pm2 start app.js --name my-app启动应用。
• 查看日志：pm2 logs my-app可以查看所有进程的实时日志。如果想分离标准输出和错误输出，可以在启动配置或生态文件中指定error_file和out_file路径。
• 内置日志轮转插件：PM2提供了一个官方插件pm2-logrotate，安装后（pm2 install pm2-logrotate）可以通过命令轻松设置，例如：

pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 5
pm2 set pm2-logrotate:workerInterval 2

这就设置了单个日志文件最大10M，保留5个备份，每2小时检查一次。

使用 systemd + journalctl

如果你习惯将Node.js应用注册为系统服务（systemd service），那么日志会自动集成到系统的journal中。查看日志的命令是journalctl -u your-service-name。加上-f可以实时跟踪，用--since或--until可以按时间过滤，非常强大。

常用命令行查看

一些经典的Linux命令依然是查看日志的利器：tail -f app.log实时追踪最新日志；cat app.log查看全部内容；grep “error” app.log快速过滤出错误行。简单，但有效。

五 生产实践与注意事项

最后，分享几条在生产环境中摸爬滚打总结出的经验，算是避坑指南。

• 结构化是王道：始终采用JSON等结构化格式输出日志。这看似为机器准备，实则是为了未来的你。当需要接入ELK、EFK或Grafana Loki等日志平台时，结构化日志能直接被解析和检索，效率天差地别。当然，在开发环境可以接入美化工具提升可读性。
• 分级分流，聚焦问题：一定要将不同级别的日志分开，尤其是错误日志。把error级别的日志单独写入一个文件，这样设置监控告警时目标明确，排查问题时也能直击要害。info、warn这些可以放在综合日志里。
• 规范字段，保护敏感信息：每条日志都应包含足够的上下文，比如时间戳（timestamp）、级别（level）、服务名（service）、请求ID（trace_id）、消息（msg）以及错误的堆栈（err.stack）。同时，务必警惕，绝对不要在日志里记录密码、密钥、令牌等敏感信息。
• 管理生命周期：结合磁盘容量，制定合理的日志保留策略（比如保留7天、14天或30天），并启用压缩。定期清理历史日志，这既是资源管理，也符合一些数据安全规范。
• 告别裸奔的 console.log：在生产环境，请务必使用成熟的日志库。它们提供的可配置性、可扩展性和一致性，是console.log无法比拟的，这是保障应用可观测性的底线。
• 多进程场景下的选择：如果你的应用以集群模式或多实例运行，优先考虑使用系统级的logrotate或PM2的日志机制。这能有效避免多个进程同时写入和轮转同一个日志文件时可能出现的竞争和错乱问题。

说到底，日志配置没有一成不变的银弹，关键是根据你的应用规模、团队习惯和运维体系，选择并组合最适合的工具与策略。希望这份指南能帮你搭建起一个坚实可靠的日志基础。