Raypx

@raypx/logger 基于 Pino 提供结构化日志功能，支持日志上下文、多传输层和错误序列化。

基本用法

import { logger } from "@raypx/logger"

logger.info("Server started", { port: 3001 })
logger.error("Database connection failed", { error: err.message })

logger 是一个惰性代理，首次访问时自动创建默认实例。

createLogger()

创建一个自定义 Logger 实例。

import { createLogger } from "@raypx/logger"

const log = createLogger({
  level: "debug",
  service: "my-service",
  version: "1.0.0",
  context: { feature: "auth" },
})

选项

参数	类型	默认值	说明
`level`	`LogLevel`	`"info"`	最低日志级别
`service`	`string`	-	服务名称，写入每条日志
`version`	`string`	-	版本号，写入每条日志
`transports`	`TransportConfig[]`	-	自定义传输层
`redact`	`string[]`	-	需要脱敏的字段路径
`context`	`LogContext`	-	默认上下文对象

日志级别

type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal"

getLogger() 与 setLogger()

获取或替换全局默认 Logger。

import { getLogger, setLogger } from "@raypx/logger"

// 获取默认 Logger
const log = getLogger()

// 替换默认 Logger（用于测试或自定义配置）
setLogger(createLogger({ level: "debug" }))

日志上下文

通过 context 参数附加结构化数据。推荐始终包含 feature 字段以标识功能模块。

logger.info("User signed in", {
  feature: "auth",
  userId: user.id,
  provider: "google",
})

withContext()

创建一个带有固定上下文的新 Logger 实例，后续调用自动附加该上下文。

const authLog = logger.withContext({ feature: "auth" })
authLog.info("Password reset requested") // 自动包含 feature: "auth"

child()

创建子 Logger，支持覆盖配置。

const childLog = logger.child({ context: { feature: "billing" }, level: "debug" })

传输层

createConsoleTransport()

创建控制台传输层，开发环境下自动使用 pino-pretty 美化输出。

import { createConsoleTransport } from "@raypx/logger"

const log = createLogger({
  transports: [createConsoleTransport("debug")],
})

createFileTransport()

创建文件传输层，将日志写入指定文件。

import { createFileTransport } from "@raypx/logger"

const log = createLogger({
  transports: [
    createConsoleTransport("info"),
    createFileTransport("/var/log/app.log", "warn"),
  ],
})

serializeError()

将任意错误对象序列化为可 JSON 序列化的结构。

import { serializeError } from "@raypx/logger"

const serialized = serializeError(err)
// { name: "Error", message: "...", stack: "...", cause: {...} }

支持嵌套 cause 链的递归序列化，对非 Error 对象也会尝试安全转换。

在其他包中的使用

@raypx/rpc：RPC 拦截器中使用 logger.info() 记录请求
@raypx/auth：认证回调（密码重置等）中使用 logger.info() 记录事件

@raypx/logger

On this page