aem-cli

AEM CLI

用于 AEM Edge Delivery Services 的本地开发工具。提供三个命令：aem up（本地开发服务器）、aem import（导入服务器和 UI）、aem content（da.live 内容同步）。

二进制文件：aem（主要名称）、hlx（原 helix-cli 包的别名，该包在 v15.0.0 更名为 @adobe/aem-cli）。

---

1. 安装

前提条件： Node.js 12.11 或更高版本（推荐 Node 22 LTS）。[verified]

# Global install
npm install -g @adobe/aem-cli

# One-off via npx (no global install needed)
npx -y @adobe/aem-cli up

验证：

aem --version   # or: hlx --version

从旧版 helix-cli 包迁移

如果 npm install -g @adobe/aem-cli 失败并提示 File exists: …/hlx，说明仍安装着旧版包，且它占用了该二进制文件。请先卸载它（npm 包作用域为 @adobe，名称为 helix-cli）：[verified]

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

二进制文件名称从 hlx 改为 aem；安装后两者均可使用，因为 aem-cli 将 hlx 作为别名一并提供。

---

2. aem up — 本地开发服务器

Agent 标准调用方式：

aem up --no-open --forward-browser-logs

检查服务器是否正在运行：

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
# Expected: 200

主要标志

标志	功能
--no-open	启动时不打开浏览器窗口
--forward-browser-logs	将浏览器控制台消息（log、error、warn、info）转发到终端
--port <n>	使用不同端口侦听（默认值：3000）
--addr <addr>	绑定地址；使用 * 允许外部连接（默认值：127.0.0.1）
--url <url>	用于代理内容的源 URL（覆盖项目的默认页面 URL）
--html-folder <dir>	从 <dir> 提供本地 HTML 文件，无需扩展名
--html-mount <path>	提供 --html-folder 文件的 URL 路径（默认值：/<dir>）
--no-livereload	禁用文件更改时的浏览器自动重新加载
--stop-other	启动前停止使用同一端口的其他 AEM CLI 实例（默认值：true）
--tls-cert <file>	TLS .pem 文件的路径（参见 §4）
--tls-key <file>	TLS .key 文件的路径（参见 §4）
--allow-insecure	允许向上游服务器发送不安全请求（使用自签名证书）
--print-index	打印当前页面的索引记录（用于调试）
--site-token <token>	CLI 访问网站所需的站点令牌
--cookies	代理所有 Cookie（默认仅代理 hlx-auth-token）

--html-folder： 如果不使用此选项，则绝不会提供本地 HTML 文件——所有请求都会代理到远程管道，本地独有路径会返回 404。[verified]

在本地提供导入的 HTML（preview-import 模式）

aem up --html-folder drafts --no-open --forward-browser-logs
# Files in ./drafts/ are served at /drafts/<name> (no extension needed)

---

3. .env 配置

所有选项都可以保存在项目根目录的 .env 文件中；系统会自动加载。[verified]

# .env example
AEM_PORT=8080
AEM_PAGES_URL=https://stage.myproject.com
AEM_FORWARD_BROWSER_LOGS=true
AEM_HTML_FOLDER=drafts
AEM_TLS_CERT=server.crt
AEM_TLS_KEY=server.key
AEM_OPEN=/products

完整的 AEM_* 环境变量参考及默认值，请参阅 references/command-reference.md。

---

4. HTTPS / TLS

受信任的本地证书（推荐——避免浏览器警告）

安装 mkcert（macOS 上使用 brew install mkcert，Windows 上使用 choco install mkcert，其他系统上使用 go install filippo.io/mkcert@latest），然后：

mkcert -install                                          # one-time CA install
mkcert -cert-file server.crt -key-file server.key localhost 127.0.0.1
aem up --tls-cert server.crt --tls-key server.key

自签名证书（不使用 mkcert）

openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes \
  -out server.crt -keyout server.key -subj "/CN=localhost"
aem up --tls-cert server.crt --tls-key server.key

在 .env 中持久化 TLS 配置

AEM_TLS_CERT=server.crt
AEM_TLS_KEY=server.key

---

5. 公司代理和证书信任

在会拦截 HTTPS 的代理后运行时，aem up 会失败并提示 unable to get local issuer certificate。 从浏览器导出公司 CA 证书或向 IT 部门索取，然后设置：

# macOS / Linux
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt
aem up

# Windows
set NODE_EXTRA_CA_CERTS=./certs/corporate-ca.pem
aem up

NODE_EXTRA_CA_CERTS 是 Node 内置变量——请在 Shell 配置文件或 CI 中设置，而不是在 .env 中设置。

代理环境变量：

