@guiiai/logg

中文文档
1.2.12发布于 2026/09/29MITTypeScriptESM + CJS构建来源已验证近 30 天下载 4.3万

还有一个简单、几乎零依赖性的结构日志遵守记录器实施.

中文使用文档
文档目录28 节
  1. 特征
  2. 预览
  3. 安装
  4. 代理技能
  5. 快速启动
  6. 用法实例
  7. 基本用途
  8. 添加自定义字段
  9. 处理错误
  10. 儿童伐木者
  11. 自动文本记录器
  12. 自定义时间格式
  13. 处理错误
  14. API 参考
  15. Logger 工厂函数
  16. 伐木实例方法
  17. 全局配置
  18. 数字和类型
  19. 配置
  20. 日志级别
  21. 输出格式
  22. 环境支助
  23. 节点.js
  24. 浏览器
  25. 为什么?
  26. 恒星历史
  27. 贡献者
  28. 由 所制

@ guiai/ logg

npm version License: MIT

还有一个简单、几乎零依赖性的结构日志遵守记录器实施.

特征

  • 🛠️ 堆叠解析: 自动抓取并包含用于加强调试的堆栈跟踪信息
  • 📞 呼叫记录: 提供有关调用函数的详细信息, 并使用可点击超链接的文件
  • 🗄️ JSON 格式和 stdout 格式: 以 JSON 格式输出日志, 以便于解析并与日志管理工具集成
  • 🎨 漂亮格式: 在浏览器控制台支持下开发的美丽彩色输出
  • 🔄 滴入替换: 可作为温斯顿等受欢迎的伐木工的直接替代品
  • 📏 最佳做法:实施结构化伐木行业最佳做法
  • 🧩 直观 API: 简单而易于使用的流利的API 快速集成
  • 🌐 通用: 在节点和浏览器环境中工作
  • ⚡ 0 配置: 以合理的默认值在框外工作

预览

image

安装

npm install @guiiai/logg

代理技能

安装 日志技能 给您的 AI 编码代理 :

npx skills add guiiai/logg

快速启动

import { initLogger, useGlobalLogger } from '@guiiai/logg'

// Initialize with defaults (Verbose level, Pretty format)
initLogger()

// Create a logger and start logging
const log = useGlobalLogger('MyApp')
log.log('Hello world!')

用法实例

基本用途

import { createLogg, Format, LogLevel, setGlobalFormat, setGlobalLogLevel } from '@guiiai/logg'

setGlobalLogLevel(LogLevel.Debug)
setGlobalFormat(Format.Pretty) // Otherwise it will output JSON

// Create a logger instance with a specific context
const log = createLogg('http/request').useGlobalConfig()

// Log messages with different levels
log.debug('Debugging info')
log.log('Regular log')
log.warn('Warning message')
log.error('Error occurred')

添加自定义字段

// Add single field
log
  .withField('requestId', req.id)
  .withField('url', req.url)
  .error('Resource not found (404)')

// Add multiple fields at once
log
  .withFields({
    userId: '12345',
    ip: '192.168.1.1',
    userAgent: 'Mozilla/5.0'
  })
  .log('User logged in')

处理错误

try {
  // Some operation
}
catch (err) {
  // Automatically extracts error message, stack trace, and cause
  log.withError(err).error('Operation failed')

  // Or use errorWithError for more control
  log.errorWithError('Failed to process request', err)
}

儿童伐木者

const parentLog = createLogg('app').useGlobalConfig()

// Create child logger with persistent fields
const childLog = parentLog.child({
  module: 'database',
  version: '1.0.0'
})

// All logs from childLog will include the parent fields
childLog.log('Connected to database')

自动文本记录器

import { createLogger } from '@guiiai/logg'

// Automatically includes file path and line number with clickable hyperlinks
const log = createLogger().useGlobalConfig()
log.log('This log knows where it came from!')

自定义时间格式

const log = createLogg('app')
  .useGlobalConfig()
  .withTimeFormatter((date) => {
    return date.toLocaleString('en-US', {
      timeZone: 'America/New_York'
    })
  })

log.log('Log with custom timestamp')

处理错误

// Transform errors before logging
const log = createLogg('app')
  .useGlobalConfig()
  .withErrorProcessor((err) => {
    if (err instanceof CustomError) {
      // Add custom properties or transform the error
      return { ...err, customField: 'value' }
    }
    return err
  })

log.withError(someError).error('Processed error')

API 参考

Logger 工厂函数

createLogg(context: string): Logg

创建一个带有指定上下文的新日志实例.

const log = createLogg('MyModule')

createLogger(context?: string): Logg

从呼叫站点(文件路径和行号)创建自动上下文的日志。 在支持的终端中包括可点击的超链接.

const log = createLogger() // Context is auto-generated
const log2 = createLogger('CustomContext') // Override with custom context

createGlobalLogger(context?: string): Logg

创建自动上下文的日志并应用全局配置.

const log = createGlobalLogger()

initLogger(level?: LogLevel, format?: Format): void

初始化默认的全局日志配置 .

import { Format, initLogger, LogLevel } from '@guiiai/logg'

initLogger(LogLevel.Verbose, Format.Pretty)

别名 :

  • useLogg → createLogg
  • useLogger → createLogger
  • useGlobalLogger → createGlobalLogger

伐木实例方法

