NestJS 项目日志管理终极指南：Winston 的深度配置与实践

你好，老铁！我是老码农，很高兴能和你聊聊 NestJS 项目中日志管理这个重要的环节。一个优秀的日志系统就像飞机的黑匣子，能够帮助我们记录关键信息，快速定位和解决问题，提升项目的可维护性和稳定性。今天，我们就来深入探讨一下如何在 NestJS 项目中使用 Winston 这个强大的日志库，以及如何根据不同的场景配置 Winston，让你的日志系统变得更加强大和灵活。

为什么选择 Winston？

Winston 是一个功能强大且灵活的 Node.js 日志库，它支持多种传输方式（如控制台、文件、数据库等），可以自定义日志级别、格式和输出方式。与 NestJS 完美集成，能让你在项目中轻松实现日志的集中管理和个性化定制。以下是 Winston 的几个主要优点：

• 灵活性： 支持多种传输方式，可以同时将日志输出到控制台、文件、数据库等。
• 可定制性： 允许自定义日志级别、格式和输出方式，满足不同项目的需求。
• 易于使用： 提供了简洁易用的 API，方便开发者快速集成。
• 扩展性： 支持自定义日志格式器、传输器等，可以根据需要进行扩展。
• 与 NestJS 集成： 可以轻松地与 NestJS 的依赖注入系统集成，实现日志的全局管理。

在 NestJS 中安装 Winston

首先，我们需要在项目中安装 Winston 和 @nestjs/platform-express（用于在 NestJS 中使用 Express）：

npm install winston @nestjs/platform-express

Winston 的基本配置

1. 创建 LoggerService

为了方便在 NestJS 项目中使用 Winston，我们可以创建一个 LoggerService，将 Winston 的实例封装起来。创建一个 logger.service.ts 文件，内容如下：

// logger.service.ts
import { Injectable, Logger, ConsoleLogger, LogLevel } from '@nestjs/common';
import { createLogger, format, transports } from 'winston';
import { utilities as nestWinstonModuleUtilities } from 'nest-winston';
 
@Injectable()
export class LoggerService extends ConsoleLogger {
  private readonly logger = createLogger({
    level: 'info',
    format: format.combine(
      format.timestamp(),
      format.ms(),
      nestWinstonModuleUtilities.format.nestLike(),
    ),
    transports: [
      new transports.Console(),
      // new transports.File({ filename: 'error.log', level: 'error' }),
      // new transports.File({ filename: 'combined.log' }),
    ],
  });
 
  log(message: any, ...optionalParams: any[]) {
    super.log(message, ...optionalParams);
    this.logger.info(message, ...optionalParams);
  }
 
  error(message: any, ...optionalParams: any[]) {
    super.error(message, ...optionalParams);
    this.logger.error(message, ...optionalParams);
  }
 
  warn(message: any, ...optionalParams: any[]) {
    super.warn(message, ...optionalParams);
    this.logger.warn(message, ...optionalParams);
  }
 
  debug(message: any, ...optionalParams: any[]) {
    super.debug(message, ...optionalParams);
    this.logger.debug(message, ...optionalParams);
  }
 
  verbose(message: any, ...optionalParams: any[]) {
    super.verbose(message, ...optionalParams);
    this.logger.verbose(message, ...optionalParams);
  }
}

2. 注册 LoggerService

在 app.module.ts 中注册 LoggerService，以便在整个项目中注入使用：

// app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { LoggerService } from './logger.service';
 
@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService, LoggerService],
})
export class AppModule {}

3. 使用 LoggerService

在你的 Controller 或 Service 中注入 LoggerService 并使用它来记录日志：

// app.service.ts
import { Injectable } from '@nestjs/common';
import { LoggerService } from './logger.service';
 
@Injectable()
export class AppService {
  constructor(private readonly logger: LoggerService) {}
 
  getHello(): string {
    this.logger.log('Hello World! This is a log message.');
    this.logger.error('This is an error message.');
    this.logger.warn('This is a warning message.');
    this.logger.debug('This is a debug message.');
    this.logger.verbose('This is a verbose message.');
    return 'Hello World!';
  }
}

现在，当你运行 NestJS 项目时，你将在控制台中看到 Winston 记录的日志信息。

Winston 的高级配置

1. 日志级别

Winston 支持以下日志级别，从高到低排序：

