@neosjs/logger
基于 Pino 的生产级结构化日志库,一套 API 覆盖三端:Node.js 服务端(主包)、浏览器端(/browser 子路径)、Vue 3(/vue 子路径)。生产环境向 stdout 输出 JSON(零格式化开销,便于 ELK / Loki / Datadog 采集),开发环境可用 pino-pretty 美化控制台;文件日志基于 pino-roll 自动轮转,内置敏感字段脱敏与 AsyncLocalStorage 请求上下文。
安装
pnpm add @neosjs/loggernpm i @neosjs/loggeryarn add @neosjs/loggerTIP
主包 @neosjs/logger 仅用于 Node.js 服务端。浏览器 / Vue 项目请分别使用子路径导出 @neosjs/logger/browser、@neosjs/logger/vue(安装命令相同)。
快速上手
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/logger | Node.js 服务端 |
@neosjs/logger/vue | Vue 3 插件 + useLogger |
@neosjs/logger/browser | 纯浏览器端(非 Vue) |
| 导出 | 说明 |
|---|---|
logger | 全局默认 logger(懒初始化) |
initLogger | 初始化全局 logger(仅调用一次) |
createLogger | 模块级 child logger(同名模块自动缓存复用) |
createNeosLogger | 创建独立 logger 实例(不替换全局) |
getLogger | 获取当前全局 logger 实例 |
audit | 审计日志 |
httpLogger | HTTP 请求中间件 |
runWithContext / getLoggerContext | 请求上下文注入与读取 |
setLevel / getLevel | 动态调整 / 获取日志级别 |
flushLogger | 优雅刷盘 |
初始化
initLogger(推荐)
替换全局默认 logger,适用于大多数单应用场景。logger 采用懒初始化,import 时不会立即创建 worker,首次写日志或调用 initLogger 时生效:
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 实例,不替换全局默认:
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 / epoch | utc |
配置优先级:代码 options > 环境变量 > 内置默认值。
输出策略
| 环境 | 控制台 | 文件 |
|---|---|---|
开发(pretty: true) | 彩色人类可读格式 | ./logs/app.log(轮转) |
生产(pretty: false) | 结构化 JSON → stdout | ./logs/app.log(轮转) |
生产环境日志示例:
{
"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
模块级日志
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')动态调整级别
import { getLevel, setLevel } from '@neosjs/logger'
setLevel('debug')
console.log(getLevel()) // 'debug'请求上下文
通过 AsyncLocalStorage 自动传播,业务代码无需手动传 traceId:
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 前置用法:
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
审计日志
与普通业务日志分离,便于合规检索,敏感字段自动脱敏:
import { audit } from '@neosjs/logger'
audit('USER_LOGIN', {
userId: '1001',
ip: '10.0.0.1',
success: true,
password: '123456' // 自动脱敏为 [保密]
})优雅关闭
进程退出前刷盘,防止 worker 线程日志丢失:
import { flushLogger } from '@neosjs/logger'
process.on('SIGTERM', async () => {
await flushLogger()
process.exit(0)
})敏感字段脱敏
内置 redact 路径(可通过 initLogger({ redact: [...] }) 扩展):
password/pwd/secret/tokenaccessToken/refreshToken/authorization/cookiephone/idCard/apiKeyuser.password/user.phone/headers.authorization等
配置项参考
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 子路径:
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-idVue 3 浏览器端
使用 @neosjs/logger/vue 子路径(需同时安装 vue):
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:
<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 及以上级别。
生产环境最佳实践
核心原则:
initLogger只调用一次,放在应用入口最前面(可放在独立的 bootstrap 文件中,并保证它最先被 import)- 先
initLogger,再 import 业务模块 - 不要提前缓存
createLogger()返回值 - 进程退出前调用
flushLogger()刷盘 - 运行时调整级别用
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 分类 |