# @exodus/errors 中文文档

规范地址：https://npmcn.com/package/%40exodus/errors/

版本：3\.8\.2
npm 元数据更新时间：2026-10-13T17:16:24.715Z
中文译文更新时间：2026-11-14T04:06:06.494Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40exodus/errors
原文对照：https://npmcn.com/package/%40exodus/errors/?lang=original
项目主页：https://github.com/ExodusMovement/exodus/tree/master/libs/libraries/errors
源码仓库：https://github.com/ExodusMovement/exodus

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

- 包体积（解压后）：36.7 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2024-07-17T12:24:30.061Z
- 最新版本发布：2026-10-13T17:16:24.491Z
- 近 30 天下载量：11668（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 6 个）

## 中文简介

用于客户端代码中错误处理的软件,例如消毒

## 安装

```sh
npm install @exodus/errors
```

也可以使用：`pnpm add @exodus/errors`、`yarn add @exodus/errors`、`bun add @exodus/errors`

## README

# @ exodus/ errors

## 使用量

```javascript
import { SafeError } from '@exodus/errors'

try {
  throw new Error('Something went wrong')
} catch (e) {
  const safeError = SafeError.from(e)

  // It's now safe to report or log the error, even to a remote server.
  console.error({
    name: safeError.name, // Sanitized error name.
    code: safeError.code, // Optional error code (if present).
    hint: safeError.hint, // Optional error hint (if present).
    stack: safeError.stack, // Sanitized stack trace.
    timestamp: safeError.timestamp, // When the error occurred.
  })
}
```

## 财务问题

### 为什么使用 SafeError 而不是内置错误 ?

在大型代码库中,错误可以从任何地方抛出,因此不可能对每一个错误消息进行敏感信息的审计. 包含敏感数据的单一错误可能暴露用户信息。 集中处理错误 `SafeError` 通过确保:

1.  **控制出错流量**:所有出错在撞击出错跟踪系统之前,都会经过一个经过了良好测试的单一消毒层.
2.  **可强制执行的安全**:错误处理可以通过代码拥有者来拥有,并被测试所覆盖,所以不会漏出任何不被注意.

除了强制执行这些做法外, `SafeError` 包括一些关键的设计决定,使其比原生错误对象更加安全可靠:

1.  **信件卫生**编号: `message` 来自内建错误的属性被故意省略,因为它常常包含敏感信息。 相反,a `hint` 属性仅包含已消毒的非敏感信息.
2.  **本地堆栈解析**: 图书馆使用 [`Error.prepareStackTrace` API 密码](https://v8.dev/docs/stack-trace-api) 来解析堆栈跟踪,提供跨越不同JavaScript环境的一致而可靠的堆栈跟踪信息.
3.  **可变性**: 一旦创建, a `SafeError` 实例不能被修改,防止篡改错误数据.
4.  **安全序列化**编号: `toJSON` 方法确保记录或发送到错误跟踪服务的安全序列化.

### 为什么不编辑错误消息 ?

对错误信息进行解析/保密是不可靠的,失败的代价是潜在的用户资金损失和永久声誉损害.

### 为什么不使用内置 `.stack` 错误属性 ?

不幸的是,内在的 `.stack` 财产是可变异的,而且不受我们的控制。 相反,我们使用 `Error.prepareStackTrace` API,它使我们能够确保我们访问实际的呼叫堆栈而不是缓存 `err.stack` 可能已经消耗和修改的数值。 然后我们把它分析成一种结构化的格式, 我们可以安全地消毒和控制。 这种方法在不同的环境中(目前支持V8和Hermes)提供了一致,可靠的堆栈痕迹.

## 食谱

> \[TIP\] 在潜入食谱之前,你可能想要熟悉什么是"安全弦": [https://github.com/Exodus Movement/exodus-hydra/tree/master/librarys/saf-string 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/ExodusMovement/exodus-hydra/tree/master/libraries/safe-string)

### 我想保存安全错误中的服务器错误

你控制服务器吗? 如果是的话, 最好从您的服务器发送短错误代码 . `err.code` 将 [将经过](https://github.com/ExodusOSS/hydra/blob/master/libraries/errors/src/safe-error.ts#L32) 安全错误胁迫.

如果您不控制服务器, 并且您知道服务器返回的具体错误消息, 您可以预先定义它们 `safeString`数字 :

```js
import { safeString } from '@exodus/safe-string'

// From: https://github.com/ethereum/go-ethereum/blob/master/core/txpool/errors.go.
export const KnownErrors = new Set([
  safeString`already known`,
  safeString`invalid sender`,
  safeString`transaction underpriced`,
])
```

您现在可以处理这样的失败请求 :

```js
import { safeString } from '@exodus/safe-string`
import { KnownErrors } from './errors.js'

const response = await this.request(request)
const error = response?.error

if (error) {
  const message = KnownErrors.get(msg) ?? safeString`unknown error`
  throw new Error(safeString`Bad rpc response: ${message}`)
}
```

## 解决问题

### 安全错误实例返回 `undefined` 堆积追踪?

可能意味着有东西进入 `error.stack` _在此之前_ 安全错误构建器有机会应用自定义 `Error.prepareStackTrace` 处理者。 这可能是反应,高级错误处理器,或任何其他框架. `error.stack` 仅在第一次访问时计算,所以不会要求自定义处理器进行后续尝试(参见 `stack.test.js` 快速演示.

如果你能确定具体地点 `.stack` 已访问, 考虑像这样捕捉堆栈跟踪 :

```javascript
import { captureStackTrace, SafeError } from '@exodus/errors'

try {
  // the devil's work
} catch (e) {
  captureStackTrace(e)
  void e.stack // Intentionally access the property to "break" it here.
  SafeError.from(e).stack // A non-empty string!
  // 🎉 Congrats — you just (hopefully) saved hours of debugging! The custom stack trace parsing logic now works because the stack was captured explicitly above.
}
```

## 常见问题

### @exodus/errors 是什么？

用于客户端代码中错误处理的软件,例如消毒

### 如何安装 @exodus/errors？

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

### @exodus/errors 支持 TypeScript 吗？

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

### @exodus/errors 支持 ESM 还是 CommonJS？

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

### @exodus/errors 可以商用吗？

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

### @exodus/errors 的下载量有多少？

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

### @exodus/errors 还在维护吗？

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