commerce-app-init

初始化新的 Commerce 应用

搭建一个基础的 Adobe Commerce 应用：创建包含元数据的 app.commerce.config.ts，然后运行 init 安装依赖并生成所有必需的项目文件。 扩展性领域（事件、webhook、业务配置）需通过领域技能单独添加。

步骤 1 — 创建配置

如果项目根目录中已存在 app.commerce.config.ts，不要覆盖它 — 直接跳到步骤 2（此技能可以安全地在已有配置的应用上再次调用）。否则，根据用户的意图推导以下字段的值，确认后将文件写入项目根目录：

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

export default defineConfig({
  metadata: {
    id: "my-commerce-app", // alphanumeric + hyphens only, max 100 chars
    displayName: "My Commerce App", // shown in App Management UI, max 50 chars
    description: "...", // max 255 chars
    upgradeMode: "manual", // optional; currently defaults to "manual" while upgrade execution stabilizes (will default to "auto" once ready); "auto" (experimental) runs upgrades after deploy and waits for completion, "manual" returns plans without executing them
    version: "1.0.0", // Major.Minor.Patch only, no pre-release identifiers
  },
});

完整的注释模板请参见 assets/app.commerce.config.ts。

步骤 2 — 初始化项目

始终运行 init — 它会查找现有配置、验证配置并处理项目设置：

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

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

对于 TypeScript Commerce 配置，init 还会创建缺失的 webpack-config.cjs 和根目录 tsconfig.json 文件，安装兼容的 typescript、ts-loader、@tsconfig/bases 和 @types/node 开发依赖，并将 typecheck:actions 添加到项目组合后的 typecheck 脚本中。生成的 Runtime action 仍为 JavaScript。完成此脚手架搭建后，用户编写的运行时 action（通过下方的领域技能添加）和自定义安装脚本（commerce-app-storage）可以使用 .ts 编写 — 如果要将现有 JavaScript 项目迁移为 TypeScript，请参阅 aio-commerce-lib-app 使用指南了解完整的迁移步骤。

项目结构

init 完成后，项目在 src/ 下有两类目录：

• src/commerce-extensibility-1/actions/ — 用于 webhook 和事件的自定义运行时 action。在 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 action，同时排除拥有独立 TypeScript 配置的 Admin UI web-src。

步骤 3 — 验证配置

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

aio app build

如果配置无效，构建会失败，并显示指明出错字段的详细验证错误。

常见问题

• 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 通过后：

1. 初始化 Developer Console — 对于任何与 App Builder 设置（Console 项目/工作区、API 订阅、部署、运行、工作区连接）相关的后续主题，请调用技能 appbuilder-project-init（来自 adobe/skills）。告知它：

   • 跳过 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
   

2. 使用领域技能扩展 — 工作区连接完成后：

   • commerce-app-eventing — 管理 Commerce 和外部事件源
   • commerce-app-webhooks — 管理 Webhook 拦截
   • commerce-app-business-config — 管理自定义业务配置
   • commerce-app-admin-ui — 使用自定义列、批量操作、订单视图按钮或菜单项扩展 Commerce Admin UI
   • commerce-app-storage — 使用持久化、可查询的数据库存储支持运行时操作

参考资料

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