# @happyvertical/logger 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/logger/

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:02:03.181Z
中文译文更新时间：2026-11-17T09:28:17.012Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/logger
原文对照：https://npmcn.com/package/%40happyvertical/logger/?lang=original
项目主页：https://github.com/happyvertical/sdk/tree/main/packages/logger#readme
源码仓库：https://github.com/happyvertical/sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：51.6 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@sentry/node \>=10\.49\.0
- 首次发布：2026-06-23T08:14:16.639Z
- 最新版本发布：2026-11-17T00:02:02.924Z
- 近 30 天下载量：41777（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：131（近 12 个月 131 个）

## 中文简介

HARE SDK 带有信号适配器的结构记录

## 安装

```sh
npm install @happyvertical/logger
```

也可以使用：`pnpm add @happyvertical/logger`、`yarn add @happyvertical/logger`、`bun add @happyvertical/logger`

## README

# @ 喜悦的垂直/ 跳动

HARE SDK的结构记录有信号适配器集成和可选的哨兵出错跟踪. 规定 a `Logger` 与四个重度级的接口,一个带有分级过滤的控制台执行,以及将SMRT框架信号转换成日志条目或哨兵面包屑/例外的适配器.

## 安装

```bash
pnpm add @happyvertical/logger

# Optional: for Sentry integration
pnpm add @sentry/node
```

取决于 `@happyvertical/utils`可选同伴依赖 `@sentry/node` (关于 `/sentry` (原始内容存档于2018-03-29). subpath.

## 基本用途

```typescript
import { createLogger } from '@happyvertical/logger';

// Console logger with default 'info' level
const logger = createLogger(true);

logger.info('Application started');
logger.debug('Verbose detail'); // Not output (below 'info')
logger.warn('High memory usage', { memoryMB: 512 });
logger.error('Connection failed', { host: 'localhost', port: 5432 });

// Configure a specific level
const debugLogger = createLogger({ level: 'debug' });

// No-op logger — all calls discarded, zero overhead
const silent = createLogger(false);
```

### 环境变量

设定 `HAVE_LOGGER_LEVEL` 改为 `debug`, (中文(简体) ), `info`, (中文(简体) ), `warn`,或 `error`时应用 `createLogger(true)` 或者说 `createLogger({})`明确配置优先:

```typescript
process.env.HAVE_LOGGER_LEVEL = 'debug';
const logger = createLogger(true); // uses 'debug' from env

const explicit = createLogger({ level: 'warn' }); // uses 'warn', ignores env
```

## 日志级别

`debug < info < warn < error` ——已配置阈值以下的信件被丢弃.

```typescript
const logger = createLogger({ level: 'warn' });
logger.debug('ignored');  // not output
logger.info('ignored');   // not output
logger.warn('output');    // output
logger.error('output');   // output
```

输出格式 : `[LEVEL] message {"key":"value"}`

## 信号适配器

`LoggerAdapter` 将 SMRT 框架信号转换为结构化的日志条目 :

```typescript
import { createLogger, LoggerAdapter } from '@happyvertical/logger';

const logger = createLogger({ level: 'info' });
const adapter = new LoggerAdapter(logger);
// Register adapter with a signal bus to log operations automatically
```

信号类型映射 : `start` 调试, `step` 调试, `end` - 资料, `error` ——错误.

## 哨兵适应器

这个 `/sentry` 子路径信号到哨兵/格利奇Tip. 要求数 `@sentry/node` 作为同伴的依赖.

```typescript
import { createSentryAdapter } from '@happyvertical/logger/sentry';

const adapter = createSentryAdapter({ category: 'myapp' });
// Register adapter with a signal bus

// Error signals → Sentry.captureException with scope tags
// Non-error signals → Sentry.addBreadcrumb for debugging trail
```

## API 概览

### 工厂

| 函数 | 说明 |
| --- | --- |
| `createLogger(config)` | 回返a `Logger` —— 说 `ConsoleLogger` 当启用时, 无操作 `false` |
| `createSentryAdapter(config?)` | 回返a `SentryAdapter` (从) `/sentry` 子路径) |

### 类

| 类 | 说明 |
| --- | --- |
| `ConsoleLogger` | 带有级别过滤的 Logger 执行, 写到 `console.*` |
| `LoggerAdapter` | 将信号转换为结构化日志消息的信号适配器 |
| `SentryAdapter` | 信号适配器,用于向哨兵传递错误并添加面包屑 |

### 类型

| 类型 | 说明 |
| --- | --- |
| `Logger` | 与 `debug`, (中文(简体) ), `info`, (中文(简体) ), `warn`, (中文(简体) ), `error` 方法 |
| `LogLevel` | `'debug' | 'info' | 'warn' | 'error'` |
| `LoggerConfig` | `boolean | { level?: LogLevel }` |
| `Signal` | 操作执行中的信号事件 |
| `SignalAdapter` | 处理信号的接口 |
| `SignalType` | `'start' | 'step' | 'end' | 'error'` |
| `SentryAdapterConfig` | `{ category?: string }` |

### 自定义锁定器

执行 `Logger` 自定义后端的接口 :

```typescript
import type { Logger } from '@happyvertical/logger';

class MyLogger implements Logger {
  debug(message: string, context?: Record<string, unknown>): void { /* ... */ }
  info(message: string, context?: Record<string, unknown>): void { /* ... */ }
  warn(message: string, context?: Record<string, unknown>): void { /* ... */ }
  error(message: string, context?: Record<string, unknown>): void { /* ... */ }
}
```

## 许可证

麻省理工学院

## 常见问题

### @happyvertical/logger 是什么？

HARE SDK 带有信号适配器的结构记录

### 如何安装 @happyvertical/logger？

在项目目录运行 npm install @happyvertical/logger，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-logger-context，可以用 npx have-logger-context 直接运行。

### @happyvertical/logger 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/logger 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/logger 可以商用吗？

@happyvertical/logger 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/logger 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/logger 在 2026/10/17 – 2026/11/15 这 30 天内被下载 41,777 次，日均约 1,393 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/logger 还在维护吗？

最新版本 0\.113\.1 发布于 2026/11/17（今天）；至今共发布 131 个版本，其中过去 12 个月发布了 131 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

