设备不支持 ARCore 或特定 API 排查

问题描述

用户打开你的 AR 应用时遇到以下情况之一：

• 提示"您的设备不支持 ARCore"或类似信息
• 能打开但点击 AR 功能时崩溃
• 特定 API（Depth / Geospatial / Cloud Anchors / Augmented Faces）不工作

排查流程图

用户反馈 AR 不工作
    ↓
第一步：确认设备型号和 Android/iOS 版本
    ↓
第二步：检查设备在 ARCore 官方支持列表中吗？
    ↓ 是                                  ↓ 否
第三步：检查 Google Play Services for AR       这是正常情况，应用应该优雅降级
        是否已安装且版本足够新
    ↓
第四步：检查应用声明的 uses-feature
        和 checkAvailability() 返回值
    ↓
第五步：如果是特定 API 不支持
        用 session.isXxxSupported() 检测
    ↓
第六步：根据检测结果降级或提示用户

基础 ARCore 不支持

步骤一：检查支持列表

ARCore 官方维护了一个支持设备列表（Google Developers → ARCore → Supported Devices）。不在列表中的设备官方不保证能用，但实际上很多未列出的设备也能跑——Google 只是没测试过。

检查清单：

步骤二：Play Services for AR 问题

很多"设备不支持"其实是 Play Services for AR 没装或版本太旧：

val availability = ArCoreApk.getInstance().checkAvailability(context)

when (availability) {
    SUPPORTED_INSTALLED -> { /* 完全就绪 */ }
    SUPPORTED_APK_TOO_OLD -> {
        // Play Services for AR 版本太旧
        ArCoreApk.getInstance().requestInstall(context, true)
        // 触发 Google 商店更新
    }
    SUPPORTED_NOT_INSTALLED -> {
        // 没装，requestInstall 会弹出安装对话框
        ArCoreApk.getInstance().requestInstall(context, true)
    }
    DEVICE_NOT_SUPPORTED -> {
        // 真不支持，给用户友好提示
    }
}

步骤三：Manifest 声明冲突

<!-- 如果声明为 required，不支持的设备 Play 商店看不到 -->
<!-- 但如果声明了但设备应该支持却被过滤了... -->
<uses-feature android:name="com.google.ar.core" android:required="true" />

检查是否有其他 uses-feature 声明过度限制了设备范围（比如声明了 android.hardware.camera.flash 但你的 ARCore 实际不需要闪光灯）。

Depth API 不工作

问题：session.isDepthSupported() 返回 false

问题：Depth API 启用了但深度图是空的

// 检查深度图有效性
val depthImage = frame.acquireDepthImage()
val plane0 = depthImage.planes[0]

// 有些像素深度值为 0 或特定常量 = 无效
val isValid = depthValue > 0 && depthValue < 100f  // 合理范围

// 无效像素多的原因：
// 1. 摄像头没对准任何物体（纯天空）
// 2. 距离太近或太远
// 3. 光滑表面无法计算被动深度
depthImage.close()

被动深度 vs 硬件深度降级

// 自动模式会优先用硬件深度，没有就用被动深度
session.configure(
    Session.Config(context).apply {
        setDepthMode(Session.Config.DepthMode.AUTOMATIC)
    }
)
// 不需要手动区分模式

Geospatial API 不支持

问题：isGeospatialModeSupported() 返回 false

Geospatial API 在中国大陆不可用

这是最常见的 Geospatial 问题——Geospatial API 依赖 Google Street View 数据，中国大陆的街景数据由国内地图商提供，Google 无法访问。

解决方案：

• 检测到设备在中国时跳过 Geospatial API，降级到本地 SLAM + Cloud Anchors
• 或者在国内版本的应用中完全去掉 Geospatial 功能

Cloud Anchors 不工作

问题：托管/解析一直处于 PENDING 或超时

API Key 验证清单

Android：
1. Google Cloud Console → 创建 API Key
2. Key 限制为 Android 应用 → 输入你的应用包名
3. 限制 ARCore Cloud Anchor API 可访问
4. 把 Key 写入 AndroidManifest 的 meta-data
5. 确保使用的是这个 GCP 项目

iOS：
1. 同上步骤 1-3（Key 类型选 iOS）
2. 把 Key 写入 Info.plist 的 GARAPIKey 字段
3. iOS 应用的 Bundle ID 必须在 Key 白名单里
4. Cloud Anchors 在 iOS 上需要额外配置吗？（不需要）

Augmented Images 检测不到

调试技巧

用 ARCore Debug Overlay 诊断

session.configure(
    Session.Config(context).apply {
        setShowDiagnostics(true)
    }
)

屏幕上会显示：

• SLAM 跟踪状态（Good / Bad / Lost）
• 检测到的平面可视化
• 特征点云
• Session 更新耗时

版本确认

// 确认运行时 ARCore 版本
val arcoreVersion = ArCoreApk.getInstance().getVersionName(context)
Log.d("ARCore", "Running ARCore $arcoreVersion")

// 确认 Play Services for AR 版本
// 如果版本号很旧，让用户更新