# @geekmidas/logger 中文文档

规范地址：https://npmcn.com/package/%40geekmidas/logger/

版本：9\.6\.1
npm 元数据更新时间：2026-11-16T09:28:55.663Z
中文译文更新时间：2026-11-16T09:31:07.918Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：149 kB，57 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：pino ~10\.0\.0，pino-pretty ~13\.1\.2
- 首次发布：2025-10-19T18:21:36.015Z
- 最新版本发布：2026-11-16T09:28:55.292Z
- 近 30 天下载量：15627（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：203（近 12 个月 202 个）

## 中文简介

一个简单而灵活的节点和浏览器日志库

## 安装

```sh
npm install @geekmidas/logger
```

也可以使用：`pnpm add @geekmidas/logger`、`yarn add @geekmidas/logger`、`bun add @geekmidas/logger`

## README

# @ geekmidas/ logger (英语)

一个简单而灵活的结构化的日志库,用于Node.js和浏览器,有孩子日志支持和上下文继承功能.

## 特征

-   **标准接口**: 具有多个日志级别(调试、信息、警告、错误、致命、跟踪)的常见日志界面
-   **结构化日志**: 支持结构化的(对象+消息)和简单的(仅信息)记录
-   **儿童伐木者**: 创建带有继承上下文的儿童日志
-   **多个执行**: 简单使用的控制台Logger,生产使用的 PinoLogger
-   **敏感数据编辑**: 内置密码、 令牌、 API 密钥等编辑器
-   **类型脚本**: 完整类型脚本支持和类型安全记录

## 安装

```bash
pnpm add @geekmidas/logger
```

## 快速启动

```typescript
import { ConsoleLogger } from '@geekmidas/logger';

// Create logger with initial context
const logger = new ConsoleLogger({ app: 'myApp', version: '1.0.0' });

// Structured logging
logger.info({ userId: 123, action: 'login' }, 'User logged in');
// Output: { app: 'myApp', version: '1.0.0', userId: 123, action: 'login', ts: 1234567890 } User logged in

// Simple logging
logger.info('Application started');
// Output: { app: 'myApp', version: '1.0.0', ts: 1234567890 } Application started

// Error logging
logger.error({ error, operation: 'fetchUser' }, 'Failed to fetch user');
```

## 皮诺·洛格

对于生产用途,该包提供了一种基于皮诺的对接机,具有高性能和内置的编辑支持.

```typescript
import { createLogger } from '@geekmidas/logger/pino';

const logger = createLogger({
  level: 'info',
  pretty: true,  // Pretty printing in development
  redact: true,  // Enable sensitive data redaction
});

logger.info({ userId: 123 }, 'User logged in');
```

## 敏感数据编辑

皮诺登录器包括内置编辑器,以自动遮盖密码,令牌等敏感数据以及API密钥.

### 用默认启用

```typescript
import { createLogger } from '@geekmidas/logger/pino';

const logger = createLogger({ redact: true });

// Sensitive data is automatically masked
logger.info({ password: 'secret123', user: 'john' }, 'Login attempt');
// Output: { password: '[Redacted]', user: 'john' } Login attempt

logger.info({ headers: { authorization: 'Bearer xyz' } }, 'Request');
// Output: { headers: { authorization: '[Redacted]' } } Request
```

### 默认已编辑字段

何时 `redact: true`,以下字段自动被遮盖:

-   **认证**数字 : `password`, (中文(简体) ), `pass`, (中文(简体) ), `passwd`, (中文(简体) ), `secret`, (中文(简体) ), `token`, (中文(简体) ), `accessToken`, (中文(简体) ), `refreshToken`, (中文(简体) ), `apiKey`, (中文(简体) ), `api_key`, (中文(简体) ), `authorization`, (中文(简体) ), `credentials`
-   **页眉**数字 : `headers.authorization`, (中文(简体) ), `headers.cookie`, (中文(简体) ), `headers["x-api-key"]`
-   **个人数据**数字 : `ssn`, (中文(简体) ), `creditCard`, (中文(简体) ), `cardNumber`, (中文(简体) ), `cvv`, (中文(简体) ), `pin`
-   **秘诀**数字 : `connectionString`, (中文(简体) ), `databaseUrl`
-   **通关卡**数字 : `*.password`, (中文(简体) ), `*.secret`, (中文(简体) ), `*.token` (渔获物嵌入地)

### 添加自定义路径( 带有默认的路径)

