@geekmidas/logger

中文文档
9.6.1发布于 2026/11/16TypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 1.6万

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

中文使用文档
文档目录25 节
  1. 特征
  2. 安装
  3. 快速启动
  4. 皮诺·洛格
  5. 敏感数据编辑
  6. 用默认启用
  7. 默认已编辑字段
  8. 添加自定义路径( 带有默认的路径)
  9. 覆盖默认
  10. 自定义检查并删除
  11. 路径语法
  12. API 参考
  13. 锁定接口
  14. 日志级别
  15. 控制台
  16. 用法实例
  17. 基本日志
  18. 结构化日志
  19. 儿童伐木者
  20. 请求上下文模式
  21. 与服务一体化
  22. 自定义 Logger 执行
  23. 类型脚本支持
  24. 最佳做法
  25. 许可证

@ geekmidas/ logger (英语)

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

特征

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

安装

pnpm add @geekmidas/logger

快速启动

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');

皮诺·洛格

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

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密钥.

用默认启用

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 (渔获物嵌入地)

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

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' 以禁用默认路径, 只使用您的自定义路径 :

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

自定义检查并删除

// 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,
  },
});

路径语法

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

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 参考

锁定接口

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

日志级别

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

控制台

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

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

用法实例

基本日志

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');

结构化日志

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
);

儿童伐木者

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

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: ... }

请求上下文模式

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 }
}

与服务一体化

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 自定义日志后端的接口 :

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 书写,并提供完整类型定义:

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 早期: 在应用程序启动时以静态上下文初始化您的基准日志

    const baseLogger = new ConsoleLogger({
      app: 'myApp',
      version: process.env.APP_VERSION,
      environment: process.env.NODE_ENV
    });
    
  2. 使用儿童搜索器: 创建不同模块/文字的儿童记录器,而不是反复传递上下文

    const authLogger = baseLogger.child({ module: 'auth' });
    const dbLogger = baseLogger.child({ module: 'db' });
    
  3. 结构覆盖字符串: 优先使用上下文对象在字符串连接上进行结构记录

    // Good
    logger.info({ userId, action: 'login', ip }, 'User logged in');
    
    // Avoid
    logger.info(`User ${userId} logged in from ${ip}`);
    
  4. 包含上下文: 添加相关上下文, 使日志可以搜索和调试

    logger.error({
      error: err,
      userId,
      requestId,
      operation: 'fetchUser'
    }, 'Operation failed');
    
  5. 依赖性注射:通过记录器作为依赖性而不是全球进口

    class MyService {
      constructor(private logger: Logger) {}
    }
    

许可证

麻省理工学院

版本与发布记录

@geekmidas/logger 共发布 203 个版本,首次发布于 2025/10/20;过去 12 个月发布了 202 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.6.1latest2026/11/16今天
10.0.0-alpha.185alpha2026/11/16今天
10.0.0-alpha.1842026/11/16今天
10.0.0-alpha.1832026/11/16今天
10.0.0-alpha.1822026/11/132 天前
10.0.0-alpha.1812026/11/133 天前

关于 @geekmidas/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 和提交记录判断。