疑難排解自訂擴充功能
本文針對建立自訂擴充功能時最有可能遇到的問題，提供一些解決方案，大致依照開發期間發生問題的順序進行。
快速檢查清單
如果某些功能無法運作，請先確認下列事項：
-
Node.js的版本為18或20 (
node --version)。 -
您已登入(
aio login)且使用正確的組織/專案/工作區(aio console where)。 -
擴充點名稱完全相符，包括版本：
fusion/nav-organization/1。 -
getWidget()中的url符合您應用程式中的路由。 -
您可見的UI呼叫
attach({ id })。 -
您在Fusion中檢視一組正確的擴充功能：
- 若要檢視Stage組建，請部署到Stage，並在Fusion設定檔中開啟Stage擴充功能開關（「產品設定> Fusion設定檔>偏好設定」）。
- 若要檢視已發佈的擴充功能，請部署至生產環境並取得核准。
錯誤1060：「擴充功能點不存在」
完整訊息： aio app deploy期間CoreConsoleAPISDK ... 1060: Extension point 'fusion/nav-organization/1' does not exist。
含義：您的Adobe組織尚未啟用Fusion擴充點（「已上線」）。 Adobe會在部署時驗證擴充功能點存在於貴組織的目錄中。 不是您的程式碼或YAML有問題。
修正：要求Fusion團隊加入您IMS組織的擴充點（fusion/nav-organization/1和/或fusion/nav-team/1）。 當您要求上線時，請包括：
- 您的IMS組織ID (
XXXX@AdobeOrg)， - 您所需的延伸點，
- 您的 Developer Console專案和工作區 名稱。
一旦確認上線，請重新執行aio app deploy。
「正在等待來自目標iframe的初始訊息」/面板永遠旋轉
表示： Fusion已開啟您可見的UI，但未完成交握，因此Fusion逾時。
常見原因：
attach只存在於註冊元件中，不在可見的Widget中。getWidget()中的url指向轉譯 註冊 元件（或空白頁面）而不是您的Widget的路由。- 傳遞至
attach的id與register中使用的id不同。 它們必須相同，所以兩者都保留在Constants.js中。
修正：確定您的 可見 元件呼叫attach({ id })：
useEffect(() => {
attach({ id: extensionId }).catch(console.error);
}, []);
如需詳細資訊，請參閱建置自訂擴充功能UI。
導覽按鈕未出現在Fusion中
如果您的自訂擴充功能的導覽按鈕未出現在Fusion中，請依序檢查下列專案：
- 您所檢視的擴充功能是否正確組合？ 依預設，Fusion只會顯示已部署到生產環境並核准的已發佈擴充功能。 如果您正在測試Stage組建，請在Fusion設定檔（「產品設定」>「Fusion設定檔」>「偏好設定」）中開啟Stage擴充功能開關，然後重新載入。 階段專案標籤為（階段）。
如需詳細資訊，請參閱發佈您的自訂擴充功能。 - 是撤銷還是撤銷？ 已撤銷或撤銷的擴充功能在Fusion中停止顯示且沒有錯誤。 如果先前執行的按鈕消失，在尋找程式碼問題之前，請先確認該按鈕在Adobe Exchange中仍為作用中。
- 是否已部署到正確的工作區？ 部署至您實際載入的工作區，也就是使用中繼測試開關時的中繼工作區。
- 是否已部署至正確的組織？ 使用您部署至的相同 IMS組織中的帳戶登入Fusion。
- 它是否在正確的區段中？
fusion/nav-organization/1顯示在 組織 下；fusion/nav-team/1顯示在 團隊 下（您必須先選取團隊）。 - 是否有擴充點名稱拼寫錯誤？ 它必須正確地讀取
app.config.yaml和資料夾的ext.config.yaml包含路徑中的fusion/nav-organization/1。
按鈕出現，但面板為空白
如果按鈕出現但面板為空白，請檢查下列專案：
- 路由不符：來自
getWidget()（例如/index.html#/my-widget）的url必須符合App.js中的<Route>。 不相符的專案會載入不含元件的頁面。 - JavaScript錯誤：請開啟瀏覽器的開發人員工具(F12) > 主控台標籤，並尋找來自iframe的錯誤。 修正回報的錯誤並重新部署。
- 標題遺失/重複：
getWidget()中的hideWidgetHeader控制Fusion是否在您的UI上方顯示標題。 如果您轉譯自己的標頭，請將其設為true。
iframe已封鎖（內容安全性原則/「拒絕框架」）
Fusion只允許在Adobe的App Builder CDN (*.adobeio-static.net)上託管的擴充功能，預設為aio app deploy放置您的檔案。 如果您將UI託管在其他位置，例如自訂網域，Fusion會拒絕載入它。 透過記錄的App Builder部署，或詢問Fusion團隊您的網域是否可以加入允許清單。
內容空白或過時
- 載入後立即清空：在
attach解析後讀取內容，而不是之前。 在此之前，會顯示「連線……」狀態。 - 當使用者切換組織或團隊時未更新：訂閱
contextchange事件並重新讀取處理常式中的金鑰。 如需詳細資訊，請參閱「建立自訂擴充功能UI」一文中的閱讀內容Fusion共用。 - 日期看起來錯誤：日期欄位會以ISO 字串送達，而非
Date物件。 將它們包裝在new Date(...)中。 請參閱Fusion內容參考文章中的日期。
呼叫API失敗並出現CORS錯誤
症狀：當您的UI直接呼叫Workfront/Fusion API時，瀏覽器主控台顯示「沒有’Access-Control-Allow-Origin’標頭」 （或要求遭到封鎖）。
修正：請勿從瀏覽器呼叫這些API。 透過您自己的App Builder 執行階段動作 （伺服器端，無CORS）路由呼叫，並讓訪客使用相對的同來源URL呼叫該動作。 如需詳細資訊，請參閱呼叫Workfront與Fusion API。
即使使用有效的權杖，Proxy動作也會傳回401
含義：透過require-adobe-auth: true，Adobe閘道會在您的動作執行前驗證呼叫，而且可以拒絕呼叫或卸除您的上游需求的自訂標頭，顯示為401。
修正：在動作 上設定require-adobe-auth: false且 自行強制執行授權。 動作中需要Authorization持有者、向上游轉送，並保留嚴格的目標允許清單。 請參閱require-adobe-auth： true與false。
融合GET /api/v3/hooks傳回400
含義：掛接端點是團隊範圍，因此teamId是必要的查詢引數。
修正：呼叫/api/v3/hooks?teamId=<team.id>。 勾點只會為作用中團隊返回。 若要涵蓋組織，請循環其團隊並合併。 相反地，案例接受organizationId。 請參閱Fusion v3 API細節。
aio個錯誤
aio: command not found： CLI未安裝或未安裝在您的PATH上。 重新執行npm install -g @adobe/aio-cli，然後開啟新的終端機。- 在全新的節點版本上建置/部署失敗：使用節點18或20 LTS。 非常新的、非LTS發行版本有時會中斷工具鏈。
- 「您不是開發人員」/看不到您的組織：您的Adobe組織管理員必須授與您此 開發人員 角色和App Builder存取權。 如需詳細資訊，請參閱設定UI擴充功能工具和帳戶。
- 401 /部署或探索期間的Token無效：您的工作階段已過期或您正在混合環境。 執行
aio logout然後aio login，確認aio console where，並部署至您正在載入的工作區。
收集支援資訊
收集這些資訊，以加快診斷速度：
- 您執行的確切命令和 完整 錯誤輸出。
- 您的IMS組織識別碼、專案和工作區。
- 您正在定位的延伸點。
aio app deploy是否成功，以及擴充功能是否為已發佈 （或者，對於Stage測試，Stage擴充功能開關是否開啟）。- 在Fusion中開啟面板時，瀏覽器主控台 (F12)發生任何錯誤。