# @guiiai/logg 中文文档

规范地址：https://npmcn.com/package/%40guiiai/logg/

版本：1\.2\.12
npm 元数据更新时间：2026-09-29T13:55:41.477Z
中文译文更新时间：2026-11-17T03:09:12.086Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40guiiai/logg
原文对照：https://npmcn.com/package/%40guiiai/logg/?lang=original
项目主页：https://github.com/guiiai/logg#readme
源码仓库：https://github.com/guiiai/logg

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：80.3 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2024-07-31T17:54:43.096Z
- 最新版本发布：2026-09-29T13:55:41.156Z
- 近 30 天下载量：43094（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 7 个）

## 中文简介

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

## 安装

```sh
npm install @guiiai/logg
```

也可以使用：`pnpm add @guiiai/logg`、`yarn add @guiiai/logg`、`bun add @guiiai/logg`

## README

# @ guiai/ logg

[![npm version](https://badge.fury.io/js/@guiiai%2Flogg.svg)](https://www.npmjs.com/package/@guiiai/logg) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## 特征

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

## 预览

![image](https://github.com/user-attachments/assets/1cd7efb2-2257-409b-8011-7de69320f2be)

## 安装

```bash
npm install @guiiai/logg
```

### 代理技能

安装 [日志技能](https://skills.sh/) 给您的 AI 编码代理 :

```bash
npx skills add guiiai/logg
```

## 快速启动

```typescript
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!')
```

## 用法实例

### 基本用途

```typescript
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')
```

### 添加自定义字段

```typescript
// 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')
```

### 处理错误

```typescript
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)
}
```

### 儿童伐木者

```typescript
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')
```

### 自动文本记录器

```typescript
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!')
```

### 自定义时间格式

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

log.log('Log with custom timestamp')
```

### 处理错误

```typescript
// 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`

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

```typescript
const log = createLogg('MyModule')
```

#### `createLogger(context?: string): Logg`

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

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

#### `createGlobalLogger(context?: string): Logg`

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

```typescript
const log = createGlobalLogger()
```

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

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

```typescript
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`** - 自动取出错误的日志错误

### 全局配置

#### 日志级别

```typescript
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()
```

#### 格式

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

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

#### 时间主题

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

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

### 数字和类型

#### `LogLevel`

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

#### `LogLevelString`

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

#### `Format`

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

## 配置

### 日志级别

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

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

### 输出格式

#### JSON 格式

结构化的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](https://api.star-history.com/svg?repos=guiiai/logg&type=Date)](https://star-history.com/#guiiai/logg&Date)

## 贡献者

[![contributors](https://contrib.rocks/image?repo=guiiai/logg)](https://github.com/guiiai/logg/graphs/contributors)

### 由 所制

## 常见问题

### @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 和提交记录判断。

