# @aptos-labs/aptos-client 中文文档

规范地址：https://npmcn.com/package/%40aptos-labs/aptos-client/

版本：4\.1\.0
npm 元数据更新时间：2026-05-20T19:22:16.220Z
中文译文更新时间：2026-11-06T13:00:29.153Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aptos-labs/aptos-client
原文对照：https://npmcn.com/package/%40aptos-labs/aptos-client/?lang=original
项目主页：https://github.com/aptos-labs/aptos-client
源码仓库：https://github.com/aptos-labs/aptos-client

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

- 包体积（解压后）：117 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：1 个
- 首次发布：2023-07-14T01:53:57.950Z
- 最新版本发布：2026-05-20T19:03:32.750Z
- 近 30 天下载量：752287（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 7 个）

## 中文简介

访问 Aptos 网络 API 的客户端软件包 .

## 安装

```sh
npm install @aptos-labs/aptos-client
```

也可以使用：`pnpm add @aptos-labs/aptos-client`、`yarn add @aptos-labs/aptos-client`、`bun add @aptos-labs/aptos-client`

## README

![License](https://img.shields.io/github/license/aptos-labs/aptos-client) [![NPM Package Version](https://img.shields.io/npm/v/%40aptos-labs%2Faptos-client.svg)](https://npmjs.org/package/@aptos-labs/aptos-client) ![Node Version](https://img.shields.io/node/v/%40aptos-labs%2Faptos-client) ![NPM bundle size](https://img.shields.io/bundlephobia/min/%40aptos-labs/aptos-client) [![NPM Package Downloads](https://img.shields.io/npm/dm/%40aptos-labs%2Faptos-client.svg)](https://npmjs.org/package/@aptos-labs/aptos-client) [![codecov](https://codecov.io/gh/aptos-labs/aptos-client/branch/main/graph/badge.svg)](https://codecov.io/gh/aptos-labs/aptos-client)

# @aptos-labs/aptos-客户端

Aptos 网络 API 的 HTTP 客户端. 单独工作或作为运输层 [Aptos 类型脚本 SDK](https://github.com/aptos-labs/aptos-ts-sdk)。 。 。 .

## 特征

-   **HTTP/2 导弹** ——默认在所有平台启用
-   **多运行时间** — Node.js, Deno, Bun, 浏览器, 以及 React Introduct
-   **饼干罐** 在节点、德诺和邦自动处理饼干
-   **业连支助** —— 说 `bcsRequest()` 返回原始内容 `ArrayBuffer` 二进制编码回复

## 安装

```bash
npm install @aptos-labs/aptos-client
# or
pnpm add @aptos-labs/aptos-client
```

## 使用量

```ts
import aptosClient from "@aptos-labs/aptos-client";

const { status, data } = await aptosClient<{ chain_id: number }>({
  url: "https://fullnode.mainnet.aptoslabs.com/v1",
  method: "GET",
});
```

### 已命名的出口

```ts
import { jsonRequest, bcsRequest } from "@aptos-labs/aptos-client";

// JSON (same as default export)
const json = await jsonRequest<MyType>({ url, method: "GET" });

// BCS (returns ArrayBuffer)
const bcs = await bcsRequest({ url, method: "GET" });
```

## 运行时间解析

软件包使用 [有条件出口](https://nodejs.org/api/packages.html#conditional-exports) 为每次运行时间选择正确的执行 :

| 条件 | 入境点 | HTTP/2 导弹 | 页:1 |
| --- | --- | --- | --- |
| `node` | `index.node.ts` | 可配置通过 `http2` 选项(默认) `true`(中文(简体) ) | 用途 [已经](https://github.com/sindresorhus/got) (代码) `br`编号 :`gzip`编号 :`deflate` h1和H2透明 |
| `browser` | `index.browser.ts` | 自动( 浏览器引擎) | 向浏览器代表 cookie |
| `react-native` | `index.fetch.ts` | 自动( OkHttp / NSURL 会话) | 平台通过 ALPN 谈判 HTTP/2 |
| `deno` | `index.fetch.ts` | 自动 | —— 说 |
| `bun` | `index.fetch.ts` | 自动 | —— 说 |
| `workerd` | `index.fetch.ts` | 自动 | 云花岗工人 |
| `edge-light` | `index.fetch.ts` | 自动 | Vercel边缘函数 |
| `default` | `index.fetch.ts` | 取决于运行时间 | 未知运行时间的倒计时 |

## 类型

```ts
type AptosClientRequest = {
  url: string;
  method: "GET" | "POST";
  body?: unknown;
  params?: Record<string, string | number | bigint | boolean | undefined>;
  headers?: Record<string, string | undefined>;
  overrides?: { WITH_CREDENTIALS?: boolean };
  http2?: boolean;    // Node only — ignored elsewhere
  cookieJar?: CookieJarLike; // Per-request cookie isolation (Node & fetch only)
};

type AptosClientResponse<Res> = {
  status: number;
  statusText: string;
  data: Res;
  config?: any;
  request?: any;
  response?: any;
  headers?: Record<string, string | string[]>;
};
```

> 见 [`src/types.ts`](https://npmcn.com/package/%40aptos-labs/aptos-client/src/types.ts) 用于带有文档的完整类型定义.

## HTTP/2 导弹

| 运行时间 | 如何运作 |
| --- | --- |
| **节点.js** | `got` 通过ALPN(由 `http2-wrapper`当 `http2: true` (默认). 设定 `http2: false` 以强制使用 HTTP/1.1. |
| **浏览器** | 浏览器引擎与服务器自动谈判HTTP/2. 这个 `http2` 选项被忽略. |
| **原生反应** | OkHttp(Android)和NSURL Session(iOS)通过ALPN自动谈判HTTP/2. 这个 `http2` 选项被忽略. |
| **德诺/ 邦** | 运行时间自动谈判HTTP/2. 这个 `http2` 选项被忽略. |

## 从v2 移动

v4.1.0 返回相同的 HTTP 库 v2 (`got`),同时保留v4架构(ESM,有条件的出口,多运行时间). 对于大多数呼叫者来说,迁移是一两个小编辑.

> **如果你在v3.0.0到v4.0.0,升级.** 这些版本静悄悄地返回原始压缩字节,而不是当来源发送时解析 JSON `content-encoding: br`编号 :`gzip`编号 :`deflate` ——这是Aptos fullnode和索引器的工作. 4.1.0 恢复v2-era减压行为.

### 和v2一样有效

-   `http2: true` 默认; 当服务器不支持 H2 时倒回 H1.1 .
-   Brotli / gzip / deflate 解压处理透明.
-   饼干罐子回转 `set-cookie` 并且根据同源请求重新发送饼干.
-   `bigint` 查询参数为字符串.
-   4xx / 5xx 答复有 **没有** 投掷-检查 `res.status`。 。 。 .
-   `AptosClientResponse` 形状 : `{ status, statusText, data, config, request, response, headers }` 与 `headers` 作为一个平地 `Record<string, string | string[]>`。 。 。 .

### 行为改变( 呼叫者可观察)

| 变动 | 页:1 | 页:1 |
| --- | --- | --- |
| **BCS 响应类型** | `Buffer` | `ArrayBuffer` - 交叉运行时间,不 `Buffer` 需要多填充剂。 字节相同; 使用 `new Uint8Array(res.data)` 或者说 `Buffer.from(res.data)` 如果你需要任何形状. |
| **检索** | 获得默认( e)`limit: 2`, 备份) | **关闭** (单位:千美元)`limit: 0`) (中文(简体) ). 在您自己的重试回环中环绕, 或者让 Aptos TS SDK 在更高层管理重试 . |
| **非JSON机构** | `JSON.parse` 会抛出 | 返回原始文本输入 `data` ——让呼叫者检查状态代码,无论身体内容类型如何. |
| **空 / 204/ 205具尸体** | 不论得到什么回报(往往) `""` 或者说 `undefined`(中文(简体) ) | 明确 `null`。 。 。 . |
| **`statusText` 超过 HTTP/2** | 空字符串( H2 没有理由短语) | 倒计时 `http.STATUS_CODES[code]` —— 说 `"OK"`, (中文(简体) ), `"Not Found"`等 (中文(简体) ). |
| **`NODE_TLS_REJECT_UNAUTHORIZED=0` 关于H2** | 过渡性继承(意外工作) | 明确传播到获得 `https.rejectUnauthorized` ——同时在H1和H2上工作. |

### V2以来的新能力

-   **按要求的饼干罐隔离** - 通过 `cookieJar: new CookieJar()` 以保留共享饼干状态的多租户请求.
-   **公开 `CookieJar`** 现在出口(有RFC 6265验证、过期驱逐、人均原产地盖和SameSite=None+Secure执行).
-   **`CookieJarLike` 接口** ——自带罐子(如:硬饼干或数据库后置商店等).
-   **有条件出口** 自动选择 Node / 浏览器 / Deno / Bun / Cloudflare Workers / Vercel Edge / React Introduct. v2 仅运出 Node + 浏览器的右条目.
-   **`overrides.WITH_CREDENTIALS`** (浏览器条目)地图到 `fetch`是因为 `credentials: "omit" | "include"`。 。 。 .

### 自 v2 起删除

-   **司法理事会 `require()`** ——自v 4.0起,该包只采用无害环境管理. 使用 `import` 或者说 `await import(...)`。 。 。 .
-   **获取错误类型的再导出** - 如果你处理 `RequestError` 编号 : `HTTPError` 直接导入 `got` (仍然是直接依赖).
-   **节点 < 22** ——最低支持的节点版本为22.

### 移徙清单

1.  **使用 `require()`? 吗?** 切换到 `import` (或 `await import()` 从CJS).
2.  **通话 `Buffer` 关于BCS响应的方法?** • 使用 `new Uint8Array(res.data)`, (中文(简体) ), `new DataView(res.data)`,或用 `Buffer.from(res.data)`。 。 。 .
3.  **依靠自动回击?** + 添加一个明确的重试包装。 (大多数消费者——包括Aptos TS SDK——不需要. )
4.  **节点版本 < 22?** • 升级.

这就是完整的迁移。 其它东西要么是相同的,要么是添加剂,要么是固定的虫子.

## 发布新版本

当创建了 GitHub 发布时, 发布会自动通过 GitHub Actions 发布到 npm 。 工作流程存在于 `.github/workflows/publish.yml`。 。 。 .

要发布新版本 :

1.  **更新版本** 内 `package.json` (以下为) [铸造](https://semver.org/):
    
    ```bash
    npm version <major|minor|patch> --no-git-tag-version
    ```
    
2.  **更新 `CHANGELOG.md`** - 将任何注释移到下面 `# Unreleased` 输入一个新版,用于发布版本.
    
3.  **提交和推** 版本凸起和更改日志更新到 `main`数字 :
    
    ```bash
    git add package.json CHANGELOG.md
    git commit -m "v<VERSION>"
    git push
    ```
    
4.  **创建 GitHub 发布** 带有匹配的标签 `vMAJOR.MINOR.PATCH` (例如:. `v2.3.0`) (中文(简体) ). 标签 **必须** 匹配当前版本 `package.json` ——发布工作流程否则会失败. 释放前标签 `v2.3.0-beta.1` 也得到支持.
    

然后发布工作流程会自动:

-   验证标签是否匹配预期 `vMAJOR.MINOR.PATCH[-prerelease]` 模式.
-   验证标签是否匹配 `version` 输入 `package.json`。 。 。 .
-   安装依赖关系、构建软件包并发布到 npm [来源](https://docs.npmjs.com/generating-provenance-statements)。 。 。 .

## 常见问题

### @aptos-labs/aptos-client 是什么？

访问 Aptos 网络 API 的客户端软件包 \.

### 如何安装 @aptos-labs/aptos-client？

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

### @aptos-labs/aptos-client 支持 TypeScript 吗？

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

### @aptos-labs/aptos-client 支持 ESM 还是 CommonJS？

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

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

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

### @aptos-labs/aptos-client 可以商用吗？

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

### @aptos-labs/aptos-client 的下载量有多少？

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

### @aptos-labs/aptos-client 还在维护吗？

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