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 调试日志或联系技术支持。