• error：错误信息，表示程序遇到了严重的问题，需要立即关注。
• warn：警告信息，表示程序可能存在潜在的问题，需要注意。
• info：普通信息，用于记录程序运行的常规信息。
• http：HTTP 请求信息，用于记录 HTTP 请求的详细信息。
• verbose：详细信息，用于记录比 debug 级别更详细的信息。
• debug：调试信息，用于记录程序运行过程中的调试信息。
• silly：最详细的信息，用于记录程序运行的所有信息。

你可以通过 level 选项来设置日志级别，例如：

const logger = createLogger({
  level: 'debug',
  // ...其他配置
});

2. 日志格式

Winston 提供了强大的日志格式化功能，你可以自定义日志的输出格式，包括时间戳、日志级别、消息内容等。Winston 使用 format 模块来处理日志格式化，常用的格式化选项包括：

• format.combine()：用于组合多个格式化选项。
• format.timestamp()：添加时间戳。
• format.printf()：自定义输出格式。
• format.json()：将日志转换为 JSON 格式。
• format.colorize()：为日志添加颜色，方便在控制台中查看。
• format.simple()：简单的日志格式，只包含日志级别和消息内容。
• format.splat()：用于处理参数，类似于 Node.js 的 util.format()。

以下是一些常见的日志格式配置示例：

a. 简单的文本格式

const logger = createLogger({
  format: format.combine(
    format.timestamp(),
    format.printf(({ timestamp, level, message }) => {
      return `${timestamp} [${level.toUpperCase()}] ${message}`;
    }),
  ),
  // ...其他配置
});

b. JSON 格式

const logger = createLogger({
  format: format.combine(
    format.timestamp(),
    format.json(),
  ),
  // ...其他配置
});

c. 带有颜色的文本格式

const logger = createLogger({
  format: format.combine(
    format.timestamp(),
    format.colorize(),
    format.printf(({ timestamp, level, message }) => {
      return `${timestamp} [${level.toUpperCase()}] ${message}`;
    }),
  ),
  // ...其他配置
});

3. 传输器 (Transports)

传输器是 Winston 的核心组件，它负责将日志输出到不同的目标，如控制台、文件、数据库等。Winston 提供了多种内置的传输器，同时也支持自定义传输器。常用的传输器包括：

• transports.Console：将日志输出到控制台。
• transports.File：将日志输出到文件。
• transports.Http：将日志发送到 HTTP 服务器。
• transports.MongoDB：将日志存储到 MongoDB 数据库。
• transports.Elasticsearch：将日志发送到 Elasticsearch。

你可以通过 transports 选项来配置传输器，例如：

const logger = createLogger({
  transports: [
    new transports.Console(),
    new transports.File({ filename: 'error.log', level: 'error' }),
    new transports.File({ filename: 'combined.log' }),
  ],
  // ...其他配置
});

4. 异常处理

为了更好地处理程序中的异常，Winston 提供了异常处理功能。你可以使用 handleExceptions 选项来配置异常处理，将未捕获的异常记录到日志中。例如：

const logger = createLogger({
  // ...其他配置
  exceptionHandlers: [
    new transports.File({ filename: 'exceptions.log' }),
  ],
  exitOnError: false,
});

exitOnError 选项控制在发生异常时是否退出程序，默认为 true。将它设置为 false 可以避免程序意外退出。

5. 异步日志

在某些情况下，同步地写入日志可能会阻塞程序的执行，影响性能。为了解决这个问题，Winston 提供了异步日志功能。你可以使用 winston-transport 库来创建自定义的异步传输器。以下是一个简单的异步文件传输器的示例：

// async-file-transport.ts
import { Transport, TransportStreamOptions } from 'winston';
import * as fs from 'fs';
import * as util from 'util';
 
const writeFile = util.promisify(fs.writeFile);
 
export class AsyncFile extends Transport {
  private filename: string;
 
  constructor(opts: TransportStreamOptions & { filename: string }) {
    super(opts);
    this.filename = opts.filename;
  }
 
  async log(info: any, callback: () => void) {
    setImmediate(() => {
      this.emit('logged', info);
    });
 
    try {
      await writeFile(this.filename, `${info.timestamp} [${info.level.toUpperCase()}] ${info.message}\n`, { flag: 'a' });
      callback();
    } catch (err) {
      console.error('Async file transport error:', err);
      callback(err);
    }
  }
}

