winston

Winston Logger - 快速参考

何时使用此技能

• 使用多个传输器进行日志记录（文件、控制台、HTTP）
• 使用自定义级别进行结构化日志记录
• 自动轮换日志文件

深入了解：使用 technology 为 winston 的 mcp__documentation__fetch_docs 获取完整文档。

基本设置

npm install winston

核心模式

Logger 基础

import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' }),
  ],
});

// Add console in development
if (process.env.NODE_ENV !== 'production') {
  logger.add(new winston.transports.Console({
    format: winston.format.simple(),
  }));
}

自定义格式

const customFormat = winston.format.printf(({ level, message, timestamp, ...meta }) => {
  return `${timestamp} [${level.toUpperCase()}]: ${message} ${Object.keys(meta).length ? JSON.stringify(meta) : ''}`;
});

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.timestamp(),
    customFormat
  ),
  transports: [new winston.transports.Console()],
});

子 Logger

const childLogger = logger.child({ requestId: req.id, module: 'auth' });
childLogger.info('User authenticated', { userId: user.id });

按日轮换文件

import DailyRotateFile from 'winston-daily-rotate-file';

const transport = new DailyRotateFile({
  filename: 'logs/app-%DATE%.log',
  datePattern: 'YYYY-MM-DD',
  maxSize: '20m',
  maxFiles: '14d',
});

logger.add(transport);

何时不使用此技能

• 高性能 API：改用 Pino，速度比 Winston 快 10 倍
• 仅使用 JSON 的日志记录：Pino 对结构化 JSON 输出的优化程度更高
• 无服务器/Lambda：优先使用更简单的控制台日志记录，或使用 Pino 以降低开销
• Python/Java 项目：使用对应语言的日志框架
• 简单脚本：基本调试使用内置的 console 即可

反模式

反模式	不良之处	解决方案
同步文件日志记录	阻塞事件循环，降低性能	使用带有 { stream: ... } 的异步传输器
不序列化就记录对象	可能记录 [Object]，而非数据本身	使用 JSON.stringify() 或 Winston JSON 格式
不轮换日志	生产环境中的磁盘空间会被占满	使用 winston-daily-rotate-file
在紧密循环中记录日志	I/O 负担过重，占满磁盘	添加条件逻辑或对日志进行采样
字符串拼接	即使禁用日志，也会始终执行	使用格式字符串：logger.info('User %s', userId)
缺少错误堆栈跟踪	丢失调试上下文	使用 { error: err } 或 Winston 错误格式

快速故障排除

问题	原因	解决方案
日志未显示	配置了错误的日志级别	检查 logger.level 和传输器级别
性能下降	同步写入文件	使用异步传输器或减少日志详细程度
磁盘已满	未轮换日志	使用 maxFiles 配置 winston-daily-rotate-file
日志中出现 [Object]	对象格式不当	使用 winston.format.json() 或 winston.format.prettyPrint()
日志重复	多个传输器指向同一目标	检查传输器配置
未显示颜色	控制台传输器缺少 colorize	在控制台传输器中添加 winston.format.colorize()