# @adobe/aem-import-helper 中文文档

规范地址：https://npmcn.com/package/%40adobe/aem-import-helper/

版本：1\.6\.2
npm 元数据更新时间：2026-10-29T01:49:30.543Z
中文译文更新时间：2026-11-06T06:08:52.988Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：228 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.17\.0 \<25\.0\.0
- 运行依赖：17 个
- 首次发布：2025-03-12T14:19:49.225Z
- 最新版本发布：2026-10-29T01:49:30.192Z
- 近 30 天下载量：4579（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 14 个）

## 中文简介

用于将站点导入 AEM 的帮助工具 .

## 安装

```sh
npm install @adobe/aem-import-helper
```

也可以使用：`pnpm add @adobe/aem-import-helper`、`yarn add @adobe/aem-import-helper`、`bun add @adobe/aem-import-helper`

## README

# AEM 导入助手

帮助将您的网站导入AEM的同伴.

### 特征

-   运行大 [导入](https://npmcn.com/package/%40adobe/aem-import-helper/#readme-import) 将 AEM 导入为服务的工作([API 文件](https://opensource.adobe.com/spacecat-api-service/#tag/import)) (中文(简体) ).
-   [套装](https://npmcn.com/package/%40adobe/aem-import-helper/#readme-bundle) 您的导入脚本.
-   [导入交叉行走内容](https://npmcn.com/package/%40adobe/aem-import-helper/#readme-importing-content-into-AEM) 给您的 AEM 作者.
-   [导入 DA 内容](https://npmcn.com/package/%40adobe/aem-import-helper/#readme-importing-content-into-DA) 改为作者巴士.

## 安装

最好是作为非依赖性,但也可以在全球使用:

```
npm install @adobe/aem-import-helper --save-dev
```

## 进口的前提条件

设置您的环境变量( 无论是在 shell 配置文件中还是在 `.env` 文件名 :

```
export AEM_IMPORT_API_KEY=your-import-api-key
```

将 npm 脚本项添加到您的边际传送项目 `package.json`数字 :

```
"import": "aem-import-helper import"
```

## 使用量

进口有两种类型:基于文档的AEM授权(xwalk). 关于每种类型的更多信息,请参见以下各节.

两种导入类型都需要包含所有URL列表的文件来导入,每行一个. 创建一个文件( 取名为 “ urls. txt ”) , 并将 URL 添加到此文件 .

### 基于文档的导入

默认导入基于 doc, 仅提供urls.txt文件和导入.js文件 .

通过下列命令执行导入:

```
npm run import -- --urls ./urls.txt --importjs tools/importer/import.js
```

这个 `import.js` 您提供的文件将自动被捆绑并作为一个 Service API 发送给导入,因此支持引用其它本地脚本(如变压器) 。 我们为什么要捆绑进口文件? 见下文关于 [捆绑多个导入脚本](https://npmcn.com/package/%40adobe/aem-import-helper/#readme-bundling-multiple-import-scripts) 更多细节.

完成后,将打印出一个预先签名的URL从S3下载导入结果(作为.zip存档)到将包含所生成文件的控制台.

#### 共享点上传

任择 [m365 立方厘米](https://pnp.github.io/cli-microsoft365/) 可以安装和配置,将导入结果上传到SharePoint. 你会需要你的 `tenantId` 编辑 `clientId` 页:1 [微软 Entra 应用程序](https://pnp.github.io/cli-microsoft365/user-guide/using-own-identity/) (在您的SharePoint上) 设置 CLI :

```
m365 setup
m365 login
```

从SharePoint复制一个链接到您想要上传到的目录 。 这可以从SharePoint Web UI,通过"Copy链接"按钮实现. 您的新链接形式如下: `https://example.sharepoint.com/:f:/r/sites/example/Shared%20Documents/destination-directory`

已登录到 sharePoint 的 `m365` CLI,将SharePoint链接作为参数传递给aem-import-helper:

```
npm run import -- --urls urls.txt --sharepointurl https://example.sharepoint.com/:f:/r/sites/example/Shared%20Documents/destination-directory
```

导入工作完成后,从S3中下载出导入结果,并上传到指定的SharePoint目录.

## AEM 写入( 十字路口) 导入

要进行跨行导入, 您需要提供引用的附加参数 。 模型、过滤器和定义文件 所需经费。 您还必须指定导入 `type` 作为 `xwalk` 和提供 `siteName` 财务报告和审定财务报表 `assetFolder`。 。 。 .

```
npm run import -- \
  --urls urls.txt \
  --importjs tools/importer/import.js \
  --options '{     
    "type": "xwalk", 
    "data": { 
      "siteName": "xwalk", 
      "assetFolder": "xwalk" 
    }  
  }' \
  --models ./component-models.json \
  --filters ./component-filters.json \
  --definitions ./component-definition.json
```

完成后,将打印出一个预先签名的URL从S3下载导入结果(作为.zip存档)到将包含所生成文件的控制台.

### 向 AEM 导入内容

将以下 npm 脚本条目添加到您的边框交付项目 `package.json`数字 :

```
"aem-upload": "aem-import-helper aem upload"
```

`aem-upload`:将内容包和相关资产上传到AEM.

### 正在使用 AEM 认证

为了认证AEM, 建议您获取您的AEM环境的开发标志 。 为了做到这一点, 通过 Cloud 管理器访问您 AEM 作者环境中的开发者控制台。 关于访问的细节 开发者控制台,参见 [AEM 作为云服务文档](https://experienceleague.adobe.com/docs/experience-manager-cloud-service/implementing/developing/aem-as-a-cloud-service-developer-console.html?lang=en) 财务报告和审定财务报表 [开发者流程](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/generating-access-tokens-for-server-side-apis#generating-the-access-token) 学习如何生成 Access Token .

一次进入开发者控制台 :

1.  点击集成
2.  点击本地令牌
3.  点击获取本地开发键

**注:开发标志只有效24小时.**

您可以在本地机器上的文件里存储此令牌, 或者通过令牌作为 cli 参数 . 如果您选择在文件中存储符号,则创建一个文件,并简单地将符号粘入到文件中并保存.

```
--token </path/to/token.txt> OR <token>
```

### 上传内容到 AEM

运行以下命令将内容包(JCR页面)和相关资产上传到您的 AEM 作者 :

```
npm run aem-upload -- \
  --token token.txt \
  --zip /path/to/zip.zip \
  --asset-mapping /path/to/asset-mapping.json \
  --target https://author-p1234-e1234.adobeaemcloud.com
```

**要求 :**

-   **符号**: 包含由 AEM 作者环境生成的符号的文件的绝对路径,或符号值.
-   **拉链**: 包含JCR页面的内容包ZIP文件的绝对路径,由导入工具生成.
-   **目标**:目标AEM作者环境URL.
-   **资产测绘**: 如果 `--skip-assets` 未提供或设定为真实,资产映射文件必须是绝对路径 到资产映射文件( e)`asset-mapping.json`),包含资产urls及其相应的JCR路径的映射.

**可选 :**

-   _产出_ \[默认='aem-assets'\]: 下载资产将存储的输出文件夹的绝对路径 .
-   _保留_ \[default=false\]:执行后将所下载的资产保存在输出文件夹中. 没有它,文件夹下 资产下载写入的输出文件夹(每个顶级的 DAM 文件夹,例如 。). `<output>/xwalk`)和 直接下载的资产 `/content/dam` 一旦安装了内容包,则删除。 如果输出 文件夹不存在,将全部删除。 如果有些资产上传失败, 内容包仍被安装 , 下载后的资产被保存起来,这样上传就可以重新测试,命令退出则处于非零状态.
-   _跳动资产_ \[default=false\]:跳过上传资产到AEM. .
-   _资产测绘_: 只有在 --skip- assets 属实时才有可选性 .
-   _图像到 png_ \[默认=真实\]: 真实时,在上传前将已下载的图像资产转换为PNG(JPEG,PNG,GIF,ICO,SVG,MP4除外).
-   _当地资产_: 本地资产文件夹的路径。 提供后,资产通过完整的DAM路径在当地解决,然后回到远程下载中处理任何缺失的文件. 文件夹结构必须映射 DAM 路径( 例如 ), `<local-assets>/content/dam/site/image.jpg`) (中文(简体) ).

命令执行后,内容包和相关资产会被上传到您的 AEM 作者环境. 内容包被安装,资产被上传到DAM.

## 将内容导入到 DA

将以下 npm 脚本条目添加到您的边框交付项目 `package.json`数字 :

```
"da-upload": "aem-import-helper da upload"
```

`da-upload`: 上传内容包和相关资产到DA.

### 正在使用 DA 认证

与 DA 认证, 建议您获取一个 IMS 访问令牌 。 见 [IMS API 参考文献](https://developer.adobe.com/developer-console/docs/guides/authentication/ServerToServerAuthentication/ims#fetching-access-tokens) 学习如何生成 Access Token .

您可以在本地机器上的文件里存储此令牌, 或者通过令牌作为 cli 参数 。 如果您选择在文件中存储符号,则创建一个文件,并简单地将符号粘入到文件中并保存.

```
--token </path/to/token.txt> OR <token>
```

### 上传内容到作者总线

运行以下命令将内容( HTML 页面) 和相关资产上传到您的 DA env :

```
npm run da-upload -- \
  --token token.txt \
  --org myDaOrg\
  --site myDaSite\
  --asset-list /path/to/asset-list.json \
  --da-folder /path/to/da/folder \
  --output /path/to/download/folder
```

**要求 :**

-   **奥尔格**: 您 DA 项目的组织名称 。 这是您 DA URL 路径的第一部分( 例如, 从 `https://da.live/#/geometrixx/outdoors`,该矿石将是 `geometrixx`) (中文(简体) ).
-   **站点**:您组织内的网站名称。 这是您 DA URL 路径的第二部分( 例如, 从 `https://da.live/#/geometrixx/outdoors`收回会是 `outdoors`) (中文(简体) ).
-   **da-文件夹**绝对路径 `da` 包含 HTML 页面的文件夹,由导入者生成.
-   **资产清单**: 资产列表文件的绝对路径( Y)`asset-list.json`),包含资产urls列表,以及站点来源信息.

**资产列表.json 格式 :**

```json
{
  "assets": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.png",
    "https://example.com/document.pdf"
  ],
  "siteOrigin": "https://example.com"
}
```

**说明**:图像和非图像资产处理方式不同. 图像存储在页面特定的阴影(.dot)文件夹中,而非图像介质(PDFs,docs)则存储在 `shared-media` 每页父目录下的文件夹.

**可选 :**

-   _符号_: 包含您 DA 环境的 IMS 令牌的文件的绝对路径, 或令牌值 .
-   _产出_ \[默认='da-content'\]: 将存储 DA 内容( 页面、 资产等) 的输出文件夹的绝对路径 .
-   _保留_ \[default=false\]:在上传后保留所下载的资产并在当地更新HTML,而不是清理.
-   _图像到 png_ \[默认=真实\]: 真实时,在上传前将已下载的图像资产转换为PNG(JPEG,PNG,GIF,ICO,SVG,MP4除外).
-   _当地资产_: 本地资产文件夹的绝对路径。 该工具一旦提供,将首先试图从本地文件夹复制资产 。 如果在本地找不到资产,则会回到下载 `siteOrigin`。当:
    -   HTML 页面有本地( 相对) 资产引用
    -   当地已有资产
    -   您想要避免重新下载已有的资产

虚假时保留原始图像格式并用原始扩展名更新引用. 只有在您知道您的图像被 DA 支持时才会使用此选项 .

**使用当地资产:**

使用时 `--local-assets` 带有本地文件夹路径的旗帜 :

```
npm run da-upload -- \
  --org myDaOrg \
  --site myDaSite \
  --asset-list /path/to/asset-list.json \
  --da-folder /path/to/da/folder \
  --local-assets /path/to/local/assets/folder
```

该工具将:

1.  试图先使用本地文件夹中的资产
2.  如果本地找不到资产, 则返回原址下载
3.  上传所有已解析的资产到 DA
4.  照常更新 HTML 引用
5.  上传更新的 HTML 页面

 `asset-list.json` 在这种情况下,应提及资产 **相对于 `--local-assets` 文件夹**数字 :

```json
{
  "assets": [
    "./hero/banner.jpg",
    "./team/john-smith.png",
    "/documents/brochure.pdf"
  ],
  "siteOrigin": "http://adobe.com"
}
```

**示例本地资产文件夹结构 :**

```
/path/to/local/assets/          <- This is your --local-assets folder
├── hero/
│   └── banner.jpg
├── team/
│   └── john-smith.png
└── documents/
    └── brochure.pdf
```

命令执行后,HTML页面和相关资产被上传到Author Bus.

#### 资产参考战略

该工具处理图像和非图像资产的方式不同,以优化DA/Edge交付服务:

**图像** (JPG、PNG、GIF等):

-   存储在每页相邻的阴影文件夹中
-   通过 `https://content.da.live/...` 路径.
-   **示例**: 页 次 `intro.html` • 图像参考 `https://content.da.live/aemysites/mySite/about-me/.intro/photo.jpg`

**非图像媒体** (PDF,其他媒体等):

-   存放于a `shared-media` 页面父目录下的文件夹
-   通过边缘交付预览 URL 引用
-   **示例**: PDF 存储于 `about-me/shared-media/resume.pdf` - 称为 `https://main--mySite--aemysites.aem.page/about-me/shared-media/resume.pdf` 内部 `intro.html`。 。 。 .

**上传性能 :** 该工具通过平行处理每个页面内的资产来优化上传性能(最多50个同时上传),同时尊重CDN同时请求的限制.

```
Page 1 → Download Assets (parallel) → Upload Assets (max 50 parallel) → Upload HTML → 
Page 2 → Download Assets (parallel) → Upload Assets (max 50 parallel) → Upload HTML → 
Page 3 → ...
```

## 捆绑多导入脚本

通过创建您导入脚本的捆绑版本,它使它与导入服务兼容,因为所有的脚本都需要在一个js文件中.

将 npm 脚本项添加到您的边际交付项目 `package.json`数字 :

```
"bundle": "aem-import-helper bundle"
```

运行脚本 :

```
npm run bundle -- --importjs tools/importer/import.js
```

## 常见问题

### @adobe/aem-import-helper 是什么？

用于将站点导入 AEM 的帮助工具 \.

### 如何安装 @adobe/aem-import-helper？

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

### @adobe/aem-import-helper 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/adobe\_\_aem-import-helper 是否存在。

### @adobe/aem-import-helper 支持 ESM 还是 CommonJS？

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

### @adobe/aem-import-helper 需要什么版本的 Node\.js？

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

### @adobe/aem-import-helper 可以商用吗？

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

### @adobe/aem-import-helper 的下载量有多少？

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

### @adobe/aem-import-helper 还在维护吗？

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