在 logger.service.ts 中使用异步文件传输器：

// logger.service.ts
import { AsyncFile } from './async-file-transport';
// ...其他导入
 
@Injectable()
export class LoggerService extends ConsoleLogger {
  private readonly logger = createLogger({
    level: 'info',
    format: format.combine(
      format.timestamp(),
      format.ms(),
      nestWinstonModuleUtilities.format.nestLike(),
    ),
    transports: [
      new transports.Console(),
      new AsyncFile({ filename: 'combined.log' }),
    ],
  });
  // ...其他代码
}

6. 集成 NestJS 的配置模块

为了更好地管理 Winston 的配置，你可以使用 NestJS 的配置模块。首先，安装 @nestjs/config：

npm install @nestjs/config

然后在 app.module.ts 中配置配置模块：

// app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { LoggerService } from './logger.service';
 
@Module({
  imports: [ConfigModule.forRoot()],
  controllers: [AppController],
  providers: [AppService, LoggerService],
})
export class AppModule {}

接下来，在 logger.service.ts 中使用配置模块来读取配置：

// logger.service.ts
import { Injectable, Logger, ConsoleLogger, LogLevel, Inject } from '@nestjs/common';
import { createLogger, format, transports } from 'winston';
import { utilities as nestWinstonModuleUtilities } from 'nest-winston';
import { ConfigService } from '@nestjs/config';
import { AsyncFile } from './async-file-transport';
 
@Injectable()
export class LoggerService extends ConsoleLogger {
  private readonly logger = createLogger({
    level: this.configService.get<string>('LOG_LEVEL') || 'info',
    format: format.combine(
      format.timestamp(),
      format.ms(),
      nestWinstonModuleUtilities.format.nestLike(),
    ),
    transports: [
      new transports.Console(),
      new AsyncFile({ filename: this.configService.get<string>('LOG_FILE') || 'combined.log' }),
    ],
  });
 
  constructor(@Inject(ConfigService) private readonly configService: ConfigService) {
    super();
  }
 
  log(message: any, ...optionalParams: any[]) {
    super.log(message, ...optionalParams);
    this.logger.info(message, ...optionalParams);
  }
 
  error(message: any, ...optionalParams: any[]) {
    super.error(message, ...optionalParams);
    this.logger.error(message, ...optionalParams);
  }
 
  warn(message: any, ...optionalParams: any[]) {
    super.warn(message, ...optionalParams);
    this.logger.warn(message, ...optionalParams);
  }
 
  debug(message: any, ...optionalParams: any[]) {
    super.debug(message, ...optionalParams);
    this.logger.debug(message, ...optionalParams);
  }
 
  verbose(message: any, ...optionalParams: any[]) {
    super.verbose(message, ...optionalParams);
    this.logger.verbose(message, ...optionalParams);
  }
}

最后，在 .env 文件中配置日志相关的环境变量：

LOG_LEVEL=debug
LOG_FILE=application.log

7. 自定义日志格式器

除了使用 Winston 提供的内置格式器外，你还可以自定义日志格式器，以满足更个性化的需求。例如，你可以创建一个格式器来添加自定义的字段，或者对敏感信息进行脱敏处理。以下是一个自定义日志格式器的示例：

// custom-format.ts
import { format } from 'winston';
 
export const customFormat = format((info) => {
  const { timestamp, level, message, ...rest } = info;
  const customFields = {
    application: 'my-application',
    environment: process.env.NODE_ENV || 'development',
    ...rest,
  };
 
  return {
    timestamp,
    level,
    message,
    ...customFields,
  };
})();

在 logger.service.ts 中使用自定义格式器：

// logger.service.ts
import { customFormat } from './custom-format';
 
@Injectable()
export class LoggerService extends ConsoleLogger {
  private readonly logger = createLogger({
    level: 'info',
    format: format.combine(
      format.timestamp(),
      format.ms(),
      nestWinstonModuleUtilities.format.nestLike(),
      customFormat,
    ),
    transports: [
      new transports.Console(),
      new transports.File({ filename: 'combined.log' }),
    ],
  });
  // ...其他代码
}

8. 日志分割与轮转

为了避免日志文件过大，你可以使用日志分割和轮转功能。Winston 本身不提供此功能，但你可以使用第三方库，如 winston-daily-rotate-file。首先，安装 winston-daily-rotate-file：

