# @contrast/logger 中文文档

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

版本：1\.44\.1
npm 元数据更新时间：2026-11-04T16:32:02.614Z
中文译文更新时间：2026-11-10T17:14:28.977Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40contrast/logger
原文对照：https://npmcn.com/package/%40contrast/logger/?lang=original

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

- 包体积（解压后）：23 kB，9 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.9\.0
- 运行依赖：3 个
- 首次发布：2022-06-16T12:13:31.164Z
- 最新版本发布：2026-11-04T16:32:02.444Z
- 近 30 天下载量：17489（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：72（近 12 个月 19 个）

## 中文简介

对比代理服务的集中伐木

## 安装

```sh
npm install @contrast/logger
```

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

## README

# `@contrast/logger`

-   [使用量](https://npmcn.com/package/%40contrast/logger/#readme-usage)
-   [结构化日志](https://npmcn.com/package/%40contrast/logger/#readme-structured-logging)
    -   [过滤](https://npmcn.com/package/%40contrast/logger/#readme-filtering)
-   [最佳做法](https://npmcn.com/package/%40contrast/logger/#readme-best-practices)
    -   [错误](https://npmcn.com/package/%40contrast/logger/#readme-errors)
    -   [对象](https://npmcn.com/package/%40contrast/logger/#readme-objects)
-   [名称间隔](https://npmcn.com/package/%40contrast/logger/#readme-namespacing)

## 使用量

集中,结构化的采伐 对比剂服务,建于皮诺. `@contrast/agentify` 将日志写入核心, 因此组件使用 `core.logger`数字 :

```ts
core.logger.info({ foo, bar }, 'message with %s, %d', 'string', 123);
```

在代理机外,将其安装到自己的核心对象上:

```ts
const { default: install } = require('@contrast/logger');

const logger = install(core); // also sets core.logger
```

见 [皮诺](https://github.com/pinojs/pino/blob/master/docs/api.md#logger-instance) 记录日志的 API .

## 结构化日志

皮诺日志为JSON,因此特别擅长记录JavaScript对象.

鉴于:

```ts
logger.info('hello world');
logger.error('this is at error level');
logger.info('the answer is %d', 42);
logger.info({ obj: 42 }, 'hello world');
logger.info({ obj: 42, b: 2 }, 'hello world');
logger.info({ nested: { obj: 42 } }, 'nested');
```

日志输出外观如下:

```json
{"level":30,"time":1649266923912,"pid":12345,"hostname":"foo","msg":"hello world"}
{"level":50,"time":1649266923913,"pid":12345,"hostname":"foo","msg":"this is at error level"}
{"level":30,"time":1649266923913,"pid":12345,"hostname":"foo","msg":"the answer is 42"}
{"level":30,"time":1649266923913,"pid":12345,"hostname":"foo","obj":42,"msg":"hello world"}
{"level":30,"time":1649266923913,"pid":12345,"hostname":"foo","obj":42,"b":2,"msg":"hello world"}
{"level":30,"time":1649266923913,"pid":12345,"hostname":"foo","nested":{"obj":42},"msg":"nested"}
```

你用得着 [`pino-pretty`](https://github.com/pinojs/pino-pretty) 改为格式 开发过程中的日志. 之前的台词,当传递到pino- pretty,将 格式改为:

```sh
node example.js | npx pino-pretty
```

```
[1649266998216] INFO (12345 on foo): hello world
[1649266998216] ERROR (12345 on foo): this is at error level
[1649266998216] INFO (12345 on foo): the answer is 42
[1649266998216] INFO (12345 on foo): hello world
    obj: 42
[1649266998216] INFO (12345 on foo): hello world
    obj: 42
    b: 2
[1649266998216] INFO (12345 on foo): nested
    nested: {
      "obj": 42
    }
```

### 过滤

JSON记录除了在漂亮印刷时更容易阅读外 我们用公用设施过滤 [`jq`](https://jqlang.github.io/jq/)。 。 。 .

例如,我们只能过滤错误消息:

```sh
node example.js | jq "select(.level == 50)"
```

输出( 单击以扩展)

```json
{
  "level": 50,
  "time": 1649268122322,
  "pid": 12345,
  "hostname": "foo",
  "msg": "this is at error level"
}
```

或者,我们可以只查看登录条目 `obj` 属性 :

```sh
node example.js | jq "select(.obj)"
```

输出( 单击以扩展)

```json
{
  "level": 30,
  "time": 1649268235040,
  "pid": 12345,
  "hostname": "foo",
  "obj": 42,
  "msg": "hello world"
}
{
  "level": 30,
  "time": 1649268235040,
  "pid": 12345,
  "hostname": "foo",
  "obj": 42,
  "b": 2,
  "msg": "hello world"
}
```

见 `jq`是因为 [教程](https://jqlang.github.io/jq/tutorial/) 财务报告和审定财务报表 [手动](https://jqlang.github.io/jq/manual/) 以实例说明 强大的JSON处理可以是!

## 最佳做法

### 错误

皮诺在通过时会特别处理错误 `err` _或者说_ 当通过时 作为第一个论点. 见: [https://github.com/pinojs/pino/blob/master/docs/api.md#serializers-object 页面存档备份,存于互联网档案馆](https://github.com/pinojs/pino/blob/master/docs/api.md#serializers-object)

例如,在处理错误时,我们应该使用以下模式:

```ts
try {
  // ...something that throws
} catch (err) {
  logger.warn(err);
  // if we want to customize the message:
  logger.warn(err, 'something bad happened');
  // or if we need to provide additional data:
  logger.warn({ err, data }, 'something broke when handling %s', filename);
}
```

输出( 单击以扩展)

```
[1649264653814] WARN (12345 on foo): yikes!
  err: {
    "type": "Error",
    "message": "yikes!",
    "stack":
        Error: yikes!
            at Object.<anonymous> (/path/to/file.js:5:13)
            at Module._compile (internal/modules/cjs/loader.js:1085:14)
            at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
            at Module.load (internal/modules/cjs/loader.js:950:32)
            at Function.Module._load (internal/modules/cjs/loader.js:790:12)
            at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:75:12)
            at internal/main/run_main_module.js:17:47
  }

[1649264653814] WARN (12345 on foo): something bad happened
  err: {
    "type": "Error",
    "message": "yikes!",
    "stack":
        Error: yikes!
            at Object.<anonymous> (/path/to/file.js:5:13)
            at Module._compile (internal/modules/cjs/loader.js:1085:14)
            at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
            at Module.load (internal/modules/cjs/loader.js:950:32)
            at Function.Module._load (internal/modules/cjs/loader.js:790:12)
            at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:75:12)
            at internal/main/run_main_module.js:17:47
  }

[1649264653814] WARN (12345 on foo): something broke when handling foo.js
  data: {
    "foo": "bar"
  }
  err: {
    "type": "Error",
    "message": "yikes!",
    "stack":
        Error: yikes!
            at Object.<anonymous> (/path/to/file.js:5:13)
            at Module._compile (internal/modules/cjs/loader.js:1085:14)
            at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
            at Module.load (internal/modules/cjs/loader.js:950:32)
            at Function.Module._load (internal/modules/cjs/loader.js:790:12)
            at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:75:12)
            at internal/main/run_main_module.js:17:47
  }
```

### 对象

与其将信息纳入日志信息本身,不如 在第一个参数中包括数据.

例如,如果我们想要记录对象的内容:

```ts
const route = { method: 'GET', path: '/users/:id', handler: 'getUser' };
logger.info({ route }, 'route registered');
// instead of
logger.info('route registered: %o', route);
```

输出( 点击可扩展)

```
[1649265443612] INFO (12345 on foo): route registered
  route: {
    "method": "GET",
    "path": "/users/:id",
    "handler": "getUser"
  }

[1649265443613] INFO (12345 on foo): route registered: {"method":"GET","path":"/users/:id","handler":"getUser"}
```

## 名称间隔

当在另一个模块中使用日志时, 您可以使用 页:1 [`child`](https://github.com/pinojs/pino/blob/master/docs/api.md#loggerchildbindings-options--logger) 方法.

例如,在 `@contrast/rewriter` 模块,我们可以命名日志 内容如下:

```ts
const logger = core.logger.child({ name: 'contrast:rewriter' });
```

## 常见问题

### @contrast/logger 是什么？

对比代理服务的集中伐木

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

在项目目录运行 npm install @contrast/logger，或使用 pnpm add / yarn add / bun add。

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

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

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @contrast/logger 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.9\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

@contrast/logger 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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