# @blockfrost/blockfrost-js 中文文档

规范地址：https://npmcn.com/package/%40blockfrost/blockfrost-js/

版本：6\.2\.0
npm 元数据更新时间：2026-08-21T11:59:54.814Z
中文译文更新时间：2026-11-08T07:17:46.296Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：314 kB，73 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：7 个
- 首次发布：2021-03-26T17:26:43.042Z
- 最新版本发布：2026-08-21T11:59:54.609Z
- 近 30 天下载量：95085（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：111（近 12 个月 4 个）

## 中文简介

用于交互的 JavaScript/ TypeScript SDK [https://blockfrost.io (英语)](https://blockfrost.io/) API 密码

## 安装

```sh
npm install @blockfrost/blockfrost-js
```

也可以使用：`pnpm add @blockfrost/blockfrost-js`、`yarn add @blockfrost/blockfrost-js`、`bun add @blockfrost/blockfrost-js`

## README

![master build ci](https://github.com/blockfrost/blockfrost-js/actions/workflows/build.yml/badge.svg?branch=master) [![npm version](https://badge.fury.io/js/%40blockfrost%2Fblockfrost-js.svg)](https://badge.fury.io/js/%40blockfrost%2Fblockfrost-js) ![downloads](https://img.shields.io/npm/dy/@blockfrost/blockfrost-js) ![](https://github.com/blockfrost/blockfrost-js/blob/master/coverage-badge.svg) [![](https://img.shields.io/badge/made%20by-Five%20Binaries-darkviolet.svg?style=flat-square)](https://fivebinaries.com/)

![](https://blockfrost.io/images/logo.svg)

# 块冻-js

  

[块霜.io](https://blockfrost.io/) SDK为JavaScript为节点.js.

[开始](https://npmcn.com/package/%40blockfrost/blockfrost-js/#readme-getting-started) 二. 支助 [安装](https://npmcn.com/package/%40blockfrost/blockfrost-js/#readme-installation) 二. 支助 [使用量](https://npmcn.com/package/%40blockfrost/blockfrost-js/#readme-usage) 二. 支助 [实例](https://github.com/blockfrost/blockfrost-js-examples) 二. 支助 [SDK API 参考文献](https://github.com/blockfrost/blockfrost-js/wiki/Exports)

  

## 开始

要使用此 SDK, 您首先需要登录到 [blockfrost.io 区名](https://blockfrost.io/),创建您的项目并取回 API 令牌.

![](https://i.imgur.com/WoEIYhk.png)  

## 安装

要运行SDK,你需要Node.js版本16和更高. 虽然你可能会找到一种方法直接在浏览器中运行,但我们不积极支持或提供此情景的排除故障协助. 我们建议自己建立节点Js后端 在前端应用程序中显示您的 API 密钥几乎总是个坏主意.

SDK是挂载在 [npmjs.com (英语)](https://www.npmjs.com/package/@blockfrost/blockfrost-js),因此可以直接使用您最喜欢的软件包管理器来导入.

```console
npm i @blockfrost/blockfrost-js
```

```console
yarn add @blockfrost/blockfrost-js
```

  

## 使用量

从下面的例子中可以看出,使用SDK是相当直线的. 更多例子请查看 [块冻-js-实例](https://github.com/blockfrost/blockfrost-js-examples) 仓库.

所有 SDK 方法列表 [看看我们的维基](https://github.com/blockfrost/blockfrost-js/wiki/Exports)。 。 。 .

```ts
const Blockfrost = require('@blockfrost/blockfrost-js');
// import { BlockFrostAPI } from '@blockfrost/blockfrost-js'; // using import syntax

const API = new Blockfrost.BlockFrostAPI({
  projectId: 'YOUR API KEY HERE', // see: https://blockfrost.io
  // For a list of all options see section below
});
```

### 选项

-   `projectId` - 说吧 `string`, Blockfrost 项目ID(需要)
-   `network` - 说吧 `string`,用于指定项目ID的 Cardano 网络。 (可选的,默认值来自 `projectId` (如果可能的话) 可能的值 : `mainnet`, (中文(简体) ), `testnet`, (中文(简体) ), `preview`, (中文(简体) ), `preprod`。 。 。 .
-   `rateLimiter` - 说吧 `boolean` 或者说 [`RateLimiterConfig`](https://github.com/blockfrost/blockfrost-js/blob/master/src/utils/limiter.ts#L18=),是否启用匹配的限速器 [块冻 API 限制](https://docs.blockfrost.io/#section/Limits) (可选,默认) `true`) (中文(简体) ). 如果您的IP地址是白名单, 您可能想要禁用它 。 您也可以自定义自定义利率限制符 配置对象。 。 。 .
-   `requestTimeout` - 说吧 `number`,等待请求完成多久,以毫秒计(可选,默认) `20000`(中文(简体) )
-   `retrySettings` - 说吧 `RequiredRetryOptions`,用于重试失败请求的定制(可选, [默认值请点击此处](https://github.com/blockfrost/blockfrost-js/blob/master/src/utils/index.ts#L58)(中文(简体) )
-   `debug` - 说吧 `boolean`,是否启用调试日志。 也可以通过设置环境变量来实现 `DEBUG` 改为 `true` (可选,默认) `false`) (中文(简体) ).
-   `customBackend` - 说吧 `string`,将 URL 设置为非官方后端的选项(可选)
-   `version` - 说吧 `number`, Blockfrost API 版本(可选,默认) `0`(中文(简体) )
-   `gotOptions` - 更多选项要传给哥特实例。 详情请参见: [有选项文档](https://github.com/sindresorhus/got/blob/main/documentation/2-options.md)。 。 。 .

## 处理错误

Blockfrost Node.js SDK 抛出两种错误, `BlockfrostServerError` 财务报告和审定财务报表 `BlockfrostClientError`。每个错误都从内置中扩展 `Error` 班级,允许你正确抓住它 并用代码处理它.

### `BlockfrostServerError`

`BlockfrostServerError` 是一个由 Blockfrost API 直接返回的错误。 错误对象的属性匹配 [与 Blockfrost API 定义的格式相同](https://npmcn.com/package/%40blockfrost/blockfrost-js/\(https://docs.blockfrost.io/#section/Errors\)),并增加 `url` 设置到 URL 的字段 `body` 字段设置为错误反应的原始正文,如果错误没有被 Blockfrost 后端(如 nginx)返回.

#### 示例

Blockfrost API 返回 404,对于目前链条上不存在的任何资源都没有找到,即使理论上它可能存在. 更详细的解释检查 [Blockfrost 开发者门户网站](https://www.blockfrost.dev/docs/support/cardano#querying-address-returns-404-not-found-but-my-address-is-valid)。 。 。 .

```ts
// Example demonstrating catching BlockfrostServerError
try {
  const address = await API.addresses('totallyValidAddress');
} catch (error) {
  if (
    error instanceof Blockfrost.BlockfrostServerError &&
    error.status_code === 404
  ) {
    // address was not used before, but most likely we don't want to throw an error
    console.log("Address is totally empty! But that's ok!");
  } else {
    // rethrow other errors
    throw error;
  }
}
```

### `BlockfrostClientError`

`BlockfrostClientError` 是Blockfrost API服务器未返回的错误。 在这种情况下,请求从未到达我们的后端。 最常见的原因与网络有关.

形状 `BlockfrostClientError` 对象与 `BlockfrostServerError`。错误已经 `code` 财务报告和审定财务报表 `message` 和可选 `url` 用于帮助您调查此问题的财产.

以下是一个显示错误格式的小例子:

```json
{
  "code": "ENOTFOUND",
  "message": "getaddrinfo ENOTFOUND api.blockfrost.io",
  "url": "https://cardano-mainnet.blockfrost.io/api/v0/addresses/addr1qxqs59lph(truncated)"
}
```

#### 示例

```ts
// Example demonstrating catching a network-related client error
try {
  const address = await API.addresses('totallyValidAddress');
} catch (error) {
  if (error instanceof Blockfrost.BlockfrostClientError) {
    console.log('Oops, error during sending the request');
  }
  // Depending on your use case you may want to rethrow the error
  throw error;
}
```

## 实例

更多例子请查看 [块冻-js-实例](https://github.com/blockfrost/blockfrost-js-examples) 仓库.

所有 SDK 方法列表 [看看我们的维基](https://github.com/blockfrost/blockfrost-js/wiki/Exports)。 。 。 .

### 卡多诺

```typescript
const Blockfrost = require('@blockfrost/blockfrost-js');
// import { BlockFrostAPI } from '@blockfrost/blockfrost-js'; // using import syntax

const API = new Blockfrost.BlockFrostAPI({
  projectId: 'YOUR API KEY HERE', // see: https://blockfrost.io
});

async function runExample() {
  try {
    const latestBlock = await API.blocksLatest();
    const networkInfo = await API.network();
    const latestEpoch = await API.epochsLatest();
    const health = await API.health();
    const address = await API.addresses(
      'addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz',
    );
    const pools = await API.pools({ page: 1, count: 10, order: 'asc' });

    console.log('pools', pools);
    console.log('address', address);
    console.log('networkInfo', networkInfo);
    console.log('latestEpoch', latestEpoch);
    console.log('latestBlock', latestBlock);
    console.log('health', health);
  } catch (err) {
    console.log('error', err);
  }
}

runExample();
```

### 森林小组

```typescript
const Blockfrost = require('@blockfrost/blockfrost-js');
// import { BlockFrostIPFS } from '@blockfrost/blockfrost-js'; // using import syntax

const IPFS = new Blockfrost.BlockFrostIPFS({
  projectId: 'YOUR IPFS KEY HERE', // see: https://blockfrost.io
});

async function runExample() {
  try {
    const added = await IPFS.add(`${__dirname}/img.svg`);
    console.log('added', added);

    const pinned = await IPFS.pin(added.ipfs_hash);
    console.log('pinned', pinned);
  } catch (err) {
    console.log('error', err);
  }
}

runExample();
```

## 工具函数

Blockfrost SDK输出了几种功能来改进开发者的经验.

-   [生成地址](https://github.com/blockfrost/blockfrost-js/wiki/Exports#deriveaddress)
-   [获取指纹](https://github.com/blockfrost/blockfrost-js/wiki/Exports#getfingerprint)
-   [剖析设置](https://github.com/blockfrost/blockfrost-js/wiki/Exports#parseasset)
-   [校验Webhook 签名](https://github.com/blockfrost/blockfrost-js/wiki/Exports#verifywebhooksignature)

## 发展

### 添加新方法

1.  在相应的文件中添加代码 。 例如,新账户方法属于 `src/endpoints/api/account/` 目录.
    -   添加 `<method>All` 带有页点的终点方法
    -   更新 [信息技术事务司](https://tsdoc.org/) 用于添加方法
2.  添加类方法到 `BlockfrostAPI` 对象在 [src/ BlockFrostAPI.ts 互联网档案馆的存檔,存档日期2013-12-02](https://npmcn.com/package/%40blockfrost/blockfrost-js/src/BlockFrostAPI.ts)。 。 。 .
3.  为添加的方法添加单位测试固定器 [测试/固定/端点](https://npmcn.com/package/%40blockfrost/blockfrost-js/test/fixtures/endpoints.ts)
4.  重生维基文件
    -   `yarn docs`
    -   将文件推到 Wiki 仓库 `https://github.com/blockfrost/blockfrost-js.wiki.git`

## 常见问题

### @blockfrost/blockfrost-js 是什么？

用于交互的 JavaScript/ TypeScript SDK https://blockfrost\.io \(英语\) API 密码

### 如何安装 @blockfrost/blockfrost-js？

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

### @blockfrost/blockfrost-js 支持 TypeScript 吗？

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

### @blockfrost/blockfrost-js 支持 ESM 还是 CommonJS？

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

### @blockfrost/blockfrost-js 需要什么版本的 Node\.js？

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

### @blockfrost/blockfrost-js 可以商用吗？

@blockfrost/blockfrost-js 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @blockfrost/blockfrost-js 的下载量有多少？

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

### @blockfrost/blockfrost-js 还在维护吗？

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