文件CommerceAdobe Commerce as a Cloud Service

教學課程必要條件

Last update: Mon Mar 23 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

建立對象：

  • 中繼
  • 開發人員

此頁面列出Adobe Commerce as a Cloud Service教學課程的先決條件和設定步驟，例如評等延伸教學課程和送貨方法延伸教學課程。

一般必要條件

在本教學課程中，擴充功能和店面開發都需要下列工具。

  • Node.js （版本22.x.x）和npm （9.0.0或更新版本）：使用下列命令驗證您的安裝：

    code language-bash 
    node --version
npm --version

  • 安裝Git — 確認您的安裝：

    code language-bash 
    git --version

  • Bash shell

    • macOS/Linux：不需要安裝
    • Windows：使用Git Bash或Linux (WSL) 的Windows子系統

  • 下載AI輔助的IDE，例如Cursor （建議使用）。 也支援其他IDE，例如Claude Code、Gemini CLI或Copilot，但可能需要修改提示和教學課程中的其他步驟。

Adobe Commerce as a Cloud Service必要條件

  • 安裝Adobe I/O CLI

    code language-bash 
    npm install -g @adobe/aio-cli

  • 安裝Adobe I/O CLI Commerce、Adobe I/O CLI Runtime和App Builder CLI外掛程式：

    code language-bash 
    aio plugins:install https://github.com/adobe-commerce/aio-cli-plugin-commerce @adobe/aio-cli-plugin-app-dev @adobe/aio-cli-plugin-runtime

安裝Adobe I/O CLI和必要的外掛程式之後，請設定您的擴充性工作區。 Adobe建議使用自動化設定，以獲得最快的體驗。

  • 自動設定 （建議） — 執行單一命令以自動設定您的工作區。
  • 手動設定 — 依照逐步指示個別設定每個元件。

自動化設定（建議） automated-setup

TIP
如果您遇到自動化安裝的問題，請遵循下列手動安裝步驟。

app-setup命令會自動執行工作區設定程式，包括建立Adobe Developer Console專案、新增必要的API、設定Adobe I/O CLI、複製入門套件、連線本機工作區，以及安裝可擴充性的AI工具。

app-setup命令會引導您完成下列步驟：

  • 選擇或建立具有必要API的Adobe Developer Console專案
  • 使用您的組織、專案和工作區設定Adobe I/O CLI
  • 複製適當的入門套件並設定專案
  • 設定環境並將本機工作區連線到遠端工作區
  • 安裝Commerce擴充性工具和編碼代理程式技能

執行以下命令，並遵循互動式提示：

aio commerce extensibility app-setup

命令完成後，瀏覽至您的專案目錄並重新啟動編碼代理程式，以載入新的MCP工具和技能。 如果您的教學課程需要店面，請重新執行命令並選取AEM Boilerplate Commerce入門套件。

以下範例安裝顯示簽出入門套件之互動式提示和輸出。

範例安裝（結帳入門套件）
code language-shell-session 
aio commerce extensibility app-setup

🚀 Adobe Commerce Extensibility App Setup

✔ Logged in
📁 Working directory: /Users/username/projects/my-commerce-project

✔ Which starter kit would you like to use? Checkout Starter Kit
✔ Enter a name for your project directory: my-extension
✔ Which coding agent would you like to install the skills for? Cursor

📦 Cloning Checkout Starter Kit...
   ✔ Repository cloned
   Using npm (package-lock.json found)
   ✔ Dependencies installed

📋 Current Adobe I/O Console configuration:
   Org: My Organization (1234567)
   Project: My Commerce Project (1234567890123456789)
   Workspace: Stage (9876543210987654321)
✔ Do you want to continue with this configuration? (Answer "No" to select a different org/project/workspace)
No

🔧 Selecting Adobe I/O Console org, project, and workspace...

? Select Org: My Organization
Org selected My Organization
You are currently in:
1. Org: My Organization
2. Project: <no project selected>
3. Workspace: <no workspace selected>

? Select Project: My Commerce Project
Project selected : My Commerce Project
You are currently in:
1. Org: My Organization
2. Project: My Commerce Project
3. Workspace: <no workspace selected>

