# @elasticpath/js-sdk 中文文档

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

版本：36\.1\.0
npm 元数据更新时间：2026-10-26T17:18:22.980Z
中文译文更新时间：2026-11-13T23:54:35.732Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1 MB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2024-07-16T12:47:47.504Z
- 最新版本发布：2026-10-26T17:18:22.564Z
- 近 30 天下载量：2819（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：85（近 12 个月 32 个）

## 中文简介

弹性路径 eCommerce API 的 SDK

## 安装

```sh
npm install @elasticpath/js-sdk
```

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

## README

![](https://www.elasticpath.com/themes/custom/bootstrap_sass/logo.svg)

# 弹性路径商业 Cloud JavaScript SDK

[![npm version](https://img.shields.io/npm/v/@elasticpath/js-sdk.svg)](https://www.npmjs.com/package/@elasticpath/js-sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/elasticpath/js-sdk/issues) [![follow on Twitter](https://img.shields.io/twitter/follow/elasticpath?style=social&logo=twitter)](https://twitter.com/intent/follow?screen_name=elasticpath)

> \[大  
> 此寄存器已经从 [@ moltin/ sdk (英语)](https://www.npmjs.com/package/@moltin/sdk)如果您是 Moltin SDK 的前用户,请阅读我们 [指南](https://npmcn.com/package/%40elasticpath/js-sdk/MIGRATION_GUIDE.md) 学习如何将您的执行迁移到这个代码库

一个简单的使用API接口来帮助您快速高效地从地上脱身,与您的"弹性路径"商业Cloud JavaScript应用程序相通.

📚 [API 参考](https://documentation.elasticpath.com/commerce-cloud/docs/developer/get-started/sdk.html#officially-supported-sdk) . . . . . [弹性路径商业云](https://www.elasticpath.com/)

## \* 安装

安装软件包从 [无](https://www.npmjs.com/package/@elasticpath/js-sdk) 并导入您的项目.

```bash
npm install --save @elasticpath/js-sdk
```

## 使用量

要启动, 请用您的商店证书即时处理一个新的 Elastic Path 客户端 .

> \[注\]  
> 这需要 [弹性路径商业云](https://www.elasticpath.com/) 账户。 你可以报名参加免费审判 [这里](https://cm.elasticpath.com/free-trial)

```js
// JavaScript
import { gateway as ElasticPathGateway } from '@elasticpath/js-sdk'

const ElasticPath = ElasticPathGateway({
  client_id: 'XXX'
})

// Node.js
const ElasticPathGateway = require('@elasticpath/js-sdk').gateway

const ElasticPath = ElasticPathGateway({
  client_id: 'XXX',
  client_secret: 'XXX'
})
```

或者您可以包括 `UMD` 通过捆绑 [联科办](https://unpkg.com/) 像这样:

```html
<script src="https://unpkg.com/@elasticpath/js-sdk"></script>

<script>
  const ElasticPath = elasticpath.gateway({
    client_id: 'XXX'
  });
</script>
```

> **说明:** 如果你在用的话 [网络软件包](https://webpack.github.io/),您需要在您的工程配置文件中添加以下内容 .

```js
node: {
  fs: 'empty'
}
```

您现在可以通过 ElasticPath 服务认证

```js
ElasticPath.Authenticate().then(response => {
  console.log('authenticated', response)
})
```

看看这个 [API 参考](https://elasticpath.dev/docs/commerce-cloud) 学习更多关于认证和可用终点的知识.

### 自定义主机

如果您是拥有自己基础设施的企业客户,您需要指定您的 API URL 当即时:

```js
const ElasticPath = ElasticPathGateway({
  client_id: 'XXX',
  host: 'api.yourdomain.com'
})
```

### 自定义存储

默认情况下, Elastic Path Commerce Cloud SDK 将数据持续到 `window.localStorage` 在浏览器和 `node-localstorage` 在节点。 如果这不适合您的需要, 您可以用一个 `MemoryStorageFactory` 将持续使用 JavaScript VM 的生命周期数据:

```js
import { gateway as ElasticPathGateway, MemoryStorageFactory } from '@elasticpath/js-sdk'

const ElasticPath = ElasticPathGateway({
  client_id: 'XXX',
  storage: new MemoryStorageFactory()
})
```

或者,通过通过一个执行下列接口的对象来创建自己的存储厂:

```js
interface StorageFactory {
  set(key: string, value: string): void;
  get(key: string): string | null;
  delete(key: string): void;
}
```

### 多个网关

您可以支持多个网关 `name` 属性在初始化网关时.

`name` 应当独有,以避免与同名的其他网关共享存储密钥.

```js
import { gateway as EPCCGateway } from "@elasticpath/js-sdk"

const gatewayOne = EPCCGateway({
    name: "my-first-gateway",
    client_id: 'XXX'
})

const gatewayTwo = EPCCGateway({
    name: "my-second-gateway",
    client_id: 'XXX'
})
```

用于存储解决方案的存储密钥被前缀所提供名称并用相关特性等结尾. `my-first-gateway_ep_cart`, (中文(简体) ), `my-first-gateway_ep_credentials` 财务报告和审定财务报表 `my-first-gateway_ep_currency`。 。 。 .

如果不向EPCCGateway函数提供名称属性,则保留遗留的命名: `mcart`, (中文(简体) ), `epCredentials` 财务报告和审定财务报表 `mcurrency`

### 包含标题

目前有几种可选标题可以传递到配置中,其中包括: `application`, (中文(简体) ), `language` 财务报告和审定财务报表 `currency`。 。 。 .

你可以把它们传到网关使用的配置中:

```TypeScript
// JavaScript
import { gateway as ElasticPathGateway } from '@elasticpath/js-sdk'
// const ElasticPathGateway = require('@elasticpath/js-sdk').gateway -> for Node

const ElasticPath = ElasticPathGateway({
    client_id: 'XXX',
    client_secret: 'XXX'
    currency: 'YEN',
    language: 'en',
    application: 'my-app'
})
```

### 检索

如果服务器响应状态为429 - "太多请求" SDK会等待一段时间并重试相同的API请求,最多可以重试一次. 您可以通过下列配置参数来调整这个逻辑 :

```TypeScript
const ElasticPath = ElasticPathGateway({
    client_id: 'XXX',
    client_secret: 'XXX',
    retryDelay: 1000,
    retryJitter: 500,
    fetchMaxAttempts: 4
})

```

如果有429个响应 SDK会等待 `retryDelay` 毫秒( 默认为 1000 秒) , 然后再尝试发出相同的呼叫 . 如果服务器再次响应429,它将等待2\* `retryDelay` ms,然后3 \* `retryDelay` 毫发等. 上面是零和零之间的随机值 `retryJitter` 每等一等,将增加(默认500). 这将重复到 `fetchMaxAttempts` (默认 4) 乘.

### 调压( 限制时间)

SDK 通过使用支持节流 `throttled-queue` 图书馆. 和流行图书馆的节流器不同, `throttled-queue` 不会阻止任何处决. 相反,每一次执行都被排入队列,排出队将按所期望的速率极限排出. 您可以通过下列参数控制节流 :

```TypeScript
const ElasticPath = ElasticPathGateway({
    client_id: 'XXX',
    client_secret: 'XXX',
    throttleEnabled: true,
    throttleLimit: 3,
    throttleInterval: 125
})

```

此功能默认已禁用, 并允许您需要设置 `throttleEnabled` 真实的. 启用后可以使用 `throttleLimit` (违约3)和 `throttleInterval` (default 125),用于定义每个间隔的最大呼叫次数. 例如设置 `throttleLimit = 5, throttleInterval = 1000` 表示每秒最多5通电话.

### 处理文件上传

文件可上传到 EPCC 文件服务 `ElasticPath.Files.Create` 方法。 你应该通过一个 `FormData` 对象,如 [文档](https://documentation.elasticpath.com/commerce-cloud/docs/api/advanced/files/create-a-file.html#post-create-a-file "documentation")。 。 。 .

在节点环境中,您可能正在使用替代品 `FormData` 中,您可以包含第二个参数来表示 `Content-Type` 请求头。 这一定是 `multipart/form-data` 并且必须包括 `boundary`。例如,使用 `form-data` [软件包](https://www.npmjs.com/package/form-data "package")数字 :

```TypeScript
const FormData = require('form-data')
const formData = new FormData()
formData.append('file', buffer)

const contentType = formData.getHeaders()['content-type']

ElasticPath.Files.Create(formData, contentType)
```

#### 引用存储在其他地方的文件

如果您想要简单创建文件 [参考资料](https://documentation.elasticpath.com/commerce-cloud/docs/api/advanced/files/create-a-file.html#post-create-a-file "referencing") 保存到其它地方的文件, 您可以使用此帮助方法 :

```TypeScript
ElasticPath.Files.Link('https://cdn.external-host.com/files/filename.png')
```

将 URL 传给 `Link` 方法和创造会为你处理.

### 类型脚本支持

弹性路径通商云JavaScript SDK在Typescript中得到充分支持.

被导入的模块将包含消费后端服务所需的所有接口. 即:

```TypeScript
import * as elasticpath from '@elasticpath/js-sdk';

const product: elasticpath.ProductBase = {...}
```

如果您不想使用命名空间,您可以扩展接口并自己定义它们,比如:

```TypeScript
// You can name the interface anything you like
interface Product extends product.ProductBase {
}

const product: Product = {...}
```

以下是简单产品创造的例子:

```TypeScript
import { ElasticPath, gateway, ProductBase, Resource } from '@elasticpath/js-sdk';

async function main() {
  const g: ElasticPath = gateway({client_id, client_secret});
  const auth = await g.Authenticate();

  const newProduct: ProductBase = {
    type: "product",
    name: "My Product",
    slug: "my-prod",
    sku: "my-prod",
    manage_stock: false,
    description: "Some description",
    status: "draft",
    commodity_type: "physical",
    price: [
      {
        amount: 5499,
        currency: "USD",
        includes_tax: true
      }
    ]
  };

  const nP: Resource<Product> = await g.Products.Create(newProduct);
}
```

您也可以扩展任何与流量相容的基础接口,以创建您可能通过重新声明而使用的自定义接口 `@elasticpath/js-sdk` 模块。 以下示例增加了几个属性 `ProductsBase` 对应于后端所添加的流量的界面.

在您的工程中添加定义文件( 有 `.d.ts` 扩展),代码如下:

```TypeScript
import * as elasticpath from '@elasticpath/js-sdk';

declare module '@elasticpath/js-sdk' {

  interface Weight {
    g: number;
    kg: number;
    lb: number;
    oz: number;
  }

  interface ProductBase {
    background_color: string;
    background_colour: string | null;
    bulb: string;
    bulb_qty: string;
    finish: string;
    material: string;
    max_watt: string;
    new: string | null;
    on_sale: string | null;
    weight: Weight;
  }

}
```

这将影响基础接口,在创建、更新、取取产品时,所有继承基础接口的所有其他产品接口都将存在.

## 捐款

我们爱社区的贡献。 这里有一个快速的向导,如果你想提交拉动请求:

1.  叉子存储器
2.  添加您更改的测试( 它会失败 )
3.  考试通过
4.  提交更改(见下文注)
5.  提交您的 PR 简略描述解释您的更改

> **说明:** 承诺应遵守 [角承诺公约](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#-git-commit-guidelines)。 。 。 .

确保你有 [高级](https://prettier.io/) 为您的编辑器安装, 启用 ESLint 集成.

## 发展

SDK是用 [ES6模块](https://strongloop.com/strongblog/an-introduction-to-javascript-es6-modules/) 使用 [滚动](http://rollupjs.org/)。 。 。 .

如果您想要滚动自己的捆绑, 或修改其中的任何模块 `src`,然后需要安装软件包的依赖性,并在观察变化时运行滚动.

```
npm install
npm start
```

运行测试

```
npm test
```

您可以更多地了解 Rollup API 和配置 [这里](https://github.com/rollup/rollup/wiki)。 。 。 .

## 术语 条件

-   这一项目的任何改动都必须由存储器所有人审查和批准.
-   关于执照的更多信息,请参见: [MIT 许可证](https://github.com/elasticpath/js-sdk/blob/main/LICENSE)。 。 。 .

## 常见问题

### @elasticpath/js-sdk 是什么？

弹性路径 eCommerce API 的 SDK

### 如何安装 @elasticpath/js-sdk？

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

### @elasticpath/js-sdk 支持 TypeScript 吗？

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

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

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

### @elasticpath/js-sdk 可以商用吗？

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

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

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

### @elasticpath/js-sdk 还在维护吗？

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