Table of Contents

故障排查：內容不顯示/激活

在使用圖像雲識別過程中，可能遇到虛擬內容無法顯示或激活的問題。本文將提供系統性排查方法。需要提醒的是，大部分情況下圖像雲識別失敗的原因與本地識別失敗是完全一致的，可參考平面圖像跟蹤的 故障排查 章節。此處僅補充雲識別特有的問題與解決方案。

常見原因與排查方法

網絡連接問題

現象：識別請求發送後無響應，或返回錯誤碼。
排查方法：

  • 檢查設備是否聯網（Wi-Fi/4G/5G），嘗試打開網頁驗證。
  • 檢查應用是否開啓了聯網權限。
  • 在代碼中捕獲網絡錯誤日誌。
  • 在瀏覽器測試 CRS API 連通性（參考：健康檢查 | GET /ping）。

改善建議：

  • 應用內增加網絡狀態檢測，弱網時有提示。
  • 設置請求超時後重試或降級至本地跟蹤。

服務配置錯誤

現象：識別請求被拒絕，返回 Unauthorized 或 Invalid Key。
排查方法：

  • 檢查代碼中填入的 CRS API Key 和 Secret 是否正確。
  • 檢查代碼中填入的 Client-end URL 沒有填錯（如誤填成了 Server-end URL）。
  • 確認 License Key 已激活且未過期（在 EasyAR 官網賬戶中心查看）。

改善建議：

  • 使用 CRS 圖庫中的複製按鈕複製您的相關服務配置，確保填寫正確。

目標庫/應用配置錯誤

現象：某個目標圖像過去識別沒有問題，但現在識別請求失敗。
排查方法：

  • 通過 CRS API 獲取目標狀態，確認目標圖像是“已激活”狀態（"active":"1"）。
  • 檢查目標 ID 是否與代碼中完全一致（區分大小寫）。

改善建議：

  • 雲端圖庫有更新/改動時，確保應用的特定目標總是激活的。
  • 仔細的代碼覈查。

混合模式下的本地加載失敗

現象：雲端識別成功，但本地跟蹤未啓動，內容不顯示。
排查方法：

  • 確認本地 ImageTarget 加載時未拋出異常（查看日誌）。
  • 驗證 ImageTracker 是否已啓用。

改善建議：

  • 使用 try-catch 包裹本地加載邏輯，捕獲異常並重試。
  • 確保虛擬內容是 ImageTarget 的子物體，且未被禁用。

總結與最佳實踐

雲識別內容不顯示問題主要集中在網絡、服務配置、目標狀態三方面，混合模式還需關注本地加載環節。建議按以下順序優先排查：

  1. 檢查網絡連接，確認 CRS 服務連通性；
  2. 檢查 License、API Key/Secret、Client-end URL 等服務設置。
  3. 檢查 CRS 圖庫中目標圖像的狀態，確保圖庫與應用中的目標 ID 一致；

若問題複雜，可啓用 EasyAR 調試日誌或聯繫技術支持。