npm install winston-daily-rotate-file

然后在 logger.service.ts 中配置 winston-daily-rotate-file：

// logger.service.ts
import * as DailyRotateFile from 'winston-daily-rotate-file';
 
@Injectable()
export class LoggerService extends ConsoleLogger {
  private readonly logger = createLogger({
    level: 'info',
    format: format.combine(
      format.timestamp(),
      format.ms(),
      nestWinstonModuleUtilities.format.nestLike(),
    ),
    transports: [
      new transports.Console(),
      new DailyRotateFile({
        filename: 'application-%DATE%.log',
        dirname: 'logs',
        datePattern: 'YYYY-MM-DD',
        zippedArchive: true,
        maxSize: '20m',
        maxFiles: '14d',
      }),
    ],
  });
  // ...其他代码
}

在这个配置中：

• filename：日志文件名，%DATE% 会被替换为日期。
• dirname：日志文件存放的目录。
• datePattern：日期格式。
• zippedArchive：是否压缩旧的日志文件。
• maxSize：每个日志文件的最大大小。
• maxFiles：保留的日志文件数量。

最佳实践与常见问题

1. 选择合适的日志级别

• error： 记录程序无法正常运行的错误，例如数据库连接失败、文件读取失败等。
• warn： 记录可能导致问题的情况，例如使用了过时的 API、配置了不推荐的选项等。
• info： 记录程序运行的常规信息，例如用户登录、数据更新等。
• debug： 记录程序运行的详细信息，用于调试和排查问题。
• verbose： 记录比 debug 更详细的信息，用于更深入的调试。

在生产环境中，通常使用 info 或 warn 级别，而在开发和测试环境中，可以使用 debug 或 verbose 级别。

2. 统一日志格式

为了方便日志的分析和处理，建议使用统一的日志格式。例如，你可以使用 JSON 格式，并包含时间戳、日志级别、消息内容、应用程序名称、环境信息等字段。

3. 敏感信息保护

在记录日志时，要注意保护敏感信息，例如密码、API 密钥、个人身份信息等。你可以使用脱敏处理，将敏感信息替换为占位符，或者将敏感信息加密后再记录到日志中。

4. 异步写入日志的注意事项

使用异步写入日志可以提高程序的性能，但也要注意潜在的问题。例如，在程序退出时，可能还没有来得及将所有日志写入文件，导致日志丢失。为了解决这个问题，你可以在程序退出前，手动调用日志库的 close() 方法，或者使用 flush() 方法来强制将日志写入文件。

5. 日志的集中管理

对于大型项目，建议使用日志集中管理系统，例如 ELK (Elasticsearch, Logstash, Kibana) 或 Graylog。这些系统可以收集、存储、分析和可视化日志，帮助你更好地监控和管理程序的运行状态。

6. 避免过度日志记录

过度日志记录会占用大量的磁盘空间和计算资源，也会影响程序的性能。因此，你需要根据实际情况，选择合适的日志级别和记录频率，避免过度日志记录。

7. 解决日志丢失问题

• 使用异步日志，并确保在程序退出前将日志写入文件。 可以使用 flush() 或 close() 方法。
• 使用可靠的传输器， 例如 winston-daily-rotate-file，可以自动分割和轮转日志，避免日志文件过大。
• 监控日志系统的运行状态， 及时发现和解决问题。

8. 性能优化

• 使用异步日志。 避免同步写入日志阻塞程序的执行。
• 选择合适的日志级别。 避免记录过多的日志信息。
• 优化日志格式。 避免使用复杂的格式化操作。
• 使用缓存。 对于频繁调用的日志记录，可以使用缓存来减少 I/O 操作。

总结

今天，我们详细介绍了在 NestJS 项目中使用 Winston 进行日志管理的各种配置选项，包括日志级别、日志格式、传输器、异常处理、异步日志、集成 NestJS 的配置模块、自定义日志格式器以及日志分割与轮转。通过这些配置，你可以构建一个强大、灵活且易于维护的日志系统，帮助你更好地监控和管理你的 NestJS 项目。

记住，日志管理是一个持续优化的过程。根据项目的实际需求和环境，不断调整和完善你的日志系统，才能让它发挥最大的作用。希望这篇指南对你有所帮助！如果你在实践过程中遇到任何问题，欢迎随时提问，我们一起探讨，共同进步！