# @andrewheberle/ts-slog 中文文档

规范地址：https://npmcn.com/package/%40andrewheberle/ts-slog/

版本：1\.5\.0
npm 元数据更新时间：2026-09-16T03:23:38.341Z
中文译文更新时间：2026-11-06T15:43:20.188Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40andrewheberle/ts-slog
原文对照：https://npmcn.com/package/%40andrewheberle/ts-slog/?lang=original
项目主页：https://github.com/andrewheberle/ts-slog#readme
源码仓库：https://github.com/andrewheberle/ts-slog

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

- 包体积（解压后）：19.9 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-11-07T05:36:20.527Z
- 最新版本发布：2026-09-16T03:23:38.061Z
- 近 30 天下载量：2859（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 5 个）

## 中文简介

TypeScript 的简单结构记录器

## 安装

```sh
npm install @andrewheberle/ts-slog
```

也可以使用：`pnpm add @andrewheberle/ts-slog`、`yarn add @andrewheberle/ts-slog`、`bun add @andrewheberle/ts-slog`

## README

# @andrewheberle/ts-slog (英语)

TypeScript 应用程序的简单结构记录器.

## 安装

```bash
npm install @andrewheberle/ts-slog
```

## 使用量

### 基本示例

```typescript
import { Logger } from '@andrewheberle/ts-slog'

const logger = new Logger()

logger.info("Application started")
logger.debug("Debug information", "userId", 123, "action", "login")
logger.warn("Warning message", "retries", 3)
logger.error("An error occurred", "errorCode", 500)
```

### 日志级别

日志支持四个日志级别:

-   `Debug` (0) - 详细调试信息
-   `Info` (1) - 一般信息信息(默认)
-   `Warning` (2) - 警告信息
-   `Error` (3) - 错误信息

### 配置

创建日志实例时配置最小日志级别 :

```ts
import { Logger, LogLevel } from "@andrewheberle/ts-slog"

// Only log warnings and errors
const logger = new Logger({ minLevel: LogLevel.Warning })

logger.debug("This won't be logged")
logger.info("This won't be logged either")
logger.warn("This will be logged")
logger.error("This will be logged too")
```

### 添加上下文

通过通过附加参数添加密钥值对以登录条目 :

```ts
import { Logger } from "@andrewheberle/ts-slog"

const logger = new Logger()

logger.info(
    "User logged in",
    "userId", 123,
    "username", "john.doe",
    "ip", "192.168.1.1"
)

// Output:
// {
//   level: 'info',
//   message: 'User logged in',
//   userId: 123,
//   username: 'john.doe',
//   ip: '192.168.1.1'
// }
```

### 组

一组K/V对可分组如下:

```ts
import { group, Logger } from "@andrewheberle/ts-slog"

const logger = new Logger()

logger.info(
    "User logged in",
    ...group("user", "id", 123, "username", "john.doe"),
    "ip", "192.168.1.1"
)

// Output:
// {
//   level: 'info',
//   message: 'User logged in',
//   user.id: 123,
//   user.username: 'john.doe',
//   ip: '192.168.1.1'
// }
```

### 文本输出

默认,默认 `logHandler` 将日志对象直接传递到 `console.log`。使用内置 `TextHandler` 改为格式化条目 作为一行案文:

```ts
import { Logger, TextHandler } from "@andrewheberle/ts-slog"

const logger = new Logger({ logHandler: TextHandler })

logger.info("User logged in", "userId", 123, "action", "login")

// Output:
// INFO User logged in userId=123 action=login
```

引用含有白空格的字符串值 :

```ts
logger.info("User logged in", "name", "John Doe", "userId", 123)

// Output:
// INFO: User logged in name="John Doe" userId=123
```

## API 密码

### `new Logger(settings?)`

创建新的日志实例.

**参数:**

-   `settings` (可选):配置对象
    -   `logHandler`: Handler 到输出日志( 默认值 : `console.log`(中文(简体) )
    -   `minLevel`: 最小日志级别( 默认值 : `LogLevel.Info`(中文(简体) )

### 方法

-   `debug(message: string, ...args: unknown[]): void` - 在“调试”级别登录
-   `info(message: string, ...args: unknown[]): void` - 在“ info”级登录
-   `warn(message: string, ...args: unknown[]): void` - 在“警告”一级登录
-   `error(message: string, ...args: unknown[]): void` - 记录在“错误”一级
-   `with(...args: unknown[]): Logger` - 返回一个新的 `Logger` 增加了 K/V 对

所有方法都接受一个消息串,然后是可选的密钥值对.

### 职能

-   `group(key: string, ...args: unknown[]): unknown[]` - 根据密钥前缀创建 K/V 对
-   `TextHandler(output: Record<string, unknown>): void` - 一个 `logHandler` 将日志条目格式化为文本(`level message key=value ...`)并通过 `console.log`

## 许可证

麻省理工学院

## 常见问题

### @andrewheberle/ts-slog 是什么？

TypeScript 的简单结构记录器

### 如何安装 @andrewheberle/ts-slog？

在项目目录运行 npm install @andrewheberle/ts-slog，或使用 pnpm add / yarn add / bun add。

### @andrewheberle/ts-slog 支持 TypeScript 吗？

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

### @andrewheberle/ts-slog 支持 ESM 还是 CommonJS？

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

### @andrewheberle/ts-slog 可以商用吗？

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

### @andrewheberle/ts-slog 的下载量有多少？

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

### @andrewheberle/ts-slog 还在维护吗？

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