变量	用途
HTTP_PROXY	HTTP 请求的代理
HTTPS_PROXY	HTTPS 请求的代理
ALL_PROXY	任一协议的回退代理
NO_PROXY	以逗号分隔的绕过代理的主机；* 表示禁用所有代理

---

6. aem import — 导入服务

本地导入服务（默认端口为 3001），用于提供 helix-importer-ui。

aem import                   # opens Importer UI in browser at port 3001
aem import --no-open         # headless / background start
aem import --port 3002       # different port

主要标志：

标志	默认值	功能
--port	3001	导入服务端口
--no-open	—	不打开浏览器窗口
--allow-insecure	true	允许代理站点使用自签名证书
--ui-repo <url>	GitHub 上的 helix-importer-ui 仓库	自定义导入器 UI 仓库
--skip-ui	false	跳过 UI 的下载和安装
--headers-file <file>	—	包含代理请求自定义标头的 JSON 文件
--cache <dir>	—	将代理响应缓存到本地文件夹
--dump-headers	false	在控制台打印请求标头以进行调试
--tls-cert / --tls-key	—	为导入服务本身配置 TLS（见 §4）

工作流： 如需编写 import.js 转换脚本或运行完整导入流程，请使用 page-import 或 generate-import-html 技能。本技能仅介绍如何启动和配置服务。

---

7. aem content — da.live 内容同步

aem content clone [--path /]   # auth via browser popup; clones into ./content/
aem content status             # show added / modified / deleted files
aem content diff [path]        # diff local vs remote
aem content merge [path]       # sync remote changes into local files
aem content add <files..>      # stage changes (like git add)
aem content commit -m "..."    # commit staged changes (like git commit)
aem content push               # upload committed changes to da.live
aem content push --force       # overwrite remote on conflict

身份验证令牌缓存于 .hlx/.da-token.json（已加入 gitignore）；首次使用时通过浏览器 OAuth 授权。

直接读取令牌以验证 curl 调用：

TOKEN=$(jq -r .access_token .hlx/.da-token.json)

已知行为：二进制文件

aem content push 会静默跳过二进制文件（图片、PDF、字体）。[verified]

验证二进制文件是否已上传：

curl -sI https://content.da.live/<org>/<repo>/path/to/image.png | grep -i "content-type"

如果返回 404，请通过 DA Source API 直接上传二进制文件：

TOKEN=$(jq -r .access_token .hlx/.da-token.json)
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @./image.png \
  "https://admin.da.live/source/<org>/<repo>/path/to/image.png"

已知行为：上传前的 HTML 规范化

上传前的规范化处理会移除 EDS 图标装饰（<span class="icon icon-X"> 等）。 [verified] 如需保留 EDS HTML 的原始字节，请直接 POST 到 DA Source API：

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/html" \
  --data-binary @./page.html \
  "https://admin.da.live/source/<org>/<repo>/path/to/page.html"

有关 DA Source API 契约和速率限制，请参阅 da-content 技能（平台参考 §7）。

---

故障排除

症状	原因	修复方法
npm install -g @adobe/aem-cli → File exists: …/hlx	旧的 helix-cli 软件包仍占用该二进制文件	卸载旧软件包（见 §1），然后重新安装
aem up → EADDRINUSE: address already in use :::3000	端口 3000 已被占用	传入 --port <other>，或终止占用 3000 端口的进程
aem up → unable to get local issuer certificate	公司代理拦截了 TLS	导出公司 CA 证书 → export NODE_EXTRA_CA_CERTS=/path/to/ca.crt
localhost:3000/mypath 返回 404	mypath/ 中的本地 HTML 文件未挂载	添加 --html-folder mypath（或在 .env 中设置 AEM_HTML_FOLDER=mypath）
aem up → 实际存在的页面返回 pipeline 404	代理使用了错误的源 URL	传入 --url https://your-pages-url.aem.page
aem content push 报告成功，但二进制文件缺失	CLI 静默跳过了二进制文件	通过 DA Source API 上传二进制文件（见 §7）
aem content push 从 HTML 中移除了图标 span	上传前的规范化处理移除了 EDS 装饰	如需保留原始字节，请直接 POST 到 DA Source API
aem import UI 无法加载	端口 3001 被占用，或 UI 下载失败	尝试使用 --port 3002；或使用 --skip-ui 并单独打开 UI

---

参考

• references/command-reference.md — 所有命令的完整标志和 AEM_* 环境变量表
• 上游文档：https://www.npmjs.com/package/@adobe/aem-cli — @adobe/aem-cli 的 npm 页面 （由于历史原因，GitHub 仓库名为 helix-cli）
• 导入器 UI：helix-importer-ui（在 npm 或 GitHub 上搜索 helix-importer-ui）——由 aem import 提供