@xilil/log

功能完善的 TypeScript 日志库，支持多级别日志记录、彩色输出、时间戳、模块化等特性。

功能特性

• 🌈 彩色输出 - 不同日志级别使用不同颜色显示
• ⏰ 时间戳 - 自动添加时间戳，支持自定义格式
• 📦 模块化 - 支持为不同模块创建独立的日志器
• 🎯 级别控制 - 支持设置最小日志级别，过滤不需要的日志
• 🔧 可配置 - 丰富的配置选项，满足不同需求
• 📊 扩展功能 - 支持 JSON 输出、表格显示、计时器等

安装

pnpm add @xilil/log

基本使用

快速开始

import { logger } from '@xilil/log'

// 基本日志记录
logger.info('应用启动成功')
logger.warn('这是一个警告')
logger.error('发生了错误')
logger.debug('调试信息')
logger.fatal('致命错误')

日志级别

日志库支持 5 个级别：

• DEBUG (0) - 调试信息
• INFO (1) - 一般信息
• WARN (2) - 警告信息
• ERROR (3) - 错误信息
• FATAL (4) - 致命错误

创建具名日志器

import { createLogger } from '@xilil/log'

const userLogger = createLogger('用户模块')
const dbLogger = createLogger('数据库')

userLogger.info('用户登录成功', { userId: 123 })
dbLogger.error('数据库连接失败')

配置日志器

import { configure, LogLevel } from '@xilil/log'

// 全局配置
configure({
  minLevel: LogLevel.WARN,     // 只显示警告及以上级别
  enableColors: false,         // 禁用彩色输出
  showTimestamp: true,         // 显示时间戳
  showLevel: true,             // 显示日志级别
  showModule: true,            // 显示模块名称
  prefix: '[MyApp]'            // 添加前缀
})

创建自定义日志器

import { Logger, LogLevel } from '@xilil/log'

const customLogger = new Logger({
  minLevel: LogLevel.DEBUG,
  enableColors: true,
  showTimestamp: true,
  timestampFormat: () => new Date().toLocaleString('zh-CN')
}, '自定义模块')

customLogger.debug('这是调试信息')

高级功能

JSON 日志

import { logger, LogLevel } from '@xilil/log'

const user = { id: 1, name: '张三', email: '[email protected]' }
logger.json(LogLevel.INFO, '用户信息:', user)

表格输出

const users = [
  { id: 1, name: '张三', age: 25 },
  { id: 2, name: '李四', age: 30 }
]

logger.table(LogLevel.INFO, '用户列表:', users)

带标签的日志

const apiLogger = createLogger('API')

apiLogger.tagged('HTTP', LogLevel.INFO, 'GET /api/users', { status: 200 })
apiLogger.tagged('DB', LogLevel.ERROR, '查询失败', { error: 'connection timeout' })

计时器

logger.time('数据库查询')
// ... 执行查询操作
logger.timeEnd('数据库查询')  // 输出: 数据库查询: 123.456ms

堆栈跟踪

logger.trace('追踪错误位置')

子日志器

const mainLogger = createLogger('主模块')
const subLogger = mainLogger.child('子模块')

subLogger.info('这是子模块的日志')
// 输出: [时间戳] [INFO] [主模块] [子模块] 这是子模块的日志

配置选项

interface LoggerConfig {
  /** 最小日志级别，低于此级别的日志不会输出 */
  minLevel?: LogLevel
  /** 是否启用彩色输出 */
  enableColors?: boolean
  /** 是否显示时间戳 */
  showTimestamp?: boolean
  /** 是否显示日志级别 */
  showLevel?: boolean
  /** 是否显示模块名称 */
  showModule?: boolean
  /** 日志前缀 */
  prefix?: string
  /** 时间戳格式函数 */
  timestampFormat?: () => string
}

使用场景

Express 应用

import express from 'express'
import { createLogger } from '@xilil/log'

const app = express()
const logger = createLogger('Express')

app.use((req, res, next) => {
  logger.info(`${req.method} ${req.path}`, { 
    ip: req.ip,
    userAgent: req.get('User-Agent')
  })
  next()
})

app.listen(3000, () => {
  logger.info('服务器启动成功', { port: 3000 })
})

错误处理

import { createLogger, LogLevel } from '@xilil/log'

const errorLogger = createLogger('错误处理')

process.on('uncaughtException', (error) => {
  errorLogger.fatal('未捕获的异常:', error)
  process.exit(1)
})

process.on('unhandledRejection', (reason, promise) => {
  errorLogger.error('未处理的 Promise 拒绝:', { reason, promise })
})

数据库操作

import { createLogger } from '@xilil/log'

const dbLogger = createLogger('数据库')

async function queryUser(id: number) {
  dbLogger.debug('查询用户', { id })
  
  try {
    const user = await db.user.findById(id)
    dbLogger.info('用户查询成功', { userId: id, found: !!user })
    return user
  } catch (error) {
    dbLogger.error('用户查询失败', { userId: id, error })
    throw error
  }
}

环境变量配置

日志系统支持通过环境变量自动配置，无需手动设置：

自动环境配置

# 开发环境 - 显示 DEBUG 及以上级别，启用彩色输出
NODE_ENV=development

# 测试环境 - 显示 INFO 及以上级别，启用彩色输出  
NODE_ENV=test

# 生产环境 - 显示 WARN 及以上级别，禁用彩色输出
NODE_ENV=production

手动指定日志级别

# 直接指定日志级别（优先级高于 NODE_ENV）
LOG_LEVEL=DEBUG    # 显示所有日志
LOG_LEVEL=INFO     # 显示 INFO 及以上级别
LOG_LEVEL=WARN     # 显示 WARN 及以上级别
LOG_LEVEL=ERROR    # 只显示错误日志
LOG_LEVEL=FATAL    # 只显示致命错误

控制彩色输出

# 强制启用或禁用彩色输出（优先级高于 NODE_ENV）
LOG_COLORS=true    # 强制启用彩色输出
LOG_COLORS=false   # 强制禁用彩色输出

查看当前配置

import { env } from '@xilil/log'

// 获取环境信息
const info = env.getEnvironmentInfo()
console.log(info)
// 输出: {
//   NODE_ENV: 'development',
//   LOG_LEVEL: 'auto',
//   LOG_COLORS: 'auto',
//   currentLogLevel: 'DEBUG',
//   colorsEnabled: true
// }

// 打印配置信息
env.printLogConfig()
// 输出:
// === 日志系统配置信息 ===
// 环境: development
// 日志级别: DEBUG (auto)
// 彩色输出: 启用 (auto)
// ========================

环境变量优先级

1. LOG_LEVEL - 直接指定日志级别
2. NODE_ENV - 根据环境自动设置
3. 默认值 - INFO 级别

完整示例

# .env 文件
NODE_ENV=development
LOG_LEVEL=DEBUG
LOG_COLORS=true

import { logger } from '@xilil/log'

// 无需手动配置，自动根据环境变量设置
logger.debug('调试信息')  // 开发环境会显示
logger.info('一般信息')   // 所有环境都会显示
logger.warn('警告信息')   // 测试和生产环境会显示
logger.error('错误信息')  // 所有环境都会显示

手动配置（可选）

如果需要手动配置，仍然可以使用 configure 函数：

性能考虑

• 日志级别过滤在格式化之前进行，避免不必要的字符串操作
• 彩色输出可以通过 enableColors: false 关闭以提高性能
• 在生产环境建议设置较高的日志级别，减少 I/O 操作

许可证

MIT