NestJS 日志进阶：Winston 集成、最佳实践与安全策略

2025/3/9 19:25:58 188 0 0 0

作为一名后端开发，想必你一定体会过日志的重要性。好的日志系统就像飞机的“黑匣子”，在系统出现问题时，能帮你快速定位问题、还原现场，是排查 bug 的利器。而对于 Node.js 开发来说，Winston 绝对是日志库中的佼佼者，它灵活、强大，拥有丰富的特性，能满足各种场景下的日志需求。

今天，咱们就来聊聊如何在 NestJS 项目中玩转 Winston，我会结合自己多年的项目经验，分享一些实用的技巧和最佳实践，帮你打造一个稳如泰山的日志系统。

为什么选择 Winston？

在 Node.js 的世界里，日志库可谓百花齐放，但 Winston 凭啥能脱颖而出呢？

灵活性：Winston 最大的特点就是灵活，你可以自定义日志的格式、输出方式、传输方式等等。无论是简单的控制台输出，还是复杂的日志聚合、分析，Winston 都能轻松应对。
强大的功能：Winston 提供了丰富的特性，比如日志级别、日志过滤、日志轮转、异常处理等等，基本上你能想到的日志功能，它都有。
社区活跃：Winston 拥有庞大的用户群体和活跃的社区，这意味着你在使用过程中遇到问题，很容易就能找到解决方案或者得到帮助。
与 NestJS 无缝集成：NestJS 官方推荐使用 Winston 作为日志库，并且提供了方便的集成方式，我们可以很轻松地在 NestJS 项目中使用 Winston。

NestJS 集成 Winston

在 NestJS 中集成 Winston 非常简单，主要有两种方式：

1. 使用 NestJS 内置的 Logger

NestJS 内置了一个 Logger 类，它其实是对 Winston 的一个简单封装，提供了基本的日志功能。如果你对日志的需求比较简单，可以直接使用它。

import { Logger } from '@nestjs/common';

export class MyService {
  private readonly logger = new Logger(MyService.name);

  doSomething() {
    this.logger.log('Doing something...');
    this.logger.error('Something went wrong!');
    this.logger.warn('Be careful!');
    this.logger.debug('Debugging information');
    this.logger.verbose('Detailed information');
  }
}

NestJS 内置的 Logger 默认使用控制台输出，并且支持 5 种日志级别：log、error、warn、debug、verbose。你可以通过环境变量 LOG_LEVEL 来控制日志级别，比如 LOG_LEVEL=error 表示只输出 error 级别的日志。

2. 自定义 Winston Logger

如果 NestJS 内置的 Logger 无法满足你的需求，你可以自定义 Winston Logger。

首先，安装 Winston：

npm install winston

然后，创建一个 logger.service.ts 文件：

import { Injectable, LoggerService } from '@nestjs/common';
import * as winston from 'winston';

@Injectable()
export class WinstonLogger implements LoggerService {
  private readonly logger: winston.Logger;

  constructor() {
    this.logger = winston.createLogger({
      level: 'info', // 默认日志级别
      format: winston.format.combine(
        winston.format.timestamp(), // 添加时间戳
        winston.format.json() // 使用 JSON 格式
      ),
      transports: [
        new winston.transports.Console(), // 输出到控制台
        // 可以添加其他 transports，比如文件、数据库等
      ],
    });
  }

  log(message: string, context?: string) {
    this.logger.log('info', message, { context });
  }

  error(message: string, trace?: string, context?: string) {
    this.logger.error(message, { trace, context });
  }

  warn(message: string, context?: string) {
    this.logger.warn(message, { context });
  }

  debug(message: string, context?: string) {
    this.logger.debug(message, { context });
  }

  verbose(message: string, context?: string) {
    this.logger.verbose(message, { context });
  }
}

接下来，在 app.module.ts 中替换默认的 Logger：

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { WinstonLogger } from './logger.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService, { provide: Logger, useClass: WinstonLogger }],
})
export class AppModule {}

这样，你就可以在整个应用中使用自定义的 Winston Logger 了。你可以根据自己的需求，配置 Winston 的各种选项，比如日志级别、格式、输出方式等等。

Winston 最佳实践

掌握了 Winston 的基本用法，咱们再来聊聊一些最佳实践，让你的日志系统更上一层楼。

1. 合理设置日志级别

日志级别是日志系统的重要组成部分，它可以帮助你过滤掉不重要的日志信息，只关注关键的日志。Winston 支持多种日志级别，常用的有：

