SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场commerce-app-init

commerce-app-init

编程与开发

查看项目

更新于 10-15 08:28

技能介绍

用途

commerce-app-init 用于初始化一个新的 Adobe Commerce 应用（Commerce App）。它基于 @adobe/aio-commerce-lib-app 搭建基础项目结构，并生成 app.commerce.config.ts 配置文件及其元数据。扩展性领域（事件、Webhook、业务配置）不在此步骤中添加，而是分别通过对应的领域技能完成。

主要能力

  • 生成配置文件：在项目根目录创建 app.commerce.config.ts，包含 metadata 字段（id、displayName、description、upgradeMode、version）。
  • 初始化项目：运行 npx @adobe/aio-commerce-lib-app init，查找已有配置、进行校验并完成项目设置，包括安装依赖、生成项目文件。
  • 可重复调用：如果 app.commerce.config.ts 已存在，不会覆盖，直接进入初始化步骤；重复运行安全。config 存在时会跳过交互式提示，安装依赖并（重新）生成项目文件。
  • TypeScript 支持：对于 TypeScript Commerce 配置，init 会创建缺失的 webpack-config.cjs 和根 tsconfig.json，安装兼容的 typescript、ts-loader、@tsconfig/bases、@types/node 开发依赖，并在组合 typecheck 脚本中添加 typecheck:actions。生成的 Runtime actions 仍为 JavaScript。
  • 校验：运行 aio app build 构建项目以确认配置有效；配置无效时构建失败并给出指向问题字段的详细验证错误。

使用方式

第一步 — 创建配置

若项目根目录已存在 app.commerce.config.ts，不要覆盖，直接跳到第二步。否则根据用户意图推导字段值，确认后写入项目根目录：

// app.commerce.config.ts
import { defineConfig } from "@adobe/aio-commerce-lib-app/config";

export default defineConfig({
  metadata: {
    id: "my-commerce-app", // 仅字母数字和连字符，最长 100 字符
    displayName: "My Commerce App", // 显示在 App Management UI，最长 50 字符
    description: "...", // 最长 255 字符
    upgradeMode: "manual", // 可选；目前默认 "manual"，待升级执行稳定后将默认 "auto"；"auto"（实验性）在部署后运行升级并等待完成，"manual" 只返回计划而不执行
    version: "1.0.0", // 仅 Major.Minor.Patch，不支持预发布标识符
  },
});

完整带注释模板见 assets/app.commerce.config.ts。

第二步 — 初始化项目

始终运行 init，它会找到已有配置、校验并处理项目设置：

npx @adobe/aio-commerce-lib-app init

由于 app.commerce.config.ts 已存在，init 会跳过交互式提示。重复运行是安全的：存在配置时会安装依赖并（重新）生成项目文件 —— app-management 包会重新生成，而 src/commerce-extensibility-1/actions/ 下的用户包会被保留。

第三步 — 校验配置

构建项目以确认一切有效：

aio app build

项目结构

init 之后，src/ 下有两类目录：

  • src/commerce-extensibility-1/actions/ —— 用于 Webhook 和事件的自定义运行时动作。在 src/commerce-extensibility-1/ext.config.yaml 中以用户自定义包名注册（除框架保留的 app-management 外任意名称均可）。这些在 aio app build 后保留 —— 生成器只重新生成 app-management 包。
  • src/commerce-extensibility-1/.generated/ —— 由 aio app build 自动生成，视为只读，手动修改会被覆盖。
  • src/commerce-configuration-1/ —— 由 aio app build 管理，视为只读。
  • 根 tsconfig.json —— 检查 TypeScript Commerce 配置和生成的 Runtime actions，同时排除具有自身 TypeScript 配置的 Admin UI web-src。

常见问题

  • id 校验错误：metadata.id 仅接受字母数字和连字符，不能有点、下划线或空格。它不能在升级期间更改；要使用不同 ID 需卸载并重新安装应用。
  • version 校验错误：仅接受数字 semver（1.0.0），不支持预发布标识符（1.0.0-beta）。
  • 找不到 defineConfig：确保已安装 @adobe/aio-commerce-lib-app 并从 @adobe/aio-commerce-lib-app/config 导入。

质量要求

aio app build 无错误完成。

衔接

aio app build 通过后：

  • 引导 Developer Console：任何与 App Builder 设置（Console 项目/工作区、API 订阅、部署、运行、工作区接线）相关的后续主题，调用来自 adobe/skills 的 appbuilder-project-init 技能。告知它：跳过 aio app init 步骤——Commerce 脚手架已存在；在工作区引导中订阅 AdobeIOManagementAPISDK（I/O Management API）——运行时同步 IMS 凭据所需。工作区创建后，询问用户 Commerce 后端是 ACCS（Adobe Commerce as Cloud Service）还是 PaaS。若为 ACCS，还必须订阅 ACCS-REST-API：运行 aio console open 在浏览器中打开工作区，然后通过 Developer Console UI 手动添加。在用户确认已添加前不要继续。
  • 若未安装 appbuilder-project-init，请用户先行安装：
npx skills add adobe/skills --skill appbuilder-project-init -y
  • 用领域技能扩展：工作区接好后，可使用 commerce-app-eventing（管理 Commerce 和外部事件源）、commerce-app-webhooks（管理 Webhook 拦截）、commerce-app-business-config（管理自定义业务配置）、commerce-app-admin-ui（用自定义列、批量操作、订单视图按钮或菜单项扩展 Commerce Admin UI）、commerce-app-storage（为运行时动作提供持久、可查询的 DB 存储）。

限制

  • 此技能只搭建基础项目结构与配置，扩展性领域需另行通过领域技能添加。
  • metadata.id 不接受点、下划线或空格，升级期间不可更改。
  • version 仅支持数字 semver，不支持预发布标识符。
  • upgradeMode 目前默认 "manual"，"auto" 为实验性。
  • 自动生成目录视为只读，手动修改会被覆盖。
  • 官方文档未提供该技能的收费、价格、平台等信息，暂未提供。

参考资料

  • assets/app.commerce.config.ts —— 最小配置模板