# @dotcom-reliability-kit/serialize-error 中文文档

规范地址：https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/

版本：5\.1\.0
npm 元数据更新时间：2026-08-19T16:09:01.527Z
中文译文更新时间：2026-11-12T17:43:42.781Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dotcom-reliability-kit/serialize-error
原文对照：https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/?lang=original
项目主页：https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/serialize-error#readme
源码仓库：https://github.com/Financial-Times/dotcom-reliability-kit

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

- 包体积（解压后）：19.5 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.12 \|\| ^24 \|\| ^26
- 运行依赖：0 个
- 首次发布：2022-05-16T07:24:34.005Z
- 最新版本发布：2026-08-19T16:09:01.328Z
- 近 30 天下载量：19508（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 6 个）

## 中文简介

用于串行一个对日志、查看引擎和转换为 JSON 的对错误对象的功能

## 安装

```sh
npm install @dotcom-reliability-kit/serialize-error
```

也可以使用：`pnpm add @dotcom-reliability-kit/serialize-error`、`yarn add @dotcom-reliability-kit/serialize-error`、`bun add @dotcom-reliability-kit/serialize-error`

## README

# @dotcom-可靠性-kit/序列化-error

一个用于序列化一个错误对象的功能,其方式对日志,查看引擎,以及转换为JSON是友好的. 此模块是 [FT.com 可靠性工具包](https://github.com/Financial-Times/dotcom-reliability-kit#readme)。 。 。 .

-   [使用量](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-usage)
    -   [`serializeError`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializeerror)
    -   [`SerializedError` 类型](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederror-type)
        -   [`SerializedError.id`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorid)
        -   [`SerializedError.fingerprint`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorfingerprint)
        -   [`SerializedError.name`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorname)
        -   [`SerializedError.code`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorcode)
        -   [`SerializedError.message`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrormessage)
        -   [`SerializedError.isOperational`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorisoperational)
        -   [`SerializedError.relatesToSystems`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorrelatestosystems)
        -   [`SerializedError.cause`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorcause)
        -   [`SerializedError.errors`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorerrors)
        -   [`SerializedError.stack`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorstack)
        -   [`SerializedError.statusCode`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrorstatuscode)
        -   [`SerializedError.data`](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederrordata)
-   [移动](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-migrating)
-   [捐款](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-contributing)
-   [许可证](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-license)

## 使用量

安装 `@dotcom-reliability-kit/serialize-error` 作为依附关系:

```bash
npm install --save @dotcom-reliability-kit/serialize-error
```

在代码中包含 :

```js
import serializeError from '@dotcom-reliability-kit/serialize-error';
```

> \[TIP\] 如果您使用此软件包并带有 TypeScript , 我们建议您使用以下设置: `tsconfig.json` 避免类型错误的文件 :
> 
> ```json
> {
>     "esModuleInterop": true,
>     "module": "nodenext",
>     "moduleResolution": "nodenext"
> }
> ```

### `serializeError`

这个 `serializeError` 函数接受类似错误的对象(例如 `Error` 或带有 `message` 属性),并返回一个平版 JavaScript 对象(符合 [`SerializedError` 类型](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializederror-type)包含相关属性:

```js
serializeError(new Error('example message'));
// {
//     id: null,
//     fingerprint: '...',
//     name: 'Error',
//     code: 'UNKNOWN',
//     message: 'An error occurred',
//     isOperational: false,
//     relatesToSystems: [],
//     cause: null,
//     stack: '...',
//     statusCode: null,
//     data: {}
// }
```

在普通对象中也可以通过,如果您已经有一个看起来像出错的物体(例如来自JSON API响应):

```js
serializeError({
    message: 'example message'
});
```

### `SerializedError` 类型

这个 `SerializedError` 类型文档的返回值 [`serializeError` 函数](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/#readme-serializeerror)。它将永远具有以下属性,从给定的错误对象中提取这些属性.

#### `SerializedError.id`

这取自于 `error.id` 财产,但只有在它是一个 `String`默认 `null`。 。 。 .

#### `SerializedError.fingerprint`

这是错误堆栈第一部分的散列,用于帮助代码库同一部分发生的分组错误. 指纹是 `null` 如果错误不包括堆栈跟踪.

> \[尖叫声\]  
> 不要依赖错误指纹的格式或长度,因为下面的散列可能会不提前变化. 你个 _能够_ 取决于指纹对所抛出错误类型的独特性.

#### `SerializedError.name`

这取自于 `error.name` 总是被扔到一个 `String`默认 `"Error"`。 。 。 .

#### `SerializedError.code`

这取自于 `error.code` 总是被扔到一个 `String`默认 `"UNKNOWN"`。 。 。 .

#### `SerializedError.message`

这取自于 `error.message` 总是被扔到一个 `String`默认 `"An error occurred"`,但我们希望这个库能够适应出乎意料的输入数据.

#### `SerializedError.isOperational`

这表明错误是否在运行(已知). 见文档 [`OperationalError`](https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/errors#operationalerror) 更多信息。 这是从 `error.isOperational` 属性。 它总是被一个 `Boolean` 默认为 `false`。 。 。 .

#### `SerializedError.relatesToSystems`

此数组包含一个列表 [系统代码](https://biz-ops.in.ft.com/list/Systems) 与错误有关。 它默认为空数组 .

#### `SerializedError.cause`

这是从“% 1” 中提取的错误实例 `error.cause` 属性,在分配前按序列排列。 默认为 `null`。 。 。 .

#### `SerializedError.errors`

这是从 `error.errors` 财产(例如来自 [总和错误](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError)) (中文(简体) ). 错误在被指定之前进行序列化.

#### `SerializedError.stack`

这取自于 `error.stack` 属性。 如果此属性不是字符串, 那么它将默认为 `null`。 。 。 .

#### `SerializedError.statusCode`

这取自于 `error.statusCode` 属性,然后是 `error.status` 属性(我们使用两个属性来保持与第三方请求和错误库的相容性)。 这些总是被扔到一个 `Number` 此属性默认为 `null`。 。 。 .

#### `SerializedError.data`

这取自于 `error.data` 属性。 如果此属性不是普通对象, 那么它会默认为空对象 : `{}`。 。 。 .

## 移动

咨询 [移徙指南](https://npmcn.com/package/%40dotcom-reliability-kit/serialize-error/docs/migration.md) 如果你想要迁移到这个软件包的后期主要版本.

## 捐款

见 [可靠性工具包中心贡献指南](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md)。 。 。 .

## 许可证

凭 [麻省理工学院](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/LICENSE) 执照.  
版权:"2022","金融时报"有限公司.

## 常见问题

### @dotcom-reliability-kit/serialize-error 是什么？

用于串行一个对日志、查看引擎和转换为 JSON 的对错误对象的功能

### 如何安装 @dotcom-reliability-kit/serialize-error？

在项目目录运行 npm install @dotcom-reliability-kit/serialize-error，或使用 pnpm add / yarn add / bun add。

### @dotcom-reliability-kit/serialize-error 支持 TypeScript 吗？

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

### @dotcom-reliability-kit/serialize-error 支持 ESM 还是 CommonJS？

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

### @dotcom-reliability-kit/serialize-error 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.12 \|\| ^24 \|\| ^26。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dotcom-reliability-kit/serialize-error 可以商用吗？

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

### @dotcom-reliability-kit/serialize-error 的下载量有多少？

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

### @dotcom-reliability-kit/serialize-error 还在维护吗？

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