Skip to content

@neosjs/logger ​

基于 Pino 的生产级结构化日志库,一套 API 覆盖三端:Node.js 服务端(主包)、浏览器端(/browser 子路径)、Vue 3(/vue 子路径)。生产环境向 stdout 输出 JSON(零格式化开销,便于 ELK / Loki / Datadog 采集),开发环境可用 pino-pretty 美化控制台;文件日志基于 pino-roll 自动轮转,内置敏感字段脱敏与 AsyncLocalStorage 请求上下文。

安装 ​

sh
pnpm add @neosjs/logger
sh
npm i @neosjs/logger
sh
yarn add @neosjs/logger

TIP

主包 @neosjs/logger 仅用于 Node.js 服务端。浏览器 / Vue 项目请分别使用子路径导出 @neosjs/logger/browser、@neosjs/logger/vue(安装命令相同)。

快速上手 ​

ts
import { createLogger, initLogger, logger } from '@neosjs/logger'

// 建议在应用入口最早调用
initLogger({
  service: 'order-service',
  level: 'info'
})

logger.info('server started')

// 按模块创建 child logger
const userLog = createLogger('user')
userLog.info({ userId: '1001' }, 'profile updated')

导出清单 ​

子路径说明
@neosjs/loggerNode.js 服务端
@neosjs/logger/vueVue 3 插件 + useLogger
@neosjs/logger/browser纯浏览器端(非 Vue)
导出说明
logger全局默认 logger(懒初始化)
initLogger初始化全局 logger(仅调用一次)
createLogger模块级 child logger(同名模块自动缓存复用)
createNeosLogger创建独立 logger 实例(不替换全局)
getLogger获取当前全局 logger 实例
audit审计日志
httpLoggerHTTP 请求中间件
runWithContext / getLoggerContext请求上下文注入与读取
setLevel / getLevel动态调整 / 获取日志级别
flushLogger优雅刷盘

初始化 ​

initLogger(推荐) ​

替换全局默认 logger,适用于大多数单应用场景。logger 采用懒初始化,import 时不会立即创建 worker,首次写日志或调用 initLogger 时生效:

ts
import { initLogger } from '@neosjs/logger'

initLogger({
  service: 'payment-service',
  level: 'debug',
  pretty: process.env.NODE_ENV === 'development',
  logDir: './logs',
  appVersion: '1.2.0'
})

createNeosLogger ​

创建独立 logger 实例,不替换全局默认:

ts
import { createNeosLogger } from '@neosjs/logger'

const workerLog = createNeosLogger({
  name: 'worker',
  service: 'email-worker',
  enableFile: false
})

环境变量 ​

变量说明默认值
NODE_ENV运行环境development
LOG_LEVEL日志级别dev=debug / prod=info
SERVICE_NAME服务名app-service
LOG_DIR日志文件目录./logs
LOG_PRETTY是否美化控制台dev 自动开启
LOG_FILE设为 false 禁用文件写入启用
APP_VERSION应用版本号—
LOG_TIME_FORMAT时间格式 utc / local / epochutc

配置优先级:代码 options > 环境变量 > 内置默认值。

输出策略 ​

环境控制台文件
开发(pretty: true)彩色人类可读格式./logs/app.log(轮转)
生产(pretty: false)结构化 JSON → stdout./logs/app.log(轮转)

生产环境日志示例:

json
{
  "level": 30,
  "time": "2026-07-11T13:19:26.835Z",
  "service": "order-service",
  "env": "production",
  "module": "user",
  "requestId": "a1b2c3d4-...",
  "traceId": "trace-abc",
  "message": "profile updated",
  "userId": "1001"
}

常用 API ​

模块级日志 ​

ts
import { createLogger } from '@neosjs/logger'

const orderLog = createLogger('order')
orderLog.info({ orderId: 'O-001' }, 'order created')
orderLog.warn({ amount: 99.9 }, 'refund pending')
orderLog.error({
  err: new Error('timeout')
}, 'request failed')

动态调整级别 ​

ts
import { getLevel, setLevel } from '@neosjs/logger'

setLevel('debug')
console.log(getLevel()) // 'debug'

请求上下文 ​

通过 AsyncLocalStorage 自动传播,业务代码无需手动传 traceId:

ts
import { logger, runWithContext } from '@neosjs/logger'

await runWithContext(
  { requestId: 'req-001', traceId: 'trace-abc', userId: '1001' },
  async () => {
    logger.info('inside request scope') // 自动携带 requestId / traceId / userId
  }
)

HTTP 中间件 ​

兼容 Express / Connect / Fastify 前置用法:

ts
import { httpLogger } from '@neosjs/logger'
import express from 'express'

const app = express()
app.use(httpLogger)

中间件行为:

  • 自动生成 requestId,或读取 x-request-id 请求头
  • 透传 x-trace-id / x-span-id
  • 记录请求开始与完成(含 statusCode、duration)
  • 4xx → warn,5xx → error

