# @easypost/api 中文文档

规范地址：https://npmcn.com/package/%40easypost/api/

版本：9\.2\.0
npm 元数据更新时间：2026-11-09T17:59:43.280Z
中文译文更新时间：2026-11-13T04:13:08.288Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：553 kB，195 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18\.0
- 运行依赖：1 个
- 首次发布：2017-04-25T20:59:35.048Z
- 最新版本发布：2026-11-09T17:59:42.890Z
- 近 30 天下载量：404379（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：98（近 12 个月 10 个）

## 中文简介

EasyPost 节点客户端库

## 安装

```sh
npm install @easypost/api
```

也可以使用：`pnpm add @easypost/api`、`yarn add @easypost/api`、`bun add @easypost/api`

## README

# EasyPost 节点客户端库

[![CI](https://github.com/EasyPost/easypost-node/workflows/CI/badge.svg)](https://github.com/EasyPost/easypost-node/actions?query=workflow%3ACI) [![codecov](https://codecov.io/gh/EasyPost/easypost-node/graph/badge.svg?token=RhFfmXPeDW)](https://codecov.io/gh/EasyPost/easypost-node) [![npm version](https://badge.fury.io/js/%40easypost%2Fapi.svg)](https://badge.fury.io/js/%40easypost%2Fapi)

EasyPost,简单的航运解决方案. 你可以注册一个账户在 [https://easypost.com (中文(中国大陆) )](https://easypost.com/)。 。 。 .

注: 这个库意在用于后端节点服务,而不是通过浏览器用于前端的Javascript项目.

## 安装

```bash
npm install --save @easypost/api
```

您可以从此项目下载各种已建资产 [页 次](https://github.com/EasyPost/easypost-node/releases)。 。 。 .

## 使用量

简单创建并购买运出实例( B) :

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient(process.env.EASYPOST_API_KEY);

const shipment = await client.Shipment.create({
  from_address: {
    street1: '417 MONTGOMERY ST',
    street2: 'FLOOR 5',
    city: 'SAN FRANCISCO',
    state: 'CA',
    zip: '94104',
    country: 'US',
    company: 'EasyPost',
    phone: '415-123-4567',
  },
  to_address: {
    name: 'Dr. Steve Brule',
    street1: '179 N Harbor Dr',
    city: 'Redondo Beach',
    state: 'CA',
    zip: '90277',
    country: 'US',
    phone: '4155559999',
  },
  parcel: {
    length: 8,
    width: 5,
    height: 5,
    weight: 5,
  },
});

const boughtShipment = await client.Shipment.buy(shipment.id, shipment.lowestRate());

console.log(boughtShipment);
```

### 选项

您可以构造一个 API 实例, 并附带某些选项 :

```javascript
const client = new EasyPostClient(process.env.EASYPOST_API_KEY, {
  timeout: 120000,
  baseUrl: 'https://api.easypost.com/v2/',
  useProxy: false,
  httpMiddleware: (f) => f,
  httpClient: fetch,
  requestMiddleware: (r) => r,
});
```

#### 超时

以毫秒计, 请求失败 .

#### 基数Url

更改 API 库使用的基础 URL 。 代理请求时有用 从前端通过服务器.

#### 使用 Proxy

禁用 API 密钥 。 如果您代理端请求通过前端, 则有用 一个服务器.

#### httpMiddle 软件

将 HTTP 传输功能包起来的函数 .

```javascript
const wrapFetch = (f) => (input, init) => {
  // custom behavior here
  return f(input, init);
};

const client = new EasyPostClient('my-key', {
  httpMiddleware: wrapFetch,
});
```

#### httpclient 语句

HTTP 请求所用的函数 。 内置默认值 `fetch` (节点18+). 您可以在自定义环境、 测试或仪表上覆盖 .

#### 请求中间软件

需要兼容请求对象并返回的函数 。 现有 使用中间软件模式 `auth`, (中文(简体) ), `query`,以及 `send` 仍然被支持.

```javascript
const client = new EasyPostClient('my-key', {
  requestMiddleware: (r) => {
    r.set({ 'X-Custom-Header': 'my-value' });
    return r;
  },
});
```

### HTTP 钩子

如果您需要或想要查看EasyPost API在幕后提出的请求,您可以提供功能来倾听请求和/或回应. 可以在创建客户端的辅助功能中做到这一点.

```javascript
const client = new EasyPostClient('my-key');

const logOutgoingRequest = (request) => console.log('Outgoing:', request);
const logResponse = (response) => console.log('Response:', response);

// optionally add your hook to listen for outgoing requests
client.addRequestHook(logOutgoingRequest);
// and optionally the hook for the response
client.addResponseHook(logResponse);

// ...do other stuff

// remove that request hook
client.removeRequestHook(logOutgoingRequest);
// and the response one
client.removeResponseHook(logResponse);
// or clear all the hooks at once
client.clearRequestHooks();
client.clearResponseHooks();
```

**说明:** 您无法使用这些钩子编辑或以其他方式影响请求 。 它们纯粹是为了调试或伐木目的.

## 文档

API 文档可见于: [https://docs.easypost.com (中文(简体) )](https://docs.easypost.com/)。 。 。 .

图书馆文件可上网查阅: [https://easypost.github.io/easypost-node/ 页面存档备份,存于互联网档案馆](https://easypost.github.io/easypost-node/) 或通过当地建造 `just docs` 命令.

更新这个项目的主要版本? 参见 [升级指南](https://npmcn.com/package/%40easypost/api/UPGRADE_GUIDE.md)。 。 。 .

## 支助

新的特性和错误修正在本库最新的主要发行上发布. 如果您是这个库的旧主版, 我们建议升级到最近的版, 利用新的功能、错误修正和安全补丁。 这个图书馆的旧版本将继续工作,只要它们与API版本捆绑在一起,就可以提供;不过,它们不会收到更新,被认为是EOL.

额外的支持,见我们 [整体支助政策](https://github.com/EasyPost/.github/blob/main/SUPPORT.md)。 。 。 .

## 发展

```bash
# Install dependencies
just install

# Install style guides (Unix only)
just install-styleguide

# Update dependencies
just update

# Build the project
just build

# Lint the project
just lint
just lint-fix

# Run tests (these will be transpiled on the fly)
EASYPOST_TEST_API_KEY=123... EASYPOST_PROD_API_KEY=123... just test
EASYPOST_TEST_API_KEY=123... EASYPOST_PROD_API_KEY=123... just coverage

# Run security analysis
just scan

# Generate library documentation
just docs

# Update submodules
just update-examples-submodule
```

### 字体定义

从开始 `v5.3.0`,此项目包含 Typescript 定义.

当前的定义来自源代码,并与软件包一起发布于 `dist/types`。 。 。 . 导入时不需要更改消费者配置 `@easypost/api` 从包根.

#### 字体排除

-   我们目前没有提供这些定义的绝对Typed版本
-   预定义软件包( 见 [载体元数据](https://docs.easypost.com/docs/carrier-metadata) 详细情况请见我们的文件)
-   承运人服务水平(见 [载体元数据](https://docs.easypost.com/docs/carrier-metadata) 详细情况请见我们的文件)
-   承运人名单(见 [载体类型](https://docs.easypost.com/docs/carrier-types) 详细情况请见我们的文件)
-   我们不需要在这个库中全面使用参数或属性. 详情见我们的文件,说明每项要求需要什么

### 测试

这个项目中的测试套房是专门为在每次运行中产生一致的结果而建造的,无论它们何时运行或由谁运行. 这个项目使用 [波利兹](https://github.com/Netflix/pollyjs) (AKA:VCR)通过"盒"来记录并重放HTTP请求和回应. 当套件运行时,每个测试函数的HTTP请求和回复如果不存在,将会被保存到磁带中,如果已经存在,则会从这个被保存的文件重放,这样可以节省每次测试运行时进行活API调用的需要. 如果收到关于磁带过期的错误,则删除并重新记录磁带,以确保数据是最新的.

**敏感数据 :** 我们在录制磁带时, 尽量加入洗涤器 以获取敏感数据 以免PII或敏感信息 持续控制版本; 然而,请确保在录制或重新录制磁带时, 在您进行修改之前, 没有PII或敏感信息 通过检查磁带来维持.

**进行修改 :** 如果您添加了此工程, 请求/ 答复会自动为您录制 。 在修改此工程时, 您需要重新录制相关的磁带, 强制进行新的实时 API 调用测试, 然后记录下次运行时使用的请求/ 答复 .

**测试数据 :** 测试套间内装有各种可供使用的有用装置,每套都完全独立于某一特定用户 **除USPS载体账户ID外** (见 [单位测试 API 密钥](https://npmcn.com/package/%40easypost/api/#readme-unit-test-api-keys) ),它具有我们内部测试用户ID的倒数值. 一些固定装置使用硬编码日期,如果磁带被重新录入,可能需要加码(如报告或取出).

#### 单位测试 API 密钥

每次测试都需要以下内容:

-   `EASYPOST_TEST_API_KEY`
-   `EASYPOST_PROD_API_KEY`

一些测试可能需要一个具有特定一组功能的 EasyPost 用户,例如 `Partner` 用户在创建推荐时。 我们曾试图在各自的指令中提及这些职能。 在需要重新录制用于适用测试的磁带时,需要提供下列资料:

-   `USPS_CARRIER_ACCOUNT_ID` (例如:为非EasyPost雇员购买一通电话)
-   `PARTNER_USER_PROD_API_KEY` (例如:创建推荐用户)
-   `REFERRAL_CUSTOMER_PROD_API_KEY` (例如:向查询用户添加信用卡)

## 常见问题

### @easypost/api 是什么？

EasyPost 节点客户端库

### 如何安装 @easypost/api？

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

### @easypost/api 支持 TypeScript 吗？

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

### @easypost/api 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @easypost/api 需要什么版本的 Node\.js？

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

### @easypost/api 可以商用吗？

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

### @easypost/api 的下载量有多少？

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

### @easypost/api 还在维护吗？

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