配置方法

  • useGlobalConfig(): Logg - 对日志实例应用全局配置
  • child(fields?: Record<string, any>): Logg - 创建一个带有额外持久字段的儿童记录器
  • withContext(context: string): Logg - 动态设置上下文(返回克隆实例)
  • withLogLevel(logLevel: LogLevel): Logg - 动态设置日志级别(返回克隆实例)
  • withLogLevelString(logLevelString: LogLevelString): Logg - 使用字符串设置日志级别(返回克隆实例)
  • withFormat(format: Format): Logg - 动态设定输出格式(返回克隆实例)
  • withFields(fields: Record<string, any>): Logg - 别提了 child()
  • withField(key: string, value: any): Logg - 添加一个自定义字段
  • withError(err: Error | unknown): Logg - 附加自动提取信件、堆栈和原因的错误对象
  • withCallStack(errorLike: { message: string, stack?: string }): Logg - 添加调用堆栈信息
  • withTimeFormatter(fn: (date: Date) => string): Logg - 为物质函数设定自定义时间
  • withErrorProcessor(fn: (err: Error | unknown) => Error | unknown): Logg - 设置自定义错误处理器功能

记录方法

  • debug(message: any, ...optionalParams: any[]): void - 日志调试级消息
  • verbose(message: any, ...optionalParams: any[]): void - 日志动词级消息
  • log(message: any, ...optionalParams: any[]): void - 日志信息级消息
  • warn(message: any, ...optionalParams: any[]): void - 日志警告级消息
  • error(message: any, stack?: string, ...optionalParams: any[]): void - 日志错误级别消息
  • errorWithError(message: any, err: Error | unknown, ...optionalParams: any[]): void - 自动取出错误的日志错误

全局配置

日志级别

import { getGlobalLogLevel, getGlobalLogLevelString, LogLevel, setGlobalLogLevel, setGlobalLogLevelString } from '@guiiai/logg'

setGlobalLogLevel(LogLevel.Debug)
const level = getGlobalLogLevel()

// Or use string-based methods
setGlobalLogLevelString('debug')
const levelString = getGlobalLogLevelString()

格式

import { Format, getGlobalFormat, setGlobalFormat } from '@guiiai/logg'

setGlobalFormat(Format.Pretty)
const format = getGlobalFormat()

时间主题

import { getGlobalTimeFormatter, setGlobalTimeFormatter } from '@guiiai/logg'

setGlobalTimeFormatter(date => date.toISOString())
const formatter = getGlobalTimeFormatter()

数字和类型

LogLevel

enum LogLevel {
  Error = 0,
  Warning = 1,
  Log = 2,
  Verbose = 3,
  Debug = 4
}

LogLevelString

type LogLevelString = 'error' | 'warn' | 'log' | 'verbose' | 'debug'

Format

enum Format {
  JSON = 'json',
  Pretty = 'pretty'
}

配置

日志级别

日志级别控制哪个消息是输出 。 较高级别包括所有较低级别.

职等数值说明
错误0 个只有错误消息
3⁄4 ̄ ̧漯B1个错误和警告
日志2个错误、警告和一般日志
声波3个所有以上加动词信息
调试页:1包括调试信息在内的所有信件

输出格式

JSON 格式

结构化的JSON输出,理想的生产环境和日志汇总工具.

{ "level": "log", "context": "app", "timestamp": "2024-01-01T00:00:00.000Z", "message": "User logged in", "fields": { "userId": "123" } }

漂亮格式

人可读取的有色产出促进发展. 自动检测浏览器环境并相应调整输出.

[2024-01-01 00:00:00] LOG app: User logged in { userId: '123' }

环境支助

节点.js

全力支持所有特征,包括:

  • 终端超链接( VS 代码, iTerm2等)
  • 彩色输出
  • 堆栈跟踪解析

浏览器

优化浏览器支持方式 :

  • 方便主机输出
  • 在浏览器演示工具中适当扩展对象
  • 自动格式检测

为什么?

  • 轻巧: 最小的依赖性( 只有3 个运行时的隔间)
  • 类型安全: 包含完整类型定义的完整类型脚本支持
  • 弹性: 在任何环境中进行没有配置的工作
  • 方便开发者: 美丽的输出和可点击的源链接
  • 生产准备: 用于日志汇总系统的 JSON 输出

恒星历史

Star History Chart

贡献者

contributors

由 所制

版本与发布记录

@guiiai/logg 共发布 27 个版本,首次发布于 2024/08/01;过去 12 个月发布了 7 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.2.12latest2026/09/291 个月前
1.2.112025/12/1611 个月前
1.2.102025/12/1511 个月前
1.2.92025/12/1411 个月前
1.2.82025/12/1411 个月前
1.2.72025/12/1411 个月前

关于 @guiiai/logg 的常见问题

@guiiai/logg 是什么?

还有一个简单、几乎零依赖性的结构日志遵守记录器实施.

如何安装 @guiiai/logg?

在项目目录运行 npm install @guiiai/logg,或使用 pnpm add / yarn add / bun add。

@guiiai/logg 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guiiai/logg 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@guiiai/logg 可以商用吗?

@guiiai/logg 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@guiiai/logg 的下载量有多少?

根据 npm 官方下载统计,@guiiai/logg 在 2026/10/17 – 2026/11/15 这 30 天内被下载 43,094 次,日均约 1,436 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guiiai/logg 还在维护吗?

最新版本 1.2.12 发布于 2026/09/29(1 个月前);至今共发布 27 个版本,其中过去 12 个月发布了 7 个;首次发布于 2024/08/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。