NestJS Boot

外观

日志系统 ​

基于 Winston 的日志方案，支持控制台输出、文件按日期/大小轮转、阿里云 SLS 远程日志。

基础用法 ​

typescript
import { createLogger, logger, WinstonLoggerService } from '@maxtan/nest-core'

// 初始化日志（在 main.ts 中调用）
createLogger()

// 使用 logger 记录
logger.info('普通信息')
logger.warn('警告信息')
logger.error('错误信息', errorObj)
logger.debug('调试信息')

自定义配置 ​

typescript
createLogger({
  useConsole: true, // 是否输出到控制台，默认 true
  maxDays: 30, // 日志文件保留天数，默认 30
  maxSize: '20m', // 单个文件最大大小，默认 20MB
  sls: {
    // 阿里云 SLS（可选）
    accessKeyId: 'your-ak',
    accessKeySecret: 'your-sk',
    endpoint: 'cn-hangzhou.log.aliyuncs.com',
    projectName: 'your-project',
    logStoreName: 'your-logstore',
    topic: 'nest-boot',
    source: 'source',
    env: 'production'
  }
})

集成到 NestJS ​

typescript
import { NestFactory } from '@nestjs/core'
import { createLogger, WinstonLoggerService } from '@maxtan/nest-core'

async function bootstrap() {
  createLogger({ useConsole: true })

  const app = await NestFactory.create(AppModule, {
    logger: new WinstonLoggerService()
  })

  await app.listen(3000)
}

文件轮转 ​

日志文件自动按日期和大小轮转，超期文件自动压缩归档：

logs/default-2026-02-10.log        # 当前文件
logs/default-2026-02-09.log.gz     # 已压缩归档
  • 自动按日期切割日志文件
  • 旧文件自动压缩为 .gz 格式，节省磁盘空间
  • 超过 maxDays（默认 30 天）的文件自动删除

配置参考 ​

AllLoggerOptions ​

参数类型默认值说明
useConsolebooleantrue是否输出到控制台
maxDaysnumber30日志文件保留天数
maxSizestring'20m'单个日志文件最大大小
slsSlsAppenderOptions-阿里云 SLS 配置

SlsAppenderOptions ​

参数类型默认值说明
accessKeyIdstring-阿里云 AccessKey ID
accessKeySecretstring-阿里云 AccessKey Secret
endpointstring'cn-hangzhou.log.aliyuncs.com'SLS 服务端点
projectNamestring-SLS 项目名称
logStoreNamestring-SLS 日志存储名称
topicstring'nest-boot'日志主题
sourcestring'source'日志来源
envstring'production'环境标识

最佳实践 ​

  1. 启动时初始化：在 main.ts 的最前面调用 createLogger()，确保所有日志都能被捕获
  2. 优先使用 LoggerModule：在 NestJS 上下文中推荐 LoggerModule.forRoot() 注册 + DI 注入，便于测试替换
  3. 区分环境：
    • 开发环境：useConsole: true
    • 生产环境：可关闭控制台，启用 SLS
  4. 合理保留期：根据存储空间设置 maxDays，默认 30 天
  5. 结构化信息：使用 logger.info({ traceId, action, duration }) 传入对象，便于日志检索
  6. 敏感信息：避免在日志中输出密码、Token 等字段，操作日志模块已内置自动脱敏

与 LoggerModule 的关系

createLogger() 初始化全局单例，LoggerModule.forRoot() 在 onModuleInit 时自动调用 createLogger() 并将 logger 注入 DI 容器。两者可以同时使用，但使用 LoggerModule 后不需要再手动调用 createLogger()。

相关文档 ​