enonic-app-manager

Enonic CLI 和本地开发环境助手

操作流程

步骤 1：检测工作区上下文

1. 在技能根目录中执行 node scripts/find-enonic-targets.mjs，扫描当前工作区中的 Enonic 项目标记（.enonic、含 com.enonic.xp 插件的 build.gradle、含 xpVersion 的 gradle.properties）。
2. 如果找到标记，请记录输出中的项目名称、关联的沙盒和 XP 版本。后续命令默认使用这些值。
3. 如果未找到标记，则将请求视为全新项目设置，并根据需要创建沙盒或搭建项目框架。

步骤 2：确保 CLI 可用

1. 运行 enonic --version，确认已安装 Enonic CLI。
2. 如果命令执行失败，请阅读 references/cli-reference.md 中的安装说明，并根据检测到的操作系统引导用户采用相应方式：
   • npm（任何操作系统）： npm install -g @enonic/cli
   • macOS： brew tap enonic/cli && brew install --no-quarantine enonic
   • Linux： wget -qO- https://repo.enonic.com/public/com/enonic/cli/installer/cli-linux/1.0.0/cli-linux-1.0.0.sh | sh
   • Windows： scoop bucket add enonic https://github.com/enonic/cli-scoop.git && scoop install enonic
3. 安装后，使用 enonic --version 验证。

步骤 3：沙盒管理

1. 阅读 references/cli-reference.md，了解完整的沙盒命令目录。
2. 将请求与正确的操作对应起来：
   • 创建： enonic sandbox create <name> [-v <version>] [-t <template>] [--skip-template] [-i <image>] [-f]
   • 列出： enonic sandbox ls
   • 启动： enonic sandbox start <name> [--detach] [--prod] [--debug]
   • 停止： enonic sandbox stop
   • 升级： enonic sandbox upgrade <name> -v <version>
   • 删除： enonic sandbox delete <name> -f
   • 复制： enonic sandbox copy <source> <target>
3. 创建沙盒时，如果未指定 XP 版本，请询问用户。已知版本和名称时，使用 -f 标志执行非交互式操作。注意：使用 -f 时，沙盒会在创建后自动启动，除非同时提供 --skip-start。
4. 如果请求中提到了模板，请列出可用模板，或使用 -t <template> 标志。使用 --skip-template 可创建不预装应用的空白沙盒。
5. 如果请求中提到了 Docker，请使用 -i <image>（例如 enonic/xp:latest-sdk），以 Docker 镜像而非下载的 XP 发行版为沙盒提供支持。需要在 $PATH 中安装 docker。

步骤 4：项目搭建

1. 创建新项目时，使用简化命令：enonic create <name> [-r <starter>] [-s <sandbox>] [-f]
2. 常见的 starter 包括 starter-vanilla、starter-headless 和 starter-nextjs。完整选项列表请阅读 references/cli-reference.md。
3. 将现有项目关联到其他沙盒：enonic project sandbox <name>
4. 创建后，确保项目文件夹中包含 build.gradle 和 .enonic 配置。

步骤 5：开发工作流

1. 确定合适的开发命令：
   • 开发模式（热重载）： enonic dev — 以分离模式启动沙盒，并通过监视文件运行应用。请在项目根目录中执行。
   • 仅构建： enonic project build
   • 部署到沙盒： enonic project deploy [sandbox-name] [-c] — 使用 -c 进行持续部署。
   • 安装到正在运行的 XP： enonic project install
   • 运行测试： enonic project test
   • 清理构建产物： enonic project clean
   • 运行任意 Gradle 任务： enonic project gradle <tasks>
2. 如果沙盒尚未运行，请先启动：enonic sandbox start <name> -d
3. 使用 Ctrl-C 终止开发模式。CLI 会尝试自动停止分离模式运行的沙盒。 步骤 6：管理运行中的 XP 应用
4. 如需管理正在运行的 XP 实例中的应用，请阅读 references/cli-reference.md 了解 XP 应用命令。
5. 根据操作选择相应命令：
   • 从 URL 安装： enonic app install --url <jar-url>
   • 从文件安装： enonic app install --file <path-to-jar>
   • 启动应用： enonic app start <app-key>
   • 停止应用： enonic app stop <app-key>
6. XP 命令需要身份验证。使用 --cred-file <path>（XP 7.15+）、使用 --client-key <path> + --client-cert <path> 进行 mTLS（XP 7.15+），或设置 ENONIC_CLI_REMOTE_USER 和 ENONIC_CLI_REMOTE_PASS 环境变量。

步骤 7：生成 CI/CD 流水线

1. 阅读 assets/enonic-ci.template.yml 了解 GitHub Actions 工作流模板。
2. 根据项目自定义模板：
   • 在 sandbox 创建步骤中设置正确的 XP 版本。
   • 设置应用名称和 Gradle 构建参数。
   • 配置部署目标（用于预发布环境的 sandbox，用于生产环境的 cloud）。
3. 将生成的工作流文件放在项目仓库中的 .github/workflows/enonic-ci.yml。

步骤 8：故障排查

1. 如果 sandbox 无法启动或部署失败，请阅读 references/troubleshooting.md 了解常见问题和解决方法。
2. 关键诊断命令：
   • enonic sandbox ls — 检查 sandbox 状态和 XP 版本。
   • enonic system info — 检查运行中 XP 实例的详细信息。
   • 检查端口 8080（HTTP）和 5005（debug）是否可用。
3. 如果出现版本不匹配错误，请阅读 references/compatibility.md 了解 CLI 与 XP 版本的兼容性。

错误处理

• 如果 scripts/find-enonic-targets.mjs 没有返回结果，请改为按照全新项目的设置说明操作，而不要报错退出。
• 如果 enonic --version 执行失败，请先按照步骤 2 指引安装 CLI，再继续操作。
• 如果创建 sandbox 时出现版本错误，请阅读 references/compatibility.md 并建议使用兼容的 XP 版本。
• 如果启动 sandbox 时发生端口冲突，请阅读 references/troubleshooting.md 了解解决步骤。
• 如果 enonic dev 执行失败，请确认项目包含 Gradle dev 任务（所有官方起始项目均包含该任务），并确认已链接的 sandbox 存在，且未在另一个终端中运行。