? Select Workspace: Stage
Workspace selected Stage
You are currently in:
1. Org: My Organization
2. Project: My Commerce Project
3. Workspace: Stage

✅ Console configured:
   Org: My Organization
   Project: My Commerce Project
   Workspace: Stage

🔐 Configuring workspace credentials and services...
   ✔ Workspace configuration loaded
   ✔ OAuth server-to-server credentials already configured
   ✔ All required services available in organization
   ✔ Subscribed to: Adobe Commerce as a Cloud Service

📋 Configuring Checkout Starter Kit...
   Creating .env from env.dist...
✔ Select tenant (type to search) My Commerce Instance:
https://<region>.api.commerce.adobe.com/<tenant-id>/graphql
   ✔ Commerce instance configured
✔ Enter the event prefix for your workspace: my-prefix
   ✔ Workspace IDs configured
   ✔ OAuth credentials configured
   ✔ Checkout Starter Kit configured

🔧 Installing Commerce Extensibility tools and agent skills...
   ✔ Commerce Extensibility tools installed

🎉 App setup complete!

📁 Project directory: /Users/username/projects/my-commerce-project/my-extension

Next steps:
   1. cd into your project directory
   2. Restart your coding agent to load the Commerce Extensibility tools and skills

手動設定 manual-setup

以下幾節將說明如何手動設定擴充性工作區的每個元件。 如果您偏好手動設定，或遇到自動安裝程式的問題，請依照下列步驟進行。

Adobe Developer Console必要條件

在Adobe Developer Console中設定具備必要API和憑證的專案。

  1. 導覽至Adobe Developer Console。
  2. 使用您的電子郵件和密碼登入。

建立新專案

在Adobe Developer Console中建立App Builder專案，以託管您的擴充功能。

  1. 導覽至Adobe Developer Console。

  2. 按一下​Create project from a template。

  3. 選取​ App Builder ​範本。

  4. 輸入​ Project Title ​和​App Name。

  5. 請確定已標示​ Include Runtime ​核取方塊。

    已選取Adobe Developer Console範本的App Builder專案建立 {width="600" modal="regular"}

  6. 按一下​Save。

將API新增至工作區

將必要的API新增到您的Stage工作區，以進行事件管理和Commerce整合。

  1. 按一下​ Stage ​工作區，然後對每個API重複下列步驟。

    為API使用新增服務選項來暫存工作區 {width="600" modal="regular"}

  2. 按一下​ Add Service ​並選取​API。

  3. 選取下列其中一個API。 請對下列每個API重複此程式：

    • Adobe Services​篩選器：

      • I/O Management API
      • I/O Events API

    • Experience Cloud​篩選器：

      • Adobe I/O Events for Adobe Commerce API

  4. 按一下​Next。

  5. 按一下​Save configured API。

  6. 重複上述步驟，直到您將所有API新增至工作區為止。

    Workspace顯示所有必要的API，已成功新增 {width="600" modal="regular"}

設定Adobe I/O CLI

將Adobe I/O CLI連線到您的組織、專案和工作區。

  1. 清除任何現有設定：

    code language-bash 
    aio config clear

  2. 使用Adobe I/O CLI登入：

    code language-bash 
    aio auth login -f

  3. 使用下列每一個命令選取您的組織、專案和工作區：

    code language-bash 
    aio console org select
    code language-bash 
    aio console project select
    code language-bash 
    aio console workspace select

    終端機顯示Adobe I/O CLI組織專案和工作區選擇 {width="600" modal="regular"}

複製入門套件

為您正在建置的擴充功能複製以下Commerce starter kit存放庫之一，並準備您的專案：

整合入門套件：

git clone https://github.com/adobe/commerce-integration-starter-kit.git extension
cd extension

結帳入門套件：

git clone https://github.com/adobe/commerce-checkout-starter-kit.git extension
cd extension
整合入門套件

建立.env檔案

建立您的環境設定檔：

code language-bash 
cp env.dist .env

在文字編輯器中開啟.env檔案，並新增下列OAuth認證：

code language-bash 
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
OAUTH_TECHNICAL_ACCOUNT_ID=
OAUTH_TECHNICAL_ACCOUNT_EMAIL=
OAUTH_ORG_ID=

按一下工作區上的「Credential details」索引標籤，從Developer Console的「OAuth Server-to-Server」頁面複製這些值。

Adobe Developer Console中的 OAuth伺服器對伺服器認證頁面 {width="600" modal="regular"}

新增Commerce設定

將下列Commerce執行個體詳細資料新增至您的.env檔案：

code language-bash 
COMMERCE_BASE_URL=
COMMERCE_GRAPHQL_ENDPOINT=

若要尋找這些值，請執行下列步驟：

  1. 導覽至Commerce Cloud服務執行個體。
  2. 按一下執行個體旁的資訊圖示。
  3. 將REST端點復製為COMMERCE_BASE_URL。
  4. 將GraphQL端點復製為COMMERCE_GRAPHQL_ENDPOINT。

設定事件前置詞

設定事件首碼的暫時值：

code language-bash 
EVENT_PREFIX=test

下載工作區設定

執行以下命令來下載工作區組態檔：

code language-bash 
aio console workspace download workspace.json

將工作區組態檔複製到scripts目錄：

code language-bash 
cp workspace.json scripts/

將本機工作區連線到遠端工作區

將您的本機專案連結至遠端工作區：

code language-bash 
aio app use workspace.json -m

終端機顯示成功的工作區連線與aio應用程式使用命令 {width="600" modal="regular"}

結帳入門套件

將本機工作區連線到遠端工作區

將您的本機專案連結至遠端工作區。 從專案根目錄（extension資料夾），執行：

code language-bash 
aio app use --merge

出現提示時，選擇使用您在設定Adobe I/O CLI時所選取之組織、專案和工作區的選項。 這會將工作區設定寫入您的應用程式中，以便部署和本機開發使用該工作區。

終端機顯示成功的工作區連線與aio應用程式使用命令 {width="600" modal="regular"}

安裝擴充性AI工具

此程式會建立MCP組態(.<agent>/mcp.json)、技能目錄(.<agent>/skills/)，並將AGENTS.md新增至專案根目錄。 系統會提示您選擇入門套件、編碼代理程式和封裝管理員。

  1. 使用以下命令在extension資料夾中設定AI輔助開發工具：

    code language-bash 
    cd extension
    code language-bash 
    aio commerce extensibility tools-setup

    顯示AI擴充工具設定命令輸出的終端機 {width="600" modal="regular"}

  2. 安裝完成之後，請重新啟動編碼代理程式，讓它載入新的MCP工具和技能。 Commerce App Builder工具現在可在您的環境中使用。

    note note
    NOTE
    如果您看到開機套件找不到任何技能的警告，表示發生錯誤，這通常是因為安裝程式是在開機套件複製位置以外的資料夾中執行。 從aio commerce extensibility tools-setup資料夾（入門套件專案根目錄）執行extension，並在出現提示時選取適當的入門套件。

    終端機顯示設定了AI擴充性工具，並選取結帳啟動套件 {width="600" modal="regular"}

店面手動設定

本節說明如何手動設定Ratings擴充功能教學課程和其他店面教學課程的店面。

若要自動設定店面，請執行app-setup自動化設定區段中說明的命令，並選取AEM Boilerplate Commerce入門套件。

先決條件

若要完成評等延伸教學課程的店面區段，並在您的商店中顯示產品評等，必須執行下列專案。

複製店面存放庫

開啟終端機並複製存放庫：

git clone https://github.com/hlxsites/aem-boilerplate-commerce.git storefront
cd storefront

安裝相依性

安裝專案相依性：

npm install

安裝店面AI工具

在storefront資料夾中設定AI輔助開發工具。

從樣板專案的根目錄執行以下命令。 命令會將@adobe-commerce/commerce-extensibility-tools套件安裝為開發相依性、將技能檔案複製到代理程式的技能目錄中，以及設定MCP （模型內容通訊協定），讓您的代理程式可以存取Commerce檔案搜尋工具。

aio commerce extensibility tools-setup

指令會引導您完成兩個提示：

  1. 選取入門套件 — 選擇​AEM樣板Commerce。

  2. 選取編碼代理程式 — 從支援的代理程式清單中選擇您的代理程式。

recommendation-more-help
2a2029a1-b458-4706-b074-f9c0c06ca6bb