# @adobe/aem-cli 中文文档

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

版本：16\.22\.16
npm 元数据更新时间：2026-10-28T04:02:45.613Z
中文译文更新时间：2026-11-05T20:12:26.867Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：893 kB，65 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：44 个
- 首次发布：2023-09-29T19:47:28.227Z
- 最新版本发布：2026-10-28T04:02:45.212Z
- 近 30 天下载量：30938（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：318（近 12 个月 117 个）

## 中文简介

AEM CLI (法语)

## 安装

```sh
npm install @adobe/aem-cli
```

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

## README

# AEM 命令行接口 (`aem`(中文(简体) )

## 状态

[![codecov](https://img.shields.io/codecov/c/github/adobe/helix-cli.svg)](https://codecov.io/gh/adobe/helix-cli) ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/adobe/helix-cli/main.yaml) [![GitHub license](https://img.shields.io/github/license/adobe/helix-cli.svg)](https://github.com/adobe/helix-cli/blob/master/LICENSE.txt) [![GitHub issues](https://img.shields.io/github/issues/adobe/helix-cli.svg)](https://github.com/adobe/helix-cli/issues)

AEM指令行接口允许网络开发者使用Adobe体验管理器站点功能创建,开发并部署数字体验. Edge Production Services. 其中一些功能在之前被称为"富兰克林"或"螺旋计划".

## 安装

安装 `aem` 作为全球指令。 你需要节点12.11或更新.

```bash
npm install -g @adobe/aem-cli
```

如果失败 `File exists: /opt/homebrew/bin/hlx`请 [看这里](https://npmcn.com/package/%40adobe/aem-cli/#readme-npm-install-fails-with-file-exists-opthomebrewbinhlx)。 。 。 .

## 快速启动

```
$ aem --help
Usage: aem <command> [options]

Commands:
  aem up       Run a AEM development server
  aem import   Run the AEM import server
  aem content  Manage local da.live content

Options:
  --version                Show version number                         [boolean]
  --log-file, --logFile    Log file (use "-" for stdout)  [array] [default: "-"]
  --log-level, --logLevel  Log level
        [string] [choices: "silly", "debug", "verbose", "info", "warn", "error"]
                                                               [default: "info"]
  --tls-key, --tlsKey      Path to .key file (for enabling TLS)        [string]
  --tls-cert, --tlsCert    Path to .pem file (for enabling TLS)        [string]
  --help                   Show help                                   [boolean]

use <command> --help to get command specific details.

for more information, find our manual at https://github.com/adobe/helix-cli
```

## 开始发展

```
$ cd <my-cool-project>
$ aem up
```

### 自动打开浏览器

这个 `--open` 参数选择路径, eg `--open=/products/`,将会使浏览器打开 在具体地点。 禁用为 `--no-open'.`

### 浏览器控制台日志转发

这个 `--forward-browser-logs` 旗帜允许将浏览器控制台信件(日志、错误、警告、信息)转发到终端。 这对调试客户端问题特别有用,无需打开浏览器的开发工具.

```
$ aem up --forward-browser-logs
```

启用时,浏览器控制台消息将以下列格式出现在您的终端中:

```
[Browser:error] 2025-07-27T10:30:45.123Z http://localhost:3000/script.js:42 Error message here
```

在以下情况下,这一特点特别有用:

-   在无头环境中调试 JavaScript 错误
-   监测开发期间客户方的行为
-   与需要在服务器和客户端日志中可见的 AI 编码助理合作

### html 内容预览文件夹

这个 `--html-folder` 选项允许在没有扩展名的情况下服务 HTML 文件,用于在无法访问作者系统时预览内容变化.

```
$ aem up --html-folder drafts                      # serves at /drafts/*
$ aem up --html-folder html --html-mount /       # serves at /* (root)
$ aem up --html-folder drafts --html-mount /preview # serves at /preview/*
```

使用 `--html-mount` 以控制文件服务的 URL 路径。 没有它,文件在 `/FOLDER/*`。 。 。 .

这使得有两个特点:

1.  **无扩展的 URL**: 访问 `/drafts/page` (或 `/page` 用根挂载)服务于相应的 `.html` 文件
2.  **有元数据的普通 HTML**创建 `.plain.html` 自动被适当的 HTML 结构和元数据处理所包裹的文件

#### Plain HTML 文件 (. plance.html) 互联网档案馆的存檔,存档日期2013-12-02

Plain HTML 文件只包含主要内容和一个可选的元数据块. CLI 自动 :

-   环绕内容 `<html><head><body><header><main><footer>` 结构
-   合并为 `head.html` 内容
-   元数据块从已提供的内容中去除并转换为元标记 `<head>`。 。 。 .

当请求决定 `<stem>`,CLI抬头看 `<stem>.html` 先掉头 `<stem>.plain.html`。通过 `--preferPlainHtml` 来倒置此顺序 —— 当您同时保存两个文件并希望普通版本获胜时有用 :

```
$ aem up --html-folder drafts --preferPlainHtml
```

### 设置使用 https 的自签名证书

1.  创建证书

```
$ openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out server.crt -keyout server.key -subj "/CN=localhost"
```

这将创建两个文件 : `server.crt` 财务报告和审定财务报表 `server.key`

或者,如果您的浏览器不信任证书,您可以使用 mkcert 生成信任的证书 :

```bash
# Install mkcert via Homebrew or your preferred method, then run:
mkcert -cert-file server.crt -key-file server.key localhost 127.0.0.1
```

2.  以 tls 支持启动 aem

```
$ aem up --tls-cert server.crt --tls-key server.key
    ___    ________  ___                          __      __ v14.26.1
   /   |  / ____/  |/  /  _____(_)___ ___  __  __/ /___ _/ /_____  _____
  / /| | / __/ / /|_/ /  / ___/ / __ `__ \/ / / / / __ `/ __/ __ \/ ___/
 / ___ |/ /___/ /  / /  (__  ) / / / / / / /_/ / / /_/ / /_/ /_/ / /
/_/  |_/_____/_/  /_/  /____/_/_/ /_/ /_/\__,_/_/\__,_/\__/\____/_/

info: Starting AEM dev server v14.26.1
info: Local AEM dev server up and running: https://localhost:3000/
```

3.  (可选) 将参数添加到.env文件 :

```
$ echo -e "AEM_TLS_CERT=server.crt\nAEM_TLS_KEY=server.key" >> .env
```

### 环境

所有命令参数也可以通过环境变量指定. 页:1 `.env` 文件为 自动装入 .

示例:

`.env`

```dotenv
AEM_OPEN=/products
AEM_PORT=8080
AEM_PAGES_URL=https://stage.myproject.com
```

#### HTTP 代理服务器

为了使用 HTTP 代理( 如公司防火墙 ) , 您可以设置相应的环境变量 :

`NO_PROXY` 是一个主机名列表(可选择带有端口)。 如果输入的 URL 匹配其中的任何条目 `NO_PROXY`,然后输入 URL 应通过直接请求获取(即没有代理).

匹配遵循以下规则: 1

`NO_PROXY=*` 禁用所有代理人. 空格和逗号可用于分隔 `NO_PROXY` 列表中选择一个选项. 若为 `NO_PROXY` 不包含任何条目,则代理从不禁用. 如果在主机名后添加一个端口,则端口必须匹配. 如果URL没有明确的端口名称,则使用协议的默认端口. 一般来说,只有在主机名与条目完全匹配时,代理机才会被禁用 `NO_PROXY` 列表中选择一个选项。 唯一的例外是以点开头或以通配符开头的条目;如果主机名以条目结尾,则代理机被禁用. 见test.js 关于什么应该匹配什么不匹配的例子.

`*_PROXY` 用于代理的环境变量取决于URL的协议. 譬如说, [https://example.com (中文(简体) )](https://example.com/) 使用“ https” 协议, 因此要使用的代理是 `HTTPS_PROXY` (无) `HTTP_PROXY`,仅用于http:-URLs).

如果现在, `ALL_PROXY` 如果没有其他匹配,则用作倒置.

#### 全球

| 选项 | 变量 | 默认 | 说明 |
| --- | --- | --- | --- |
| `--log-file` | `AEM_LOG_FILE` | `-` | 日志文件 。 使用情况 `-` 登录到 stdout |
| `--log-level` | `AEM_LOG_LEVEL` | `info` | 日志级别 |

#### 上调命令

| 选项 | 变量 | 默认 | 说明 |
| --- | --- | --- | --- |
| `--port` | `AEM_PORT` | `3000` | 开发服务器端口 |
| `--addr` | `AEM_ADDR` | `127.0.0.1` | 开发服务器绑定地址 |
| `--livereload` | `AEM_LIVERELOAD` | `true` | 在浏览器中允许自动重新装入修改过的源 . |
| `--no-livereload` | `AEM_NO_LIVERELOAD` | `false` | 禁用活装 . |
| `--forward-browser-logs` | `AEM_FORWARD_BROWSER_LOGS` | `false` | 转发浏览器控制台日志到终端. |
| `--html-folder` | `AEM_HTML_FOLDER` | 未定义 | 从文件夹中服务 HTML 文件而无需扩展 . |
| `--html-mount` | `AEM_HTML_MOUNT` | `/FOLDER` | 提供html文件夹文件的 URL 路径 . |
| `--prefer-plain-html` | `AEM_PREFER_PLAIN_HTML` | `false` | 偏爱 `<stem>.plain.html` 结束 `<stem>.html` 当两者都存在时. |
| `--open` | `AEM_OPEN` | `/` | 服务器启动后在指定路径打开浏览器窗口 . |
| `--no-open` | `AEM_NO_OPEN` | `false` | 禁用自动打开浏览器窗口 . |
| `--tls-key` | `AEM_TLS_KEY` | 未定义 | .key文件路径( 用于启用 TLS) |
| `--tls-cert` | `AEM_TLS_CERT` | 未定义 | .pem 文件路径( 用于启用 TLS) |

在 Git 工作树中,默认端口由分支名( 3000- 3999) 衍生为 减少工作树之间的冲突。 明确 `--port` 或者说 `AEM_PORT` 设置 (包括 `.env`(即使设定为 `3000`。 。 。 . 命令行选项优先于环境变量.

## 开始导入

AEM导入器是一个支持向AEM导入内容的应用程序.

```
$ cd <my-cool-project>
$ aem import
```

读取完整的 AEM 导入器 [文档](https://github.com/adobe/helix-importer-ui)。 。 。 .

## 内容管理

这个 `aem content` 命令允许您从 da.live 本地查看内容,进行批量编辑,并推回更改。 当地内容存在于 `content/` 文件夹.

| 命令 | 说明 |
| --- | --- |
| `aem content clone` | Clone da.live 内容本地化为 `content/` |
| `aem content status` | 显示本地添加、 修改和删除的内容文件 |
| `aem content diff` | 在本地和远程内容之间显示 diff |
| `aem content merge` | 将远程内容合并到本地文件 |
| `aem content add` | 阶段变化 `content/` (比如说) `git add`(中文(简体) ) |
| `aem content commit` | 在 `content/` (比如说) `git commit`(中文(简体) ) |
| `aem content push` | 执行 `content/` 更改为 da.live(使用 `content add` 打开 `content commit` (第一个) |

### 服务本地内容

当a `content/` 文件夹已存在, `aem up` 首先自动服务内容, 返回到本地找不到的文件的代理 。 HTML 文件在 `content/` 包起来 `head.html` 并进行元数据块的处理,所以页面在从 da.live 服务时会以同样的方式制作.

# 发展AEM CLI

## 测试

你用得着 `npm run check` 运行测试并检查您的代码是否遵守 以 aem-cli 为编码样式.

### 浏览器可注入

浏览器注入的脚本(LiveReload and Controuplog servance)在单独的子项目中保存,地点是 `packages/browser-injectables/`。这种隔离使浏览器测试依赖性与主CLI分离.

#### 发展

-   可注入脚本在 `packages/browser-injectables/src/`
-   不需要构建步骤 - 脚本直接使用
-   浏览器测试仅在可插入代码更改时运行

#### 测试可注入浏览器

```bash
cd packages/browser-injectables
npm install
npm test
```

# 解决问题

## `aem up` 失败 `unable to get local issuer certificate`

此错误发生在服务器证书不被Node.js信任时. 典型现象 原因是连接到服务器 `*.aem.page` 财务报告和审定财务报表 `*.hlx.page` 被拦截 由企业代理或防火墙 试图检查流量.

这些代理人使用私人证书机构在证书上签名 他们拦截的服务器。 要让Node.js信任服务器证书,需要添加 信任的 CA 列表中的 CA 证书.

### 备选案文1:使用IT提供的CA证书

CA证书一般由您的IT部门提供. 你可以问他们 cA 证书并保存到文件,例如. `my-ca.crt`。 。 。 .

那你可以用这个 [`NODE_EXTRA_CA_CERTS`](https://nodejs.org/docs/latest/api/cli.html) 创建 Node.js 信任的环境变量 cA 证书 :

```bash
export NODE_EXTRA_CA_CERTS=my-ca.crt
aem up
```

### 选项2:从浏览器提取证书

如果您无法从您的IT部门获取 CA 证书,可以直接提取 从您的浏览器中 :

1.  访问浏览器中的 AEM 管理员 URL( 例如 ), `https://admin.hlx.page/sidekick/owner-name/repo-name/github-branch-name/config.json`(中文(简体) )
2.  点击地址栏中的挂锁图标查看证书细节
3.  导出证书链为 Base64 编码 `.pem` 文件
4.  保存到目录( 例如 ), `certs/hlx.page.pem`(中文(简体) )
5.  设置环境变量并运行 aem :

```bash
export NODE_EXTRA_CA_CERTS=./certs/hlx.page.pem
aem up
```

在视窗上,使用 `set` 改为 `export`数字 :

```cmd
set NODE_EXTRA_CA_CERTS=./certs/hlx.page.pem
aem up
```

这两种方法都会让Node.js信任服务器证书 `aem up` 应该工作.

## `npm install` 失败 `File exists: /opt/homebrew/bin/hlx`

如果您尝试安装 `@adobe/aem-cli`数字 :

```
> npm install -g @adobe/aem-cli
...
npm error EEXIST: file already exists
npm error File exists: /opt/homebrew/bin/hlx
npm error Remove the existing file and try again, or run npm
```

当您先前将此工具安装在其旧软件包名下时, 可能会发生这种情况 [@adobe/helix-cli (英语)](https://www.npmjs.com/package/@adobe/helix-cli)。从15.0.0版本开始,这个工具被重新命名 `aem` 发表于 `@adobe/aem-cli`上一个 `@adobe/helix-cli` 已经贬值。 然而,新软件包仍以旧名提供命令行二进制 `hlx` 计外 `aem`,用于后向相容性,可导致npm安装出错.

要解决,首先解开旧版,再用新名再安装:

```
npm uninstall -g @adobe/helix-cli
npm install -g @adobe/aem-cli
```

## 常见问题

### @adobe/aem-cli 是什么？

AEM CLI \(法语\)

### 如何安装 @adobe/aem-cli？

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

### @adobe/aem-cli 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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