审计日志 ​

与普通业务日志分离,便于合规检索,敏感字段自动脱敏:

ts
import { audit } from '@neosjs/logger'

audit('USER_LOGIN', {
  userId: '1001',
  ip: '10.0.0.1',
  success: true,
  password: '123456' // 自动脱敏为 [保密]
})

优雅关闭 ​

进程退出前刷盘,防止 worker 线程日志丢失:

ts
import { flushLogger } from '@neosjs/logger'

process.on('SIGTERM', async () => {
  await flushLogger()
  process.exit(0)
})

敏感字段脱敏 ​

内置 redact 路径(可通过 initLogger({ redact: [...] }) 扩展):

  • password / pwd / secret / token
  • accessToken / refreshToken / authorization / cookie
  • phone / idCard / apiKey
  • user.password / user.phone / headers.authorization 等

配置项参考 ​

ts
interface NeosLoggerOptions {
  name?: string // Pino logger name
  level?: LogLevel // trace | debug | info | warn | error | fatal
  service?: string // 服务名
  env?: string // 环境标识
  appVersion?: string // 应用版本
  logDir?: string // 日志目录
  pretty?: boolean // 控制台美化
  enableFile?: boolean // 是否写文件
  roll?: {
    size?: string // 默认 '50M'
    frequency?: string // 默认 'daily'
    retention?: number // 默认 7
    compress?: boolean // 默认 true
  }
  timeFormat?: TimeFormat // utc | local | epoch,默认 utc
  redact?: string[] // 额外脱敏路径
  pino?: LoggerOptions // 透传 Pino 高级配置
}

浏览器端(非 Vue) ​

适用于原生 H5、React 等非 Vue 场景,使用 @neosjs/logger/browser 子路径:

ts
import { createBrowserLogger, tracedFetch } from '@neosjs/logger/browser'

const log = createBrowserLogger({
  service: 'h5-app',
  console: import.meta.env.DEV,
  timeFormat: 'local',
  reportUrl: import.meta.env.VITE_LOG_REPORT_URL, // 日志上报地址
  reportLevel: 'warn'
})

log.info('page loaded')
tracedFetch('/api/data') // 自动携带 x-trace-id

Vue 3 浏览器端 ​

使用 @neosjs/logger/vue 子路径(需同时安装 vue):

ts
import { NeosLoggerPlugin, setupLoggerRouter } from '@neosjs/logger/vue'
// main.ts
import { createApp } from 'vue'
import router from './router'

const app = createApp(App)

app.use(NeosLoggerPlugin, {
  service: 'admin-web', // 与服务端 SERVICE_NAME 对齐
  console: import.meta.env.DEV, // 开发环境输出到 console
  reportUrl: import.meta.env.VITE_LOG_REPORT_URL, // 生产上报后端
  reportLevel: 'warn', // warn 及以上上报
  sessionTrace: true // SPA 会话级 traceId
})
setupLoggerRouter(router) // 可选:路由切换时刷新 requestId

app.mount('#app')

组件中使用 useLogger 与 tracedFetch:

vue
<script setup lang="ts">
import { tracedFetch, useLogger } from '@neosjs/logger/vue'

const log = useLogger('user')

async function loadProfile() {
  log.info({ userId: '1001' }, 'loading profile')
  try {
    const res = await tracedFetch('/api/user/profile') // 自动带 x-trace-id
    log.info('profile loaded')
  }
  catch (err) {
    log.error({ err }, 'profile load failed')
  }
}
</script>

前端 tracedFetch 注入 x-trace-id 请求头,服务端 httpLogger 读取后写入日志,即可在日志平台按 traceId 串联前后端链路。

WARNING

生产环境前端不写本地文件,应通过 reportUrl 上报到后端,由服务端 @neosjs/logger 统一落盘与采集;生产环境建议关闭 console 输出,仅上报 warn 及以上级别。

生产环境最佳实践 ​

核心原则:

  1. initLogger 只调用一次,放在应用入口最前面(可放在独立的 bootstrap 文件中,并保证它最先被 import)
  2. 先 initLogger,再 import 业务模块
  3. 不要提前缓存 createLogger() 返回值
  4. 进程退出前调用 flushLogger() 刷盘
  5. 运行时调整级别用 setLevel(),不要重复 initLogger
推荐避免
入口文件第一行 import './bootstrap'在 initLogger 之前调用 createLogger 并缓存
initLogger 只调用 1 次多次 initLogger(会泄漏 worker 线程)
stdout JSON + 日志平台采集生产环境开启 pretty: true
setLevel('debug') 临时排查为改级别而重新 initLogger
错误日志传 { err } 保留堆栈logger.error(err.message) 丢失 stack
SIGTERM 时 await flushLogger()直接 process.exit() 导致日志丢失
敏感操作用 audit()审计与业务日志混写、无 event 分类