npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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