# @exodus/headless 中文文档

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

版本：5\.0\.0-rc\.105
npm 元数据更新时间：2026-11-09T14:28:03.734Z
中文译文更新时间：2026-11-14T04:02:56.339Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：186 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：38 个
- 首次发布：2023-03-28T08:40:55.290Z
- 最新版本发布：2026-11-09T14:28:03.491Z
- 近 30 天下载量：12407（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：281（近 12 个月 16 个）

## 中文简介

平台不可知的Exodus 钱包 SDK

## 安装

```sh
npm install @exodus/headless
```

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

## README

# @ exodus/ 无头

平台-不可知的Exodus钱包 SDK,包括种子短语管理,交易签名,块链元数据,余额等核心功能.

## 目录

-   [快速启动](https://npmcn.com/package/%40exodus/headless/#readme-quick-start)
-   [生命周期](https://npmcn.com/package/%40exodus/headless/#readme-lifecycle)
-   [端口](https://npmcn.com/package/%40exodus/headless/#readme-port)
-   [适配器](https://npmcn.com/package/%40exodus/headless/#readme-adapters)
-   [配置](https://npmcn.com/package/%40exodus/headless/#readme-config)
-   [无头 API](https://npmcn.com/package/%40exodus/headless/#readme-headless-api)

## 快速启动

```js
import createExodus from '@exodus/headless'
import referrals from '@exodus/headless/src/modules/referrals'
import Emitter from '@exodus/wild-emitter'

// 1. Create port. Acts as an event bus between headless wallet and client
const port = new Emitter()

// 2. Instantiate client-specific adapters and config. More details below
const adapters = {}
const config = {}

// 3. Create Exodus container
const exodusContainer = createExodus({ port, adapters, config })

// 4. Register external modules. Does not support overriding modules at the moment.
exodusContainer.register({
  definition: {
    id: 'remoteConfig',
    factory: createRemoteConfig,
    dependencies: ['config', 'fetch', 'logger'],
  },
})

// see an example feature definition:
// ../../features/geolocation/index.js
exodusContainer.use(referrals())
exodusContainer.use(myCustomFeature({ id: 'myCustomFeature', ... }))

// 5. Resolve exodus instance
const exodus = exodusContainer.resolve()

// 6. Start exodus instance
await exodus.wallet.start()

// 7. Use it!
await exodus.wallet.create({ passphrase: 'my-super-secure-passphrase' })

// 8. Use your custom feature API, if any
exodus.myCustomFeature.doThatThingYouDo()
```

## 生命周期

无头钱包实例在一生中通过不同的状态过渡. 相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相相去相相去相相去相去相去相去相去相去相相去相相相相相相相相相去相去相相去相去相相相相相相相相相相相相

-   Fires hook call:允许模块订阅并停止过渡,直到收听者解决.
-   Fires event call:所有钩子被执行并解决后发回.

关于生命周期钩子的更多信息,请参见: [应用程序特性文档](https://npmcn.com/package/features/application#lifecycle-hooks)。 。 。 .

## 端口

无头钱包和客户端之间的事件总线

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| 订阅 | `({ type: string, payload: any }) => void` | 订阅受事. |
| 未订阅 | `({ type: string, payload: any }) => void` | 不订阅接收事件的处理器 . |
| 发射 | `(type: string, payload: any) => void` | 释出一事. |

## 适配器

适配器是针对客户对钱包功能所需的定义API的特定执行.

这个模块需要新的适配器,因为我们将更多的模块迁移到它。 下文解释了本单元当时需要哪些内容.

### 模块

`AssetsModule` 执行。 目前正在注入,因为我们的每个客户都有不同的执行方式.

### 创建标记器

返回带有指定命名空间的 Logger 类实例的函数 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 命名空间 | `string` | 日志的命名空间 . |

返回的 Logger 实例有以下方法:

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| 追踪 | `(...args: any[]) => void` | 登录带有跟踪级别的信件 . |
| 调试 | `(...args: any[]) => void` | 用调试级别登录信件 . |
| 日志 | `(...args: any[]) => void` | 用日志级别登录信件 . |
| 资讯 | `(...args: any[]) => void` | 用信息级别登录信件 . |
| 警告( e) | `(...args: any[]) => void` | 以警告级别登录信件 . |
| 错误 | `(...args: any[]) => void` | 以错误级别登录信件 . |

每种方法都采用任意数量的参数,这些参数将作为带有相应日志级的信件被记录. 信件会被前缀为日志的命名空间 .

### 遗产PrivTopub

私自到公钥转换功能.

每个键为资产名称且值为函数的对象 `Buffer` 返回 a `Buffer`。 。 。 .

### 不安全storage 中

不安全( raw text) 存储实例 。 内部被模块用来将数据粘入客户端下层存储层.

在多数情况下, 您可能想要使用加密存储( 尚未迁移) .

检查 [存储光谱](https://npmcn.com/package/adapters/storage-spec/spec.md) 关于存储 API 的更详细信息

### 可迁移的垃圾堆

复制 `storage` 但仅用于移民。 这样我们就可以解锁存储,但应用程序的其他部分仍然无法访问.

### 种子集

存储实例被钱包模块用来不稳地存储种子和自动生成的密码句(如果有的话).

检查 [存储光谱](https://npmcn.com/package/adapters/storage-spec/spec.md) 关于存储 API 的更详细信息

> **说明:** 因为浏览器扩展需要密码句来加密/解密种子,所以它作为第3个参数被传递来获取/设定

### 密码句缓存

密码卡切类的例子 .

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| 设定 | `(passphrase: string) => void` | 用给定的值设置密码句 . |
| 起来 | `() => string` | 获取当前密码句值 . |
| 更改Ttl | `(ttl: number) => void` | 更改密码句缓存的活取时间值( TTL) . |
| 清除 | `() => void` | 清除密码句缓存 . |
| 排程清除 | `() => void` |  |

## 配置

Exodus 实例附加配置选项的对象.

目前没有使用.

## 调试

一些功能暴露出API用于易被调试,故障排除和PR测试. 您可以访问这些 API 在外流。 调试 。 要启用它们, 只需通过调试: 真实到无头工厂函数 :

```js
import createExodus from '@exodus/headless'

const exodusContainer = createExodus({ port, adapters, config, debug: true })

exodusContainer.debug.geolocation.merge({ countryCode: 'US' })
```

## 无头 API

### 钱包

> 类型:对象

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| 已存在 | `async () => boolean` | 检查设备上是否存在钱包 . |
| 创建 | `async ({ passphrase?: string }) => void` | 创建新钱包 |
| 导入 | `async ({ mnemonic: string, passphrase?: string, forceRestart?: boolean }) => void` | 导入已存在的钱包 |
| 删除 | `async ({ passphrase?: string }) => void` | 删除钱包。 如果创建了钱包, 密码句是强制的 |
| 锁定 | `async () => void` | 锁定钱包 |
| 解锁 | `async ({ passphrase?: string }) => void` | 解锁钱包。 如果创建了钱包, 密码句是强制的 |
| 已锁定 | `async () => boolean` | 检查钱包是否锁定 |
| 获得磁性 | `async () => void` | 将钱包设置为备份 |
| 更改密码 | `async ({ currentPassphrase?: string. newPassphrase: string }) => void` | 更改密码句 。 如果创建了钱包, 当前密码句是强制的 |
| 从当前措辞恢复 | `async ({ passphrase?: string }) => void` | 恢复当前钱包 。 如果创建了钱包, 密码句是强制的 |
| 装入 | `async () => void` | 通过端口补水数据装载 UI(`BE Only`(中文(简体) ) |
| 卸货 | `async () => void` | 通过端口重新加水数据来卸载 UI(`BE Only`(中文(简体) ) |
| 更改锁定时器 | `async ({ ttl: number }) => void` | 更改自动解锁 ttl (`BE Only`(中文(简体) ) |

### 钱包账户

> 类型:对象

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| 创建 | `async (walletAccountFields) => void` | 创建一个带有所提供字段的新钱包账户. |
| 更新 | `async (name, walletAccountFields) => void` | 以提供的字段更新现有的钱包账户. |
| 启用 | `async (name) => void` | 启用已存在的钱包账户. |
| 禁用 | `async (name) => void` | 禁用现有的钱包账户. |
| 获取可启用 | `async () => object` | 返回已启用的钱包账户为 `{ [name]: WalletAccount }`。 。 。 . |

### 块链元数据

> 类型:对象

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| 获取 TxLog | `async ({ assetName, walletAccount }) => TxSet` | 获取提供的 TxSet `assetName`编号 :`walletAccount` 组合( 资产来源) |
| 获取已登录的 TxLogs | `async () => object` | 全部装入 `TxSet`s 作为 `{ [walletAccount]: { [assetName]: TxSet } } object` |
| 更新 Txs | `async ({ assetName: string, walletAccount: string, txs: object[] }) => void` | 添加或更新 txs,其中提供更新 `txs` |
| 覆盖Txs | `async ({ assetName: string, walletAccount: string, txs: object[], notifyReceivedTxs: ?boolean }) => void` | 覆盖指定的 txs . |
| 清除 Txs | `async ({ assetName: string, walletAccount: string }) => void` | 删除资产源的 txs . |
| 删除 Txs | `async ({ assetName: string, walletAccount: string, txs: object[] }) => void` | 删除已提供的 txs . |
| 获取账户状态 | `async ({ assetName, walletAccount }) => AccountState` | 获取提供的资产来源的账户状态 |
| 获取账户状态 | `async () => object` | 全部装入 `AccountState`s 作为 `{ [walletAccount]: { [assetName]: AccountState } } object` |
| 更新账户状态 | `async ({ assetName: string, walletAccount: string, newData: object }) => void` | 更新资产来源账户状态 . |
| 删除账户状态 | `async ({ assetName: string, walletAccount: string }) => void` | 删除资产来源的账户状态 . |
| 批次 | `() => Batch` | 创建批次更新 。 见 [块链元数据](https://npmcn.com/package/features/blockchain-metadata/) 详细批量读取. |

### 资产

> 类型:对象

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| 启用 | `async (assetNames: string[]) => void` | 启用资产 . |
| 禁用 | `async (assetNames: string[]) => void` | 禁用资产. |
| 添加可启用的键 | `async (assetId: string, baseAssetName: string) => string` | 添加并启用自定义符号。 返回创建的 `asset`是因为 `.name` |

### 语言

> 类型:对象

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| 时间 | `async (currency: string) => void` | 更改当前货币. |
| 设置语言 | `async (language: string) => void` | 更改当前语言 . |

### 订阅

> 类型:函数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 订阅 | `({ type: string, payload: any }) => void` | 订阅受事. |
| 未订阅 | `({ type: string, payload: any }) => void` | 不订阅接收事件的处理器 . |

### 特性标记

> 类型:对象

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| 启用 | `async (featureName: string) => void` | 启用特性旗门特性. |
| 禁用 | `async (featureName: string) => void` | 禁用特性旗门特性. |

见 [更多细节](https://npmcn.com/package/features/feature-flags/)。 。 。 .

## 常见问题

### @exodus/headless 是什么？

平台不可知的Exodus 钱包 SDK

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

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

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

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

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

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

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

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

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

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

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

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