```typescript
const logger = createLogger({
  redact: ['user.ssn', 'payment.cardNumber'],
});

// Both custom paths AND defaults are redacted
logger.info({ password: 'secret', user: { ssn: '123-45-6789' } }, 'Data');
// Output: { password: '[Redacted]', user: { ssn: '[Redacted]' } } Data
```

### 覆盖默认

使用 `resolution: 'override'` 以禁用默认路径, 只使用您的自定义路径 :

```typescript
const logger = createLogger({
  redact: {
    paths: ['myCustomSecret'],
    resolution: 'override',
  },
});

// Only 'myCustomSecret' is redacted, defaults are ignored
logger.info({ password: 'visible', myCustomSecret: 'hidden' }, 'Data');
// Output: { password: 'visible', myCustomSecret: '[Redacted]' } Data
```

### 自定义检查并删除

```typescript
// Custom censor string
const logger = createLogger({
  redact: {
    paths: ['secret'],
    censor: '***HIDDEN***',
  },
});

// Remove fields entirely instead of masking
const logger2 = createLogger({
  redact: {
    paths: ['temporaryData'],
    remove: true,
  },
});
```

### 路径语法

编辑路径支持点标记和通配符 :

```typescript
redact: [
  'password',           // Top-level field
  'user.password',      // Nested field
  'users[*].password',  // Array wildcard
  '*.secret',           // Any object's 'secret' field
  'headers["x-api-key"]', // Bracket notation for special chars
]
```

## API 参考

### 锁定接口

```typescript
interface Logger {
  debug: LogFn;
  info: LogFn;
  warn: LogFn;
  error: LogFn;
  fatal: LogFn;
  trace: LogFn;
  child: (obj: object) => Logger;
}
```

### 日志级别

-   **追踪** - 最详细的资料
-   **调试** - 调试的口头信息
-   **资讯** - 一般信息信息
-   **警告( e)** - 可能有害的情况
-   **错误** - 仍然允许应用程序继续下去的错误事件
-   **致命的** - 可能导致应用程序中止的严重错误

### 控制台

```typescript
class ConsoleLogger implements Logger {
  constructor(data?: object)

  debug: LogFn
  info: LogFn
  warn: LogFn
  error: LogFn
  fatal: LogFn
  trace: LogFn
  child(obj: object): Logger
}
```

## 用法实例

### 基本日志

```typescript
import { ConsoleLogger } from '@geekmidas/logger';

const logger = new ConsoleLogger({ service: 'api', environment: 'production' });

// Different log levels
logger.trace('Entering function');
logger.debug({ query: 'SELECT * FROM users' }, 'Executing query');
logger.info({ requestId: 'abc123' }, 'Request received');
logger.warn({ memoryUsage: '90%' }, 'High memory usage detected');
logger.error({ error: new Error('Connection failed') }, 'Database error');
logger.fatal({ exitCode: 1 }, 'Critical system failure');
```

### 结构化日志

```typescript
const logger = new ConsoleLogger({ app: 'myApp' });

// Log with context object
logger.info(
  {
    userId: 123,
    action: 'purchase',
    productId: 'prod_456',
    amount: 29.99
  },
  'Purchase completed'
);

// Multiple additional arguments
logger.info(
  { traceId: 'trace_123' },
  'Request processed in %dms',
  150
);
```

### 儿童伐木者

儿童记录员从父母那里继承所有上下文,并添加自己的:

```typescript
const parentLogger = new ConsoleLogger({
  app: 'myApp',
  environment: 'production'
});

// Create child logger for authentication module
const authLogger = parentLogger.child({ module: 'auth' });
authLogger.info({ userId: 123 }, 'User authenticated');
// Output: { app: 'myApp', environment: 'production', module: 'auth', userId: 123, ts: ... }

// Create child logger for database module
const dbLogger = parentLogger.child({ module: 'database' });
dbLogger.debug({ query: 'SELECT ...' }, 'Query executed');
// Output: { app: 'myApp', environment: 'production', module: 'database', query: 'SELECT ...', ts: ... }

// Child loggers can be nested
const userDbLogger = dbLogger.child({ table: 'users' });
userDbLogger.info({ rowsAffected: 1 }, 'Record inserted');
// Output: { app: 'myApp', environment: 'production', module: 'database', table: 'users', rowsAffected: 1, ts: ... }
```

### 请求上下文模式

```typescript
import type { Logger } from '@geekmidas/logger';

function handleRequest(logger: Logger, requestId: string) {
  // Create request-scoped logger
  const requestLogger = logger.child({ requestId });

  requestLogger.info('Processing request');

  try {
    processPayment(requestLogger);
    requestLogger.info('Request completed');
  } catch (error) {
    requestLogger.error({ error }, 'Request failed');
  }
}

function processPayment(logger: Logger) {
  const paymentLogger = logger.child({ operation: 'payment' });
  paymentLogger.debug({ amount: 100 }, 'Processing payment');
  // All context is preserved: { requestId, operation, amount, ts }
}
```

