# @contentful/app-scripts 中文文档

规范地址：https://npmcn.com/package/%40contentful/app-scripts/

版本：4\.1\.16
npm 元数据更新时间：2026-10-26T15:22:06.264Z
中文译文更新时间：2026-11-10T16:36:45.856Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40contentful/app-scripts
原文对照：https://npmcn.com/package/%40contentful/app-scripts/?lang=original
项目主页：https://github.com/contentful/create-contentful-app#readme
源码仓库：https://github.com/contentful/create-contentful-app

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

- 包体积（解压后）：184 kB，128 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：19 个
- 首次发布：2021-04-08T07:54:24.650Z
- 最新版本发布：2026-10-26T15:22:05.737Z
- 近 30 天下载量：134223（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：570（近 12 个月 30 个）

## 中文简介

用于构建内容应用程序的脚本集

## 安装

```sh
npm install @contentful/app-scripts
```

也可以使用：`pnpm add @contentful/app-scripts`、`yarn add @contentful/app-scripts`、`bun add @contentful/app-scripts`

## README

# `@contentful/app-scripts`

该项目使得在下列地点开展一些经常性业务更为容易: [内容的 App 框架](https://www.contentful.com/developers/docs/extensibility/app-framework/)。 。 。 .

## \* 安装

当地:

```shell
npm i @contentful/app-scripts
```

全球:

```shell
npm i -g @contentful/app-scripts
```

## 使用量

### \*

安装时

```
$ contentful-app-scripts create-app-definition
```

否则

```
$ npx @contentful/app-scripts create-app-definition
```

### 程序化

```javascript
const { createAppDefinition } = require('@contentful/app-scripts');
const { myCustomLogic } = require('./my-custom-logic')(async function main() {
  myCustomLogic();

  await createAppDefinition.interactive();
})();
```

## • API

从此模块导出脚本将全部为以下形状

```typescript
interface Script<Result, Options> {
  // query the user or local cache for required information
  interactive: () => Result;
  // run by automation (`--ci` flag), they would need all the information upfront
  nonInteractive: (...options: Options) => Result;
}
```

> **: 警告:请注意**
> 
> 同一脚本的互动和非互动版本都是为了返回相同的结果.

### 生成函数

允许从我们创建新函数模板 [函数示例](https://github.com/contentful/apps/tree/master/function-examples)自动更新 `contentful-app-manifest.json` 并合并脚本/从 `package.json` 输入现有项目.

#### 互动模式 :

在交互模式下,CLI会询问所有所需的选项.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts generate-function
> ```

#### 非交互模式 :

当通过 `--ci` 参数,当所需的变量未设置为参数时,命令会失败.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts generate-function --ci \
>     --name <name> \
>     --example <example> \
>     --language <javascript/typescript> \
> ```

**选项 :**

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `--name` | 您函数的名称 . |  |
| `--example` | 我们所列举的例子名称 [函数示例](https://github.com/contentful/apps/tree/master/function-examples) |  |
| `--language` | Javascript或打字的选择 |  |

### 创建 App 定义

允许创建新的 [附录](https://www.contentful.com/developers/docs/extensibility/app-framework/app-definition/) 提供了内容管理 [这里](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/personal-access-tokens)) (中文(简体) ).

它只在交互模式下运行.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts create-app-definition
> ```

### 上传捆绑到 App 定义

允许您上传构建目录并创建绑定到一个 [附录](https://www.contentful.com/developers/docs/extensibility/app-framework/app-definition/)。 。 。 . 它以交互或非交互模式运行.

**说明:** 命令会自动激活捆绑. 为了跳过激活,你可以通过 `--skip-activation` 在交互和非交互模式下,然后手动进行参数 [激活](https://npmcn.com/package/%40contentful/app-scripts/#readme-activate-an-appBundle) 这个.

#### 互动模式 :

在交互模式下,CLI会询问所有所需的选项.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts upload
> ```

#### 非交互模式 :

当通过 `--ci` 参数,当所需的变量未设置为参数时,命令会失败.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts upload --ci \
>     --bundle-dir ./built \
>     --organization-id some-org-id \
>     --definition-id some-app-def-id \
>     --token $MY_CONTENTFUL_PAT
> ```

**选项 :**

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `--bundle-dir` | 您的构建文件夹目录( 例如 : `./build`(中文(简体) ) |  |
| `--organization-id` | 你组织的身份 |  |
| `--definition-id` | 要添加捆绑的应用程序的ID |  |
| `--token` | 一个个人 [访问令牌](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/personal-access-tokens) |  |
| `--skip-activation` | (可选)布尔旗以跳过自动激活 `AppBundle` | `false` |
| `--comment` | (可选)与创建的 `AppBundle`。可用于区分捆绑. |  |
| `--host` | (可选)内容 CMA 端点使用 | `api.contentful.com` |

**说明:** 您也可以以交互模式通过所有参数来跳过被请求的参数 .

### 激活 AppBundle 程序

允许您激活 AppBundle 应用程序定义 . 当启动时,该应用程序将服务于新启用的AppBundle.

#### 互动模式 :

在交互模式下,CLI会询问所有所需的选项.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts activate
> ```

#### 非交互模式 :

当通过 `--ci` 参数添加所有变量作为参数.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts activate --ci \
>     --bundle-id some-bundle-id \
>     --organization-id some-org-id \
>     --definition-id some-app-def-id \
>     --token $MY_CONTENTFUL_PAT
> ```

**选项 :**

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `--bundle-id` | 您想要激活的 AppBundle 的ID |  |
| `--organization-id` | 你组织的身份 |  |
| `--definition-id` | 要添加捆绑的应用程序的ID |  |
| `--token` | 一个个人 [访问令牌](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/personal-access-tokens) |  |
| `--host` | (可选)内容 CMA 端点使用 | `api.contentful.com` |

**说明:** 您也可以以交互模式通过所有参数来跳过被请求的参数 .

### 打开应用程序定义的设置

它打开了内容丰富的网络应用程序中的设置,以便您可以使用UI来更改一个软件的设置 [附录](https://www.contentful.com/developers/docs/extensibility/app-framework/app-definition/)。 。 。 .

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts open-settings --definition-id some-definition-id
> ```

如果环境变量(`CONTENTFUL_APP_DEF_ID`) 已经设置.

> **示例**
> 
> ```shell
> $ CONTENTFUL_APP_DEF_ID=some-definition-id npx --no-install @contentful/app-scripts open-settings
> ```

**选项 :**

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
|  |  |  |
| `--definition-id` | 要添加捆绑的应用程序的ID |  |
| `--host` | (可选)内容 CMA 端点使用 | `api.contentful.com` |

**说明:** 您也可以以交互模式通过所有参数来跳过被请求的参数 .

### 清理捆绑

允许您清理以前的捆绑列表 。 它获取列表并删除所有捆绑, 除了50个最新的. 您可以调整您想要保存的金额 `--keep <amount>` 到论证,如果不通过,默认为50.

#### 互动模式 :

在交互模式下,CLI会询问所有所需的选项.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts bundle-cleanup
> ```

如果环境变量(`CONTENTFUL_APP_DEF_ID`)和 (中文(简体) )`CONTENTFUL_ORG_ID`) 已经设置.

#### 非交互模式 :

当通过 `--ci` 参数作为参数需要添加所有变量

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts bundle-cleanup --ci \
>     --organization-id some-org-id \
>     --definition-id some-app-def-id \
>     --token $MY_CONTENTFUL_PAT
>     --keep 30
> ```

**选项 :**

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `--organization-id` | 你组织的身份 |  |
| `--definition-id` | 要添加捆绑的应用程序的ID |  |
| `--token` | 一个个人 [访问令牌](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/personal-access-tokens) |  |
| `--keep` | (可选) 要保存的捆绑量 | `50` |
| `--host` | (可选)内容 CMA 端点使用 | `api.contentful.com` |

**说明:** 您也可以以交互模式通过所有参数来跳过被请求的参数 .

### 将定义安装到特定空间/ 环境

它打开一个对话框来选择与给定的应用程序相关的空间和环境 [附录](https://www.contentful.com/developers/docs/extensibility/app-framework/app-definition/) 应安装.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts install --definition-id some-definition-id
> ```

如果环境变量(`CONTENTFUL_APP_DEF_ID`) 已经设置.

> **示例**
> 
> ```shell
> $ CONTENTFUL_APP_DEF_ID=some-definition-id npx --no-install @contentful/app-scripts install
> ```

默认情况下,脚本会将应用程序安装到默认主机URL: `app.contentful.com`。如果想要将应用程序安装到不同的主机 URL,则可以设置参数 `--host` 转到想要的主机 URL.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts install --definition-id some-definition-id --host api.eu.contentful.com
> ```

**选项 :**

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
|  |  |  |
| `--definition-id` | 要添加捆绑的应用程序的ID |  |
| `--host` | (可选)内容 CMA 端点使用 | `api.contentful.com` |

**说明:** 您也可以以交互模式通过所有参数来跳过被请求的参数 .

### 跟踪

我们收集了我们国家综合发展工具的个人化使用数据,以便改进经验。 如果您不想收集您的数据, 您可以通过提供 env 变量选择退出 `DISABLE_ANALYTICS` 设置为任意值 :

> **示例**
> 
> ```
> DISABLE_ANALYTICS=true npx create-contentful-app
> ```

### 构建内容函数源

将 Contentful 函数的源代码构建为 App Framework 兼容捆绑 .

#### 互动模式 :

在交互模式下,CLI会提示自定义配置,但不需要任何选项.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts build-functions
> ```

#### 非交互模式 :

当通过 `--ci` 参数作为参数需要添加所有变量

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts build-functions --ci \
>     --manifest-file path/to/contentful/app/manifest.json \
>     --esbuild-config path/to/custom/esbuild/config.js \
>     --watch
> ```

**选项 :**

选项 : -e, --sbuilt-config 自定义 esbuilt 配置文件路径 -m, -- mifest-file 内容应用程序显示文件路径 -w, -- 监视变化 -h, --help 显示命令的帮助

### 更新 App 动作

使用 Contentful App Manific 文件的配置创建或更新 App 的动作 。 已创建的资源将被同步回您的列表文件 .

#### 互动模式 :

在交互模式下,CLI会询问所有所需的选项.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts upsert-actions
> ```

#### 非交互模式 :

当通过 `--ci` 参数添加所有变量作为参数.

> **示例**
> 
> ```shell
> $ npx --no-install @contentful/app-scripts upsert-actions --ci \
>     --manifest-file path/to/contentful-app-manifest.json \
>     --organization-id some-org-id \
>     --definition-id some-app-def-id \
>     --token $MY_CONTENTFUL_PAT
> ```

**选项 :**

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `--manifest-file` | Contentful app 显示文件的路径 | `contentful-app-manifest.json` |
| `--organization-id` | 应用程序定义的组织身份 |  |
| `--definition-id` | 添加动作的应用程序的标识 |  |
| `--token` | 一个个人 [访问令牌](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/personal-access-tokens) |  |
| `--host` | (可选)内容 CMA 端点使用 | `api.contentful.com` |

**说明:** 您也可以以交互模式通过所有参数来跳过被请求的参数 .

## 常见问题

### @contentful/app-scripts 是什么？

用于构建内容应用程序的脚本集

### 如何安装 @contentful/app-scripts？

在项目目录运行 npm install @contentful/app-scripts，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 contentful-app-scripts，可以用 npx contentful-app-scripts 直接运行。

### @contentful/app-scripts 支持 TypeScript 吗？

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

### @contentful/app-scripts 支持 ESM 还是 CommonJS？

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

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

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

### @contentful/app-scripts 可以商用吗？

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

### @contentful/app-scripts 的下载量有多少？

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

### @contentful/app-scripts 还在维护吗？

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