# @contentstack/delivery-sdk 中文文档

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

版本：5\.6\.2
npm 元数据更新时间：2026-11-02T09:36:10.979Z
中文译文更新时间：2026-11-10T16:43:55.068Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.5 MB，265 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：4 个
- 首次发布：2024-01-25T08:02:05.685Z
- 最新版本发布：2026-11-02T09:36:10.592Z
- 近 30 天下载量：149120（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 24 个）

## 中文简介

[![Contentstack](https://www.contentstack.com/docs/static/images/contentstack.png)](https://www.contentstack.com/) □ 目录内容交付SDK

## 安装

```sh
npm install @contentstack/delivery-sdk
```

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

## README

[![Contentstack](https://www.contentstack.com/docs/static/images/contentstack.png)](https://www.contentstack.com/)

## 内容存储的打字符内容交付SDK

内容tack是一种无头的CMS,采用API-First方法. 这是一个CMS,开发者可以用来用他们最喜爱的语言来构建强大的跨平台应用程序. 构建您的应用程序前端, 而Contack 将照顾其余的 . [更多信息](https://www.contentstack.com/)。 。 。 .

内容tack提供Typescript SDK来构建Typescript上方的应用程序. 下面是详细的指南和有用的资源 开始我们的SDK字体.

Typescript SDK也可以用于创建Node.js和React本土应用程序.

### 先决条件

要使用Contentack TypeScript SDK,需要Node.js版本18或后期安装.

### 设置和安装

Node.js使用Typescript SDK来创建应用程序. 要使用 Typescript SDK, 请通过 npm 安装它 :

```bash
npm i @contentstack/delivery-sdk
```

要在您的工程中导入 SDK, 请使用以下命令 :

```typescript
import contentstack from '@contentstack/delivery-sdk'
```

要初始化 SDK, 您需要指定您的堆栈的 API 密钥、 交付托肯 和环境名称 .

```typescript
    import contentstack from '@contentstack/delivery-sdk'
    const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });
```

### 使用 Contack 的关键概念

#### 堆栈

堆栈就像一个容器 保存您的应用程序的内容。 学习更多关于 [堆栈](https://www.contentstack.com/docs/guide/stack)。 。 。 .

#### 内容类型

内容类型允许您定义页面或您数字属性的一节的结构或蓝图。 这是一个类似窗体的页面,为内容管理员提供输入和上传内容的界面. [更多信息](https://www.contentstack.com/docs/guide/content-types)。 。 。 .

#### 条目

条目是使用定义的内容类型之一创建的实际内容块. 学习更多关于 [条目](https://www.contentstack.com/docs/guide/content-management#working-with-entries)。 。 。 .

#### 资产

资产指所有媒体文件(图像,视频,PDF,音频文件等)上传到Contaltack. 这些文件可用于多个条目. 更多信息 [资产](https://www.contentstack.com/docs/guide/content-management#working-with-assets)。 。 。 .

#### 环境

出版环境对应一个或多个部署服务器,或需要发布条目的内容发送目的地. 学会如何工作 [环境](https://www.contentstack.com/docs/guide/environments)。 。 。 .

### 内容夹打字机 SDK

#### 初始化您的 SDK

您需要指定您的堆栈的 API 密钥、 交付托肯 和环境名称来初始化 SDK :

```typescript
    const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });
```

SDK初始化后,可以开始在应用中获取内容.

#### 区域和主机配置

SDK支持区域和自定义主机配置,以连接到不同的Contentack数据中心或自定义端点.

**地区支助**

您可以指定一个区域来连接到相应的Contack数据中心. 现有区域有:

-   `US` (默认) - 用途 `cdn.contentstack.io`
-   `EU` - 用途 `eu-cdn.contentstack.com`
-   `AU` - 用途 `au-cdn.contentstack.com`
-   `AZURE_NA` - 用途 `azure-na-cdn.contentstack.com`
-   `AZURE_EU` - 用途 `azure-eu-cdn.contentstack.com`
-   `GCP_NA` - 用途 `gcp-na-cdn.contentstack.com`
-   `GCP_EU` - 用途 `gcp-eu-cdn.contentstack.com`

```typescript
import contentstack, { Region } from '@contentstack/delivery-sdk'

// Using region enum
const stack = contentstack.stack({
  apiKey: "apiKey",
  deliveryToken: "deliveryToken",
  environment: "environment",
  region: Region.EU
});

// Using region string
const stack = contentstack.stack({
  apiKey: "apiKey",
  deliveryToken: "deliveryToken",
  environment: "environment",
  region: "eu"
});
```

**自定义主机支持**

您可以指定一个自定义主机连接到自定义端点 。 如果提供自定义主机,则优先于基于区域的主机.

```typescript
const stack = contentstack.stack({
  apiKey: "apiKey",
  deliveryToken: "deliveryToken",
  environment: "environment",
  host: "custom-cdn.example.com"
});

// Custom host with region (host takes priority)
const stack = contentstack.stack({
  apiKey: "apiKey",
  deliveryToken: "deliveryToken",
  environment: "environment",
  region: Region.EU,
  host: "custom-cdn.example.com"
});
```

#### 从您的堆栈查询内容

要获得单个条目,需要指定条目的内容类型和ID.

```typescript
import { BaseEntry } from '@contentstack/delivery-sdk'
interface BlogPostEntry extends BaseEntry {
  // custom entry types
}
const result = await stack
                      .contentType(contentType_uid)
                      .entry(entry_uid)
                      .fetch<BlogPostEntry>();
```

要检索内容类型的多个条目,需要指定内容类型uid. 也可以指定搜索参数来过滤结果.

```typescript
import { BaseEntry, FindEntry } from '@contentstack/delivery-sdk'
interface BlogPostEntry extends BaseEntry {
  // custom entry types
}
const result = await stack.contentType("contentType1Uid").entry()
                    .query()
                    .find<BlogPostEntry>()
```

### 高级查询

您可以查询内容类型、 条目、 资产, 并使用我们的 Typescript API 引用 .

[Typescription API 参考文件](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/typescript/reference#contentstack)

### 图像工作

我们引入了图像传送 API , 允许您获取图像, 然后为您的数字属性操纵和优化图像 。 它允许您执行一系列其他动作,例如收成,修剪,调整大小,旋转,重叠等.

例如,如果想要裁剪一个图像(宽度为300,高为400),则只需要在图像 URL 的末尾附加查询参数,例如, [https://images.contentstack.io/owl.jpg?crop=300 (英语)](https://images.contentstack.io/owl.jpg?crop=300)400块。 还有几种参数可供您用于您的图像.

[读取图像传送 API 文档](https://www.contentstack.com/docs/developers/apis/image-delivery-api/)。 。 。 .

下面是图像传送 API 示例 .

```typescript
const url = 'www.example.com';
const transformObj = new imageTransform().bgColor('cccccc');
const transformURL = url.transform(transformObj);
```

### 倾斜

如果初始同步(或后继同步)的结果包含超过100个记录,则响应会被相接. 它在回应中提供了发号施令符. 您需要使用此标志来获取下一批数据 .

```typescript
const query = stack.contentType("contentTypeUid").entry().query();
const pagedResult = await query
                            .paginate()
                            .find<BlogPostEntry>(); 
// OR
const pagedResult = await query
                            .paginate({ skip: 20, limit: 20 })
                            .find<BlogPostEntry>();

```

### 缓存

使用缓存策略( E)`CACHE_THEN_NETWORK`, (中文(简体) ), `CACHE_ELSE_NETWORK`, (中文(简体) ), `NETWORK_ELSE_CACHE`),您必须通过 `cacheOptions.persistenceStore`。安装可选的持久性插件,并通过一个 `PersistenceStore` 实例:

```bash
npm install @contentstack/persistence-plugin
```

```typescript
import contentstack, { Policy } from '@contentstack/delivery-sdk';
import { PersistenceStore } from '@contentstack/persistence-plugin';

const stack = contentstack.stack({
  apiKey: 'your-api-key',
  deliveryToken: 'your-delivery-token',
  environment: 'your-environment',
  cacheOptions: {
    policy: Policy.CACHE_THEN_NETWORK,
    persistenceStore: new PersistenceStore({ storeType: 'localStorage', maxAge: 86400000 }),
  },
});
```

见 [@ contentstack/ 持久性插件](https://www.npmjs.com/package/@contentstack/persistence-plugin) 选项`storeType`, (中文(简体) ), `maxAge`,自定义存储).

### 发展

提供或运行寄存器的测试时, 运行 `npm run build` 在测试之前。 已发布的软件包包括一个预建 `dist/` 目录.

### 帮助链接

-   [链接网站](https://www.contentstack.com/)
-   [正式文件](https://contentstack.com/docs)
-   [内容交付 API Docs](https://contentstack.com/docs/apis/content-delivery-api/)

### 《麻省理工学院许可证》

版权:"2012-2026" [目录](https://www.contentstack.com/)保留的所有权利d

特此准许任何人免费获得本软件和相关文件文件("软件")的副本,不受限制地在软件中进行交易,包括不受限制地享有软件的使用、复制、修改、合并、出版、分发、分版和(或)销售的权利,并允许软件获得者这样做,但须符合下列条件: 1

上述版权通知和许可通知应载入软件的所有副本或大部分.

软件是提供的"AS IS", 没有任何种类的恐惧, 释放或被卷入, 包括但不限制在 危机的保障, 证明一个特定的目的和无关。 任何索赔、索赔或其他负债,无论是合同、交易或其他行为,产生于、产生于或涉及软件或软件的使用或其他交易的行为,都不得作为担保.

## 常见问题

### @contentstack/delivery-sdk 是什么？

□ 目录内容交付SDK

### 如何安装 @contentstack/delivery-sdk？

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

### @contentstack/delivery-sdk 支持 TypeScript 吗？

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

### @contentstack/delivery-sdk 支持 ESM 还是 CommonJS？

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

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

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

### @contentstack/delivery-sdk 可以商用吗？

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

### @contentstack/delivery-sdk 的下载量有多少？

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

### @contentstack/delivery-sdk 还在维护吗？

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