### 与服务一体化

```typescript
class UserService {
  private logger: Logger;

  constructor(logger: Logger) {
    this.logger = logger.child({ service: 'UserService' });
  }

  async createUser(data: UserData) {
    this.logger.info({ email: data.email }, 'Creating user');

    try {
      const user = await this.db.insert(data);
      this.logger.info({ userId: user.id }, 'User created successfully');
      return user;
    } catch (error) {
      this.logger.error({ error, email: data.email }, 'Failed to create user');
      throw error;
    }
  }

  async deleteUser(userId: string) {
    const logger = this.logger.child({ userId, operation: 'delete' });

    logger.info('Deleting user');
    await this.db.delete(userId);
    logger.info('User deleted');
  }
}
```

## 自定义 Logger 执行

您可以执行 `Logger` 自定义日志后端的接口 :

```typescript
import type { Logger, LogFn } from '@geekmidas/logger';

class CustomLogger implements Logger {
  constructor(private context: object = {}) {}

  private createLogFn(level: string): LogFn {
    return (obj: any, msg?: string, ...args: any[]) => {
      // Your custom logging implementation
      const logEntry = {
        level,
        ...this.context,
        ...obj,
        timestamp: new Date().toISOString(),
        message: msg
      };

      // Send to your logging service
      yourLoggingService.send(logEntry);
    };
  }

  debug: LogFn = this.createLogFn('debug');
  info: LogFn = this.createLogFn('info');
  warn: LogFn = this.createLogFn('warn');
  error: LogFn = this.createLogFn('error');
  fatal: LogFn = this.createLogFn('fatal');
  trace: LogFn = this.createLogFn('trace');

  child(obj: object): Logger {
    return new CustomLogger({ ...this.context, ...obj });
  }
}
```

## 类型脚本支持

库以 TypeScript 书写,并提供完整类型定义:

```typescript
import type { Logger, LogFn } from '@geekmidas/logger';

// Use Logger type for dependency injection
function createService(logger: Logger) {
  return {
    doWork() {
      logger.info('Working...');
    }
  };
}

// LogFn type for custom implementations
const customLog: LogFn = (obj, msg) => {
  console.log(obj, msg);
};
```

## 最佳做法

1.  **创建 Base Logger 早期**: 在应用程序启动时以静态上下文初始化您的基准日志
    
    ```typescript
    const baseLogger = new ConsoleLogger({
      app: 'myApp',
      version: process.env.APP_VERSION,
      environment: process.env.NODE_ENV
    });
    ```
    
2.  **使用儿童搜索器**: 创建不同模块/文字的儿童记录器,而不是反复传递上下文
    
    ```typescript
    const authLogger = baseLogger.child({ module: 'auth' });
    const dbLogger = baseLogger.child({ module: 'db' });
    ```
    
3.  **结构覆盖字符串**: 优先使用上下文对象在字符串连接上进行结构记录
    
    ```typescript
    // Good
    logger.info({ userId, action: 'login', ip }, 'User logged in');
    
    // Avoid
    logger.info(`User ${userId} logged in from ${ip}`);
    ```
    
4.  **包含上下文**: 添加相关上下文, 使日志可以搜索和调试
    
    ```typescript
    logger.error({
      error: err,
      userId,
      requestId,
      operation: 'fetchUser'
    }, 'Operation failed');
    ```
    
5.  **依赖性注射**:通过记录器作为依赖性而不是全球进口
    
    ```typescript
    class MyService {
      constructor(private logger: Logger) {}
    }
    ```
    

## 许可证

麻省理工学院

## 常见问题

### @geekmidas/logger 是什么？

一个简单而灵活的节点和浏览器日志库

### 如何安装 @geekmidas/logger？

在项目目录运行 npm install @geekmidas/logger，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：pino（~10\.0\.0）、pino-pretty（~13\.1\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @geekmidas/logger 支持 TypeScript 吗？

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

### @geekmidas/logger 支持 ESM 还是 CommonJS？

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

### @geekmidas/logger 可以商用吗？

@geekmidas/logger 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @geekmidas/logger 的下载量有多少？

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

### @geekmidas/logger 还在维护吗？

最新版本 9\.6\.1 发布于 2026/11/16（今天）；至今共发布 203 个版本，其中过去 12 个月发布了 202 个；首次发布于 2025/10/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

