文件AEM使用手冊

使用AEM Cloud移轉技能 using-cloud-migration-skill

最後更新： 2026年9月2日
  • 適用對象：
  • Experience Manager as a Cloud Service

建立對象：

  • Developer

此參考資料涵蓋各種支援的移轉模式、如何提供BPA發現，以及如何管理大型專案中的工作階段。 如需簡介和設定說明，請參閱概觀。

產生移轉Runbook migration-runbook

對於整個專案評估，從Runbook開始，而不是命名單一模式。 提示代理程式：

Review my code for AEMaaCS migration

此技能會在您的專案根目錄中產生​唯讀migration-runbook.md，而不會變更任何程式碼。 Runbook涵蓋​ 移轉技能可處理的每 ​個模式，並針對每個模式記錄：

  • 使用的偵測策略（BPA/CAM發現、分析器或啟發式內容掃描）
  • 受影響的檔案和每個模式的發現計數
  • 啟動模式移轉工作階段的複製貼上提示

由於Runbook也會在Markdown旁邊寫入發現專案快取，因此之後的模式工作階段會重複使用已發現的發現專案，代理程式不會重新掃描。 使用Runbook來排定要先處理哪些模式的優先順序，然後如下所述開始模式工作階段。

NOTE
Runbook是唯讀的。 它永遠不會編輯程式碼，且啟發式（非BPA）發現是確認候選符合專案，而非授權計數。

工作階段的運作方式 workflow-overview

每個移轉工作階段會依照此順序進行：

  1. 命名模式：指定一個模式（例如，scheduler）
  2. 提供發現：從BPA CSV檔案、透過MCP的CAM或特定檔案路徑
  3. 代理程式讀取轉換規則：此技能會先從同伴code-assessment技能讀取相關的轉換規則，然後再進行任何程式碼變更
  4. 第一批五個：代理程式最多可轉換五個發現專案並報告變更的內容
  5. 您檢閱並繼續：檢閱每個批次後，回覆continue以繼續下一批次

代理程式一次會處理一個模式和一個批次。 不會自動繼續；每個批次都需要您的確認。

移轉模式 patterns

排程器 scheduler

目標鎖定使用與AEMaaCS的無狀態、容器化執行階段不相容sling.commons.scheduler或Scheduler插入的Java類別。

BPA模式識別碼： scheduler

代理程式會使用@Designate將Scheduler插入的工作轉換為Runnable的@Component實作，將建構函式式排程器註冊取代為@Activate / @Deactivate生命週期方法。

ResourceChangeListener resource-change-listener

鎖定需要AEMaaCS更新的ResourceChangeListener或ResourceChange接聽程式實作。

BPA模式識別碼： resourceChangeListener

複製 replication

目標類別匯入com.day.cq.replication.Replicator或AEMaaCS不支援的相關復寫API。 代理程式會以ContentDistribution型對等項取代它們，並更新對應的OSGi服務參照。

BPA模式識別碼： replication

事件監聽器 event-listener

鎖定必須針對AEMaaCS事件處理語意更新的OSGi EventListener或EventHandler實作。

BPA模式識別碼： eventListener

事件處理常式 event-handler

鎖定需要針對AEMaaCS調整的同步OSGi EventHandler服務。

BPA模式識別碼： eventHandler

資產API asset-api

使用已棄用AssetManager、DAMEvent或不支援的DAM API的目標類別。 代理程式會將其取代為支援的AEM Assets API對等函式。

BPA模式識別碼： assetApi

HTL Lint (data-sly-test) htl-lint

鎖定在ui.apps下產生data-sly-test: redundant constant value comparison個Lint警告的HTL範本。 代理程式會透過直接掃描內容套件來探索受影響的範本；此模式不需要BPA CSV或CAM連線。

BPA模式識別碼： htlLint

NOTE
htlLint個發現未出現在BPA CSV匯出中。 當您啟動此模式的工作階段時，代理程式會透過直接檔案掃描來探索這些模式。

Cloud Manager的OSGi設定 osgi-cloud-manager

將ui.config中的OSGi設定轉換為與Cloud Manager相容的.cfg.json格式，並具有完整的環境特定處理。 這涵蓋兩項相關工作：

設定格式轉換

AEMaaCS需要將OSGi設定儲存為.cfg.json個檔案，並在runmode範圍的資料夾（config.author/、config.publish/、config.dev/等）中使用環境特定的設定。 代理程式：

  • 將現有.config、.cfg和XML格式的OSGi設定轉換為.cfg.json
  • 將包含作者和發佈特定值的設定分割為個別執行模式範圍的檔案
  • 根據OSGi中繼型別規格驗證屬性型別（字串、整數、布林值、陣列）
  • 標示Adobe擁有的PID以供手動檢閱，而非自動轉換