error：错误信息，表示系统发生了错误，需要立即处理。
warn：警告信息，表示系统可能存在问题，需要关注。
info：普通信息，表示系统正常运行的一些信息。
debug：调试信息，用于开发调试，通常不应该出现在生产环境中。
verbose：详细信息，比 debug 更详细的信息，通常只在开发调试时使用。

在生产环境中，建议将日志级别设置为 info 或 warn，这样可以避免大量的 debug 和 verbose 日志淹没你的日志系统。在开发环境中，可以将日志级别设置为 debug 或 verbose，方便调试。

2. 使用结构化日志

传统的日志通常是纯文本格式，这种格式不利于日志的分析和查询。结构化日志使用 JSON 格式，将日志信息结构化，方便后续的分析和查询。

Winston 支持多种日志格式，其中 winston.format.json() 可以将日志格式化为 JSON 格式。

format: winston.format.combine(
  winston.format.timestamp(),
  winston.format.json()
)

3. 添加上下文信息

为了方便排查问题，建议在日志中添加上下文信息，比如请求 ID、用户 ID、模块名等等。这些信息可以帮助你快速定位问题发生的场景。

this.logger.log('info', 'User logged in', { userId: 123, requestId: 'abc' });

4. 日志轮转

随着时间的推移，日志文件会越来越大，如果不进行处理，可能会占用大量的磁盘空间。日志轮转可以将日志文件按照一定规则分割成多个文件，避免单个文件过大。

Winston 提供了 winston-daily-rotate-file 插件，可以实现日志轮转。

npm install winston-daily-rotate-file

import * as winston from 'winston';
import 'winston-daily-rotate-file';

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

const logger = winston.createLogger({
  // ...
  transports: [transport],
});

5. 异步日志

默认情况下，Winston 的日志操作是同步的，这意味着每次写入日志都会阻塞主线程。在高并发场景下，这可能会导致性能问题。为了解决这个问题，可以使用异步日志。

Winston 本身并不直接支持异步日志，但你可以通过一些技巧来实现，比如使用 winston.transports.File 的 lazy 选项，或者使用消息队列将日志写入操作异步化。

6. 异常处理

Winston 提供了 exceptionHandlers 选项，可以捕获未处理的异常，并将异常信息写入日志。

const logger = winston.createLogger({
  // ...
  exceptionHandlers: [
    new winston.transports.File({ filename: 'exceptions.log' }),
  ],
});

Winston 安全策略

日志中可能会包含敏感信息，比如用户密码、API 密钥等等。如果不进行处理，可能会导致安全问题。因此，我们需要采取一些安全措施来保护日志中的敏感信息。

1. 过滤敏感信息

在日志写入之前，可以对日志信息进行过滤，将敏感信息替换成占位符或者删除。

const logger = winston.createLogger({
  // ...
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message, ...args }) => {
      // 过滤敏感信息
      message = message.replace(/password=\w+/g, 'password=***');
      return `${timestamp} ${level}: ${message} ${JSON.stringify(args)}`;
    })
  ),
});

2. 日志加密

如果日志中包含高度敏感的信息，可以考虑对日志进行加密。Winston 本身并不直接支持日志加密，但你可以通过一些第三方库来实现，比如 crypto-js。

3. 日志访问控制

应该限制对日志文件的访问，只有授权的用户才能访问日志文件。你可以通过操作系统的文件权限来控制对日志文件的访问。

4. 日志审计

定期审计日志，检查是否有异常的日志记录，及时发现潜在的安全问题。

总结

日志系统是后端开发中不可或缺的一部分，一个好的日志系统可以帮助你快速定位问题、提高系统的稳定性。Winston 是一个功能强大、灵活的日志库，可以满足各种场景下的日志需求。在 NestJS 项目中，我们可以很方便地集成 Winston，并通过一些最佳实践和安全策略，打造一个稳如泰山的日志系统。

希望这篇文章能帮助你更好地理解和使用 Winston，如果你有任何问题或者建议，欢迎在评论区留言。

进一步思考

除了 Winston，还有哪些常用的 Node.js 日志库？它们各自有什么优缺点？
如何将 Winston 日志与 ELK Stack（Elasticsearch、Logstash、Kibana）集成，实现日志的集中管理和分析？
如何在微服务架构中使用 Winston？
Winston 日志如何做性能优化？
如何根据不同的环境（开发、测试、生产）配置不同的 Winston 日志？

全栈老王 NestJS Winston 日志