Getting Started

@gvray/logger 是一个轻量、可扩展的日志库，支持 Node.js 和浏览器，TypeScript 优先。

实时示例

下方所有示例都是可运行的——页面内即可查看输出，点击 Re-run 重新执行。修改 src/ 源码后，文档会自动热更新，立刻看到效果。

安装

npm install @gvray/logger

快速开始

import { Logger, LogLevel } from '@gvray/logger';

const logger = new Logger({
  level: LogLevel.DEBUG,
  timestamp: 'time',
});

logger.info('Server started on port', 3000);
logger.debug('Config:', { env: 'production', debug: false });
logger.error('Connection failed:', new Error('timeout'));

日志级别

支持 6 种日志级别，从最详细的 TRACE 到最严重的 FATAL。

import { Logger, LogLevel } from '@gvray/logger';

const logger = new Logger({ level: LogLevel.TRACE, timestamp: 'time' });

logger.trace('TRACE - 最详细的追踪信息');
logger.debug('DEBUG - 调试信息');
logger.info('INFO - 一般信息');
logger.warning('WARNING - 警告信息');
logger.error('ERROR - 错误信息');
logger.fatal('FATAL - 致命错误');

Console

(no output)

多参数输出

像原生 console 一样传递多个参数，对象可在控制台中交互展开。

import { Logger, LogLevel } from '@gvray/logger';

const logger = new Logger({ level: LogLevel.DEBUG, timestamp: 'time' });

const user = {
  id: 1,
  name: 'John Doe',
  role: 'admin',
  settings: { theme: 'dark', notifications: { email: true, push: false } },
};

logger.info('User logged in:', user);
logger.info('Multiple args:', 'string', 123, true, { key: 'value' }, [1, 2, 3]);
logger.debug('Complex object:', user, { timestamp: Date.now() });

Console

(no output)

时间戳格式

支持 ISO、本地、时间、Unix 毫秒，或自定义格式化函数。

import { Logger } from '@gvray/logger';

new Logger({ timestamp: 'iso' }).info('ISO 格式时间戳');
new Logger({ timestamp: 'locale' }).info('本地格式时间戳');
new Logger({ timestamp: 'time' }).info('仅时间');
new Logger({ timestamp: 'unix' }).info('Unix 毫秒时间戳');

// 自定义格式
new Logger({
  timestamp: (date) => `[${date.getHours()}:${date.getMinutes()}:${date.getSeconds()}]`,
}).info('自定义格式时间戳');

Console

(no output)

日志级别过滤

设置最低日志级别，过滤不需要的日志。

import { Logger, LogLevel } from '@gvray/logger';

// 只显示 WARNING 及以上级别
const logger = new Logger({ level: LogLevel.WARNING, timestamp: 'time' });

logger.trace('不会显示');
logger.debug('不会显示');
logger.info('不会显示');
logger.warning('会显示');
logger.error('会显示');
logger.fatal('会显示');

Console

(no output)

命名空间

为不同模块创建独立的日志实例。

import { Logger, LogLevel } from '@gvray/logger';

const apiLogger = new Logger({ namespace: 'api', level: LogLevel.DEBUG, timestamp: 'time' });
const dbLogger = new Logger({ namespace: 'database', level: LogLevel.DEBUG, timestamp: 'time' });
const cacheLogger = new Logger({ namespace: 'cache', level: LogLevel.DEBUG, timestamp: 'time' });

apiLogger.info('Request received: GET /users');
dbLogger.info('Query executed: SELECT * FROM users');
cacheLogger.debug('Cache hit for key: user:123');
apiLogger.info('Response sent: 200 OK');

Console

(no output)

子 Logger

从父 Logger 继承配置，创建层级化日志。

import { Logger, LogLevel } from '@gvray/logger';

const app = new Logger({ namespace: 'app', level: LogLevel.DEBUG, timestamp: 'time' });
const http = app.child('http');
const auth = http.child('auth');
const jwt = auth.child('jwt');

app.info('Application started');
http.info('HTTP server listening on port 3000');
auth.debug('Processing authentication request');
jwt.debug('JWT token generated');
jwt.info('Token validated successfully');

Console

(no output)

中间件

使用中间件扩展日志功能——前缀、脱敏等。

import { Logger, LogLevel, prefixMiddleware, redactMiddleware } from '@gvray/logger';

// Prefix 中间件：给每条日志加前缀
const logger = new Logger({ level: LogLevel.DEBUG, timestamp: 'time' });
logger.use(prefixMiddleware('[API]'));
logger.info('Request received');
logger.debug('Processing data');
logger.info('Response sent');

// Redact 中间件：自动脱敏敏感信息
const secure = new Logger({ level: LogLevel.DEBUG });
secure.use(
  redactMiddleware([
    'password123',
    'secret-key',
    /\d{4}-\d{4}-\d{4}-\d{4}/, // 信用卡号
    /\w+@\w+\.\w+/, // 邮箱
  ]),
);
secure.info('Login attempt: password=password123');
secure.info('API Key: secret-key');
secure.info('Card: 1234-5678-9012-3456');
secure.info('Email: user@example.com');

Console

(no output)

链式调用

流畅的 API 设计，支持链式配置。

import { Logger, LogLevel } from '@gvray/logger';

const logger = new Logger()
  .setLevel(LogLevel.DEBUG)
  .setTimestamp('time')
  .enableColors();

logger.info('Logger configured via chaining!');
logger.debug('Deep object:', { a: { b: { c: { d: 1 } } } });

// 动态修改配置
logger.setLevel(LogLevel.WARNING);
logger.info('This will NOT show');
logger.warning('Only warnings and above now');

Console

(no output)