密碼和環境變數

將純文字密碼和環境特定值移出已提交的設定檔案，並以Cloud Manager預留位置取代它們：

  • $[secret:NAME]：用於密碼、權杖和其他敏感值
  • $[env:NAME]：針對每個環境不同的非敏感值（例如，服務URL）

對應的變數和秘密會在Cloud Manager中套用，並在執行階段插入；原始檔控制中不會儲存任何值。

IMPORTANT
代理程式絕對不會在交談中輸出秘密值。 所有敏感資料都會寫入授權移交檔案，供您透過Cloud Manager API或UI套用。

此模式不使用BPA CSV或CAM。 開始工作階段於：

Scan my config files and create Cloud Manager environment secrets or variables.

對話方塊移轉（舊版UI） dialog-migration

將傳統UI對話方塊轉換為Touch UI。 代理程式會處理兩個對話方塊子型別：ExtJS / Classic UI cq:Dialog定義已重建為Coral 3 _cq_dialog結構，而現有的Coral 2對話方塊已升級為Coral 3。 它也承載接聽程式optionsProvider、namePrefix和更新filter.xml。

BPA模式識別碼： lui （僅限對話方塊子型別）

若相同元件同時存在對話方塊和自訂Widget發現，請先執行自訂Widget移轉，以便在轉換對話方塊之前解析所有xtype參考。

Convert my Classic UI dialogs to Touch UI Coral 3.

自訂設計Widget （舊版UI） custom-design-widgets

移轉自訂ExtJS Widget （cq:Widget個具有自訂xtype值的定義）。 代理程式會清查Widget，然後將每個xtype對應到已知的Coral 3對等專案，或在沒有直接對應存在時搭配Granite UI表單元件。

BPA模式識別碼： cdw

Migrate my custom ExtJS widgets (CDW findings) from CAM.

範本現代化 template-modernization

將靜態範本轉換為可編輯的範本，並產生對應的AEM現代化工具重寫規則（結構、元件和原則規則）。 代理程式會以三個階段執行：探索範本並產生每個範本的計畫、依範本執行計畫範本，以及驗證產生的/conf結構。

此模式不使用BPA模式識別碼。 開始工作階段於：

Migrate my static templates to editable templates and generate the Modernize Tools rewrite rules.

BPA Source選項 bpa-source

來源
使用時機
BPA CSV檔案
您已從AEM執行個體或Cloud Acceleration Manager匯出CSV。 啟動工作階段時提供檔案路徑。
透過MCP的攝影機
您已設定AEM雲端移轉MCP。 代理程式會列出您的CAM專案、確認要使用的專案，並會直接擷取發現。 請參閱使用雲端移轉MCP。
手動檔案路徑
您要移轉不含BPA報告的特定檔案。 直接在您的提示中提供路徑。

MCP錯誤處理 mcp-errors

如果MCP連線傳回錯誤（包括找不到專案或驗證失敗），代理程式會停止並顯示錯誤。 它不會自動切換到另一個來源。 從已停止狀態，您可以：

  • 從顯示代理程式的清單中確認正確的專案
  • 提供BPA CSV路徑作為替代方法
  • 為手動移轉提供特定的Java檔案路徑

管理大型報表中的工作階段 large-reports

針對具有許多發現專案的BPA報表，逐批次方式可讓您逐步驗證：

  1. 複查每個批次的差異
  2. 使用模式範圍的認可訊息認可批次
  3. 回覆continue以開始下一個批次
  4. 重複此步驟，直到代理程式報告模式的所有發現專案都完成為止

每個認可一個模式​可讓您的Git歷程記錄保持可讀，並視需要輕鬆還原個別模式轉換。

NOTE
如果您在處理所有發現專案之前結束工作階段，請在新的工作階段中使用相同的模式和BPA來源重新啟動。 代理程式會從中斷的地方繼續。

Workspace範圍 workspace-scope

代理程式只會搜尋和編輯開啟的IDE Workspace資料夾中的檔案。 它不會掃描磁碟上的父目錄、同層級資料夾或其他位置。

如果BPA發現所參照的檔案路徑在工作區內不存在，代理程式會停止並告訴您哪些路徑遺失。 開啟正確的專案資料夾或明確提供路徑以繼續。

recommendation-more-help
experience-manager-cloud-service-help-main-toc