@iap/logger

跨环境统一日志系统，在浏览器中使用 CSS %c 彩色输出，在 Node.js / SSR 中使用 ANSI 转义码彩色输出，支持级别控制、样式定制与单次调用覆盖。

特性

• 跨环境：自动识别运行时环境——浏览器使用 CSS 着色，Node.js 使用 ANSI 着色
• 级别控制：trace < debug < info < warn < error < fatal < system，可配置最低输出级别
• 结构化样式：通过 JS 对象定义 label/content 的颜色、加粗、斜体、下划线，无需手写 CSS/ANSI 字符串
• 单次覆盖：将 LogStyle.style({...}) 作为最后一个参数传入，仅对该次调用生效
• 服务名前缀：为日志打上模块或服务标识，方便在复杂应用中快速定位
• 运行时开关：通过 open: false 全局关闭输出，无需删除日志语句
• 零运行时依赖，完整 TypeScript 类型支持

安装

pnpm add @iap/logger
Copy

快速上手

import { logger, setLoggerConfig } from '@iap/logger'

// 全局配置
setLoggerConfig({ serviceName: 'App', level: 'info' })

// 基础用法
logger.info('服务启动成功')
logger.warn('接口响应较慢', { latency: '800ms' })
logger.error('请求失败', new Error('timeout'))
logger.fatal('不可恢复的严重错误')
logger.system('构建完成')
Copy

API 参考

logger

默认日志实例，所有方法支持任意数量的参数。

setLoggerConfig(options)

对全局配置进行浅合并更新，levelStyles 也做浅合并。

import { setLoggerConfig } from '@iap/logger'

setLoggerConfig({
    level: 'warn',         // 最低输出级别
    serviceName: 'Auth',   // 每条日志的前缀标识
    open: false,           // 全局关闭输出
})
Copy

setLevelStyle(level, style)

单独更新某个级别的默认样式，不影响其他级别。

import { setLevelStyle } from '@iap/logger'

setLevelStyle('error', { label: { color: 'red', bold: true } })
Copy

LogStyle.style(style) — 单次调用样式覆盖

作为最后一个参数传入任意日志方法，仅对该次调用覆盖样式。

import { logger, LogStyle } from '@iap/logger'

logger.info(
    '转账成功',
    LogStyle.style({
        label:   { color: '#00c853', bold: true },
        content: { color: '#2db7f5' },
    }),
)
Copy

loggerOptions

当前全局配置对象（可读，修改请使用 setLoggerConfig）。

级别优先级

trace(0) < debug(1) < info(2) < warn(3) < error(4) < fatal(5) < system(6)
Copy

只有级别 ≥ 配置 level 的日志才会输出。system 始终具有最高优先级。

类型导出

import type {
    Logger,
    LoggerOptions,
    Level,
    LevelStyle,
    LevelStyles,
    StructuredStyle,
} from '@iap/logger'
Copy