@ldesign/log
v3.2.43
Published
一个轻量级、美观、功能丰富的日志输出工具,提供格式化的日志输出、级别控制、性能监控等功能。
Readme
@ldesign/log
LDesign 日志工具库 — 轻量级、美观、可扩展的前端日志输出方案。
概述
@ldesign/log 是 LDesign 生态的日志基础工具包,提供格式化的控制台输出、日志级别控制、性能监控、日志历史记录和传输器机制。适用于前端应用调试、线上排障日志聚合和性能分析等场景。
- 7 个日志级别:
DEBUG / LOG / INFO / SUCCESS / WARNING / ERROR / NONE - 带样式输出:浏览器中输出“时间戳/前缀 + 实底药丸徽章 + 浅底内容”三段式样式,自动按底色亮度挑选徽章文字对比度,亮色/暗色控制台主题均可读
- 独立实例:通过
createLogger创建状态完全隔离的日志实例(配置/历史/传输器/计时器/自定义类型互不影响) - DevTools 级别过滤:
error/warning分别经console.error/console.warn输出,控制台 Errors/Warnings 页签可直接过滤 - 自定义类型:注册业务专属日志类型(如 HTTP、DB 等),可配置图标与文字颜色
- 传输器机制:将日志发送到服务端或持久化存储
- 零业务运行时依赖:运行时仅依赖
@babel/runtime
安装
pnpm add @ldesign/log环境要求
- Node.js
>= 20.19.0 - 浏览器或 Node.js 环境均可使用(样式化输出仅在浏览器生效)
特性/核心能力
- 🎨 格式化输出:带颜色标签的日志输出、JSON 美化、表格、颜色块、欢迎横幅
- 🔢 级别控制:7 个日志级别(含
NONE完全禁用),可动态过滤 - ⏱ 性能监控:内置
time/timeEnd计时器(含清理防泄漏) - 📜 历史记录:可按级别、类型、关键词过滤和导出 JSON
- 🔌 传输器:支持服务端上报、本地持久化等扩展,可按级别过滤
- 🏭 生产模式:
enableInProduction控制生产环境日志开关 - 🏷 自定义类型:
registerType/typed注册业务日志类型 - 📦 Tree-Shaking:ESM 模块,支持按需引入
快速上手
import { Logger, LogLevel } from '@ldesign/log'
Logger.configure({
level: LogLevel.INFO,
prefix: 'MyApp',
showTimestamp: true,
})
Logger.info('应用启动完成')
Logger.success('用户登录成功')
Logger.warning('接口响应较慢')
Logger.error('订单提交失败', '业务错误', new Error('库存不足'))工作空间接入约定
LDesign 工作空间内各包接入本包时统一按下面三条执行,避免各包各写一套。
1. 一包一个 logger 模块,路径固定为 src/utils/logger.ts:
import { createLogger } from '@ldesign/log'
/** 模块日志实例,前缀固定为模块名 */
export const xxxLogger = createLogger('xxx', { enableInProduction: true })2. 必须显式写 enableInProduction: true。 默认值 false 在生产环境完全不输出,直接把裸 console.error 换成 Logger.error 会让线上错误"凭空消失"——除非该日志本来就包在 import.meta.env.DEV 或 process.env.NODE_ENV !== 'production' 里。
3. 方法映射与参数形态:
| 原写法 | 迁移后 | 说明 |
|---|---|---|
| console.warn(msg) | xxxLogger.warning(msg) | 走 console.warn,DevTools Warnings 可过滤 |
| console.error(msg, e) | xxxLogger.error(msg, undefined, e) | 第二个参数是标题,e 作为可展开参数追加 |
| console.warn(msg, a, b) | xxxLogger.warning(msg, undefined, a, b) | 多余参数原样追加 |
| console.group/groupEnd | xxxLogger.group/groupEnd | 分组标题走统一样式 |
| console.log(obj) | 保持原样或改用 prettyJson/dir | log(content) 只接字符串,别硬塞对象 |
不迁移的场景:Node/CLI 侧代码(packages/tool/**、packages/plugin/** 的终端输出,%c 样式在终端无效);各包 src/index-lib.ts 里的"整包引入"警告;纯调试遗留的 console.log。
4. 文案用中文,保留技术标识符。 日志正文用中文(如 加载配置失败),URL/JSON/HMR/方法名/属性名等技术标识符保留原文;模块标识前缀(如 [LDesignRouter])可保留便于 DevTools 过滤。内置徽章标题为中文(成功/错误/警告/信息/日志/调试)。级别使用:可恢复故障→error,可继续运行的异常→warning,调试细节→debug。
5. 全局级别门控(调试开关)。 所有 createLogger 实例共享全局最低级别门控,应用入口可一处控制全部输出:
import { setGlobalLevel, parseLogLevel, LogLevel } from '@ldesign/log'
setGlobalLevel(LogLevel.WARNING) // 仅保留 warning+error(生产安静)
setGlobalLevel(LogLevel.DEBUG) // 全量输出(联调模式)
setGlobalLevel(LogLevel.NONE) // 全部静默
setGlobalLevel(parseLogLevel('off')!) // 配置字符串亦可桌面应用可在 .ldesign/app.config.ts 用 logging: { enabled, level } 配置组驱动(由 desktop-core Engine 自动应用,HMR 实时生效);enabled: true → 全量输出,false → 仅 warning+error,显式 level 优先(支持 'off' 全静默)。
API 参考
LogLevel 枚举
级别数值越大越严重,用于日志过滤时的比较判断。
| 值 | 名称 | 描述 |
|----|------|------|
| 0 | DEBUG | 调试信息,最详细 |
| 1 | LOG | 一般日志 |
| 2 | INFO | 信息提示 |
| 3 | SUCCESS | 成功信息 |
| 4 | WARNING | 警告信息 |
| 5 | ERROR | 错误信息 |
| 6 | NONE | 完全禁用输出(级别过滤用,非输出类型) |
LogType 类型
内置六种类型,可通过 (string & {}) 扩展自定义字符串类型:
type LogType = 'success' | 'error' | 'warning' | 'info' | 'log' | 'debug' | (string & {})LogConfig 接口
| 属性 | 类型 | 描述 |
|------|------|------|
| title? | string | 日志标题前缀(如 "Error:") |
| color | string | 徽章底色(十六进制颜色值,必填,也用于派生内容区浅底色) |
| level | LogLevel | 该类型对应的日志级别 |
| ink? | string | 徽章文字颜色;缺省时按底色亮度自动挑选白字/深色字 |
| icon? | string | 级别图标字形(随徽章文字色着色);内置类型默认 ✓/✕/⚠/ℹ/●/◆,自定义类型默认无图标 |
| channel? | 'log' \| 'warn' \| 'error' | 显式指定输出到哪个 console 通道;缺省按级别自动路由(ERROR→error、WARNING→warn、其余→log) |
LogEntry 接口
interface LogEntry {
timestamp: number // 毫秒级时间戳
level: LogLevel // 日志级别
type: LogType // 日志类型
title: string // 标题
content: string // 内容
}TransportFn 与 Transport
type TransportFn = (entry: LogEntry) => void
interface Transport {
name: string // 传输器唯一名称
handler: TransportFn
level?: LogLevel // 最低触发级别,默认 DEBUG(全部触发)
}LoggerOptions 接口
| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| level | LogLevel | DEBUG | 低于此级别的日志被过滤 |
| enableInProduction | boolean | false | 生产环境是否输出日志 |
| prefix | string | '' | 日志前缀(配合 createLogger 标识来源) |
| showTimestamp | boolean | false | 是否显示时间戳 |
| maxStyleCacheSize | number | 50 | 样式缓存上限(LRU 淘汰) |
| enableHistory | boolean | false | 是否记录日志历史 |
| maxHistorySize | number | 500 | 历史记录条数上限 |
| timestampFormatter | (date: Date) => string | 内置 [HH:mm:ss.SSS] | 自定义时间戳格式 |
| transports | Transport[] | [] | 初始传输器列表 |
Logger 类 — 配置方法
| 方法 | 参数 | 描述 |
|------|------|------|
| configure(options) | LoggerOptions | 合并配置;更新 prefix/timestamp 时自动清空样式缓存 |
| getConfig() | — | 获取当前配置的只读副本 |
| resetConfig() | — | 重置配置为默认值并清空样式缓存 |
Logger 类 — 基础日志方法
| 方法 | 参数 | 描述 |
|------|------|------|
| success(content, title?) | string, string? | 成功日志(绿色 #5ed025) |
| error(content, title?, error?) | string, string?, Error? | 错误日志(红色),可附带输出错误堆栈 |
| warning(content, title?) | string, string? | 警告日志(橙色) |
| info(content, title?) | string, string? | 信息日志(蓝色) |
| log(content, title?) | string, string? | 一般日志(灰色) |
| debug(content, title?) | string, string? | 调试日志(浅灰) |
| print(title, content, color, level?) | string, string, string, LogLevel? | 通用带样式输出(底层核心方法) |
Logger 类 — 格式化输出
| 方法 | 参数 | 描述 |
|------|------|------|
| printTable(data, title?) | T[], string? | 以表格形式输出数据(console.table) |
| prettyJson(data, title?) | any, string? | 语法高亮输出 JSON(浏览器带样式,Node 纯文本) |
| separator(char?, length?, color?) | string?, number?, string? | 输出视觉分隔线 |
| dir(obj, depth?) | any, number? | 输出对象详细结构(封装 console.dir,默认深度 2) |
| image(url, size?) | string, number? | 在控制台输出图片(仅浏览器,非浏览器打印 URL) |
| color(color) | string | 显示单个颜色块 |
| colors(colors) | string[] | 水平排列显示多个颜色块 |
| welcome(title, version, docsUrl?) | string, string, string? | 显示应用欢迎横幅(带 3D 文字阴影) |
welcome未传docsUrl时,默认文档地址为https://wuhan.yxybb.com/ldesign。
Logger 类 — 分组与性能
| 方法 | 参数 | 描述 |
|------|------|------|
| group(label, collapsed?) | string, boolean? | 创建日志分组(可折叠) |
| groupEnd() | — | 结束当前分组 |
| time(label) | string | 开始高精度计时 |
| timeEnd(label, showDetails?) | string, boolean? | 结束计时并返回耗时(毫秒),无计时器返回 -1 |
| cleanupTimers(maxAge?) | number? | 清理超时未结束的计时器(默认 30 分钟) |
在浏览器环境中,每 1 小时会自动执行一次
cleanupTimers()防止计时器泄漏。
Logger 类 — 调试工具
| 方法 | 参数 | 描述 |
|------|------|------|
| assert(condition, content, title?) | boolean, string, string? | 条件为 false 时输出错误 |
| count(label?) | string? | 计数器累加并返回当前值(默认 'default') |
| countReset(label?) | string? | 重置指定计数器 |
| getCount(label?) | string? | 读取指定计数器当前值(不输出日志,不存在返回 0) |
| trace(message) | string | 输出调用栈 |
| clear() | — | 清空控制台 |
| exportToJson(data) | any | 将数据序列化为格式化 JSON 字符串 |
Logger 类 — 自定义类型
| 方法 | 参数 | 描述 |
|------|------|------|
| registerType(name, config) | string, LogConfig | 注册自定义日志类型(需提供 color) |
| unregisterType(name) | string | 注销自定义日志类型 |
| typed(type, content, title?) | string, string, string? | 使用自定义类型输出日志 |
| getRegisteredTypes() | — | 获取所有已注册的自定义类型名称 |
Logger 类 — 历史记录
需先 configure({ enableHistory: true }) 开启。
| 方法 | 参数 | 描述 |
|------|------|------|
| getHistory(filter?) | { level?, type?, keyword? } | 获取历史(支持级别/类型/关键词过滤,关键词不区分大小写) |
| clearHistory() | — | 清空历史记录 |
| exportHistory(filter?) | { level?, type?, keyword? } | 导出历史为 JSON 字符串 |
| getHistorySize() | — | 获取历史记录总条数 |
Logger 类 — 传输器
| 方法 | 参数 | 描述 |
|------|------|------|
| addTransport(transport) | Transport | 添加传输器(同名自动替换) |
| removeTransport(name) | string | 移除传输器 |
| getTransports() | — | 获取所有传输器名称 |
| clearTransports() | — | 清空所有传输器 |
Logger 类 — 批量与生命周期
| 方法 | 参数 | 描述 |
|------|------|------|
| batch(logs) | Array<{ content, type, title? }> | 批量输出日志(归入"批量日志"折叠分组,减少 I/O) |
| destroy() | — | 销毁并重置所有状态(计时器/缓存/计数/历史/传输器/自定义类型/配置) |
createLogger 工厂函数
function createLogger(name: string, options?: LoggerOptions): Logger创建独立的日志实例。通过内部生成 Logger 的子类实现静态状态隔离(配置、计时器、历史、传输器彼此独立),name 会作为默认日志前缀。
import { createLogger, LogLevel } from '@ldesign/log'
const authLogger = createLogger('Auth', { level: LogLevel.INFO })
const apiLogger = createLogger('API', { level: LogLevel.WARNING })
authLogger.success('登录成功')
apiLogger.warning('接口耗时超过 2s')配置
全局配置通过 Logger.configure(options) 完成,选项即上方 LoggerOptions 表格;也可在 createLogger(name, options) 时传入实例级初始配置。常用场景:
import { Logger, LogLevel } from '@ldesign/log'
// 生产环境开启日志(默认关闭)
Logger.configure({ enableInProduction: true })
// 只看 WARNING 及以上
Logger.configure({ level: LogLevel.WARNING })
// 开启历史记录
Logger.configure({ enableHistory: true, maxHistorySize: 1000 })目录结构
本包采用单文件架构,所有功能集中在 src/index.ts 中:
src/
└── index.ts # 单文件实现(Logger 类 + 枚举 + 接口 + createLogger)文件内组成:
LogLevel枚举 — 7 级日志级别定义LogType类型 — 日志类型联合类型(含自定义扩展)LogConfig/LogEntry/TransportFn/Transport/LoggerOptions接口与类型Logger类 — 核心日志工具类(全部为静态方法)createLogger函数 — 通过子类继承实现独立静态状态隔离的实例工厂- 默认导出
Logger
用法示例
自定义日志类型
import { Logger, LogLevel } from '@ldesign/log'
Logger.registerType('http', {
title: 'HTTP:',
color: '#1890ff',
level: LogLevel.DEBUG,
})
Logger.typed('http', 'GET /api/users 200 OK')传输器(日志上报)
import { Logger, LogLevel } from '@ldesign/log'
// 仅上报 ERROR 及以上级别的日志到远端
Logger.addTransport({
name: 'error-report',
level: LogLevel.ERROR,
handler: (entry) => {
navigator.sendBeacon('/api/logs', JSON.stringify(entry))
},
})性能计时
import { Logger } from '@ldesign/log'
Logger.time('数据加载')
await loadData()
const ms = Logger.timeEnd('数据加载', true) // showDetails=true 额外输出 info,返回耗时毫秒历史记录与导出
import { Logger, LogLevel } from '@ldesign/log'
Logger.configure({ enableHistory: true, maxHistorySize: 1000 })
Logger.info('操作 A')
Logger.error('操作 B 失败')
// 获取 ERROR 级别日志
const errors = Logger.getHistory({ level: LogLevel.ERROR })
// 关键词过滤
const tokenLogs = Logger.getHistory({ keyword: 'token' })
// 导出全部日志为 JSON
const json = Logger.exportHistory()批量输出
import { Logger } from '@ldesign/log'
Logger.batch([
{ content: '步骤 1 执行', type: 'info' },
{ content: '成功完成', type: 'success' },
{ content: '已发生降级', type: 'warning' },
])相关包
依赖关系以本包 package.json 为准:
| 包 | 关系 | 说明 |
|----|------|------|
| @babel/runtime | 直接依赖 | 运行时辅助函数(唯一运行时依赖) |
| @ldesign/cli | 开发依赖 | 构建、文档与发布工具链 |
| @ldesign/doc-core / @ldesign/packer / @ldesign/launcher | 开发依赖 | 文档站与打包工具链 |
| @ldesign/desktop-store | 被依赖 | Store 模块依赖本包记录状态变化 |
| @ldesign/base | 被依赖 | base 包依赖本包提供日志能力 |
本地开发
仅列出本包 package.json 中实际存在的脚本:
pnpm dev # 启动文档开发环境(ldesign doc:dev)
pnpm build # 构建产物(ldesign build)
pnpm site # 构建文档站(ldesign doc:build)
pnpm release # 发布(ldesign release)
pnpm lint # ESLint 检查
pnpm lint:fix # ESLint 自动修复
pnpm doc:dev # 文档开发环境
pnpm doc:build # 文档构建
pnpm doc:preview # 文档预览
pnpm doc:deploy # 文档部署(Vercel)
pnpm test # 运行测试(ldesign test)
pnpm repo:sync # 推送仓库(ldesign git:push)
pnpm repo:sync:auto # 自动推送仓库许可证
ISC © ldesign
