快速开始

安装

npm

npm install lograil

yarn

yarn add lograil

pnpm

pnpm add lograil

bun

bun add lograil

快速上手

本包导出一个开箱即用的 logger，其运行时（Web / Node / Electron，指日志库适配的不同运行环境）会在导入时自动探测。无需任何配置即可直接记录日志：

import { logger } from 'lograil';

logger.info('server started', { port: 3000 });
logger.warn('low disk space', { freeMb: 120 });
logger.error(new Error('boom'));

在 Node.js 与 Electron 主进程中，默认 logger 除输出到控制台外，还会写入一个滚动文件。在 Web 与 Electron 渲染进程中则输出到控制台（在 Electron 环境下，渲染进程会通过 IPC 转发到主进程）。

默认文件传输器开箱即磁盘安全：单文件最多 10 MB，保留约两周的按日文件，所有日志文件总体积最多 200 MB。可通过 fileTransportOptions 调整或放开这些上限（见 Runtime）。

单例约束

导出的 logger 是一个模块级单例。导入时会探测运行时，但默认传输器与进程间消息接收器会在首次使用 logger 时才创建。如果某个进程需要在输出本地日志前先接收 worker 或 Electron 渲染进程的日志，请在启动时调用 logger.initialize()。

• 同一进程内的所有代码共享这一个 logger、同一个异步上下文（AsyncLocalStorage 实例）以及同一组运行时资源。异步上下文是全局的——任何代码调用 runWithContext 都会影响进程内的所有 logger，不只是调用者所在的 logger。如果你创建了多个独立 logger 并希望每个有隔离的异步上下文，目前每个 logger 需要自己的 AsyncLocalStorage store（暂不提供 per-logger API）——建议改用单个 logger 配合 scope 来隔离。
• 如果你需要独立的 logger（例如测试 harness、每个 worker 一个），请使用 createLogger(options)。
• 只有通过 autoFlushOnExit 或 attachExitHandlers() 显式启用时，才会注册生命周期钩子。调用 await logger.destroy() 可解除已启用的钩子并关闭资源。

请参阅各运行时专属指南了解详情：

• Web 运行时 — 浏览器打包安全、createWebRuntime()
• Node 运行时 — 磁盘安全默认值、appName、退出时刷新
• Electron — 双进程模型、preload 桥接、IPC 频道

上下文与元数据

LogEntry 携带两个独立的对象字段 —— context 和 metadata —— 它们服务于不同的目的。详见 上下文与元数据 了解完整说明与示例。简短版本：

• context 是持久化且可继承的。通过 log.setContext() 设置一次后，后续每条条目都会携带它。子 logger 会从父级获得一份独立的拷贝。用于 userId、requestId、tenantId 等请求级数据。
• metadata 仅附加到单条条目。通常由 processor 或 plugin 注入（如 durationMs、host、pid）。用于不应跨请求泄露的单次测量值或环境信息。

结构化日志

第一个参数可以是字符串、Error 或任意值。对象会被保留为结构化数据，而不会被强制转换成 [object Object]：

// Error 会被提取，并渲染其完整的 cause 因果链
logger.error(new Error('db failed'), { query: 'select * from users' });

// 普通对象会作为结构化参数保留
logger.info({ user: { id: 1 }, action: 'login' });

Error 的因果链（包含循环 cause）在可读行与 JSON 输出中均会被安全序列化。

作用域 Logger

可以派生出一个子 logger，它与父 logger 共享相同的传输器、管道与插件，但拥有自己的作用域（以 : 拼接）与隔离的上下文：

const http = logger.scope('http');

http.info('request received'); // scope: "http"

创建自定义实例

当你需要一个完全独立、可自定义的实例时，使用 createLogger：

import { createLogger } from 'lograil';

const log = createLogger({
  level: 'debug',
  transports: [/* ... */],
  context: /* ... */,
});

继续阅读 配置 了解级别、上下文、传输器与管道。