设置ARKit的WorldTrackingConfiguration为gravityAndHeading时出错求助

嘿，这个问题我之前做AR项目时也踩过坑！你看到的CMErrorDomain Code=102和ARError Code=102本质是同一个问题：ARKit依赖的方向传感器组合（磁力计+加速度计）无法正常工作，毕竟.gravityAndHeading模式需要设备通过指南针+重力来确定虚拟世界的绝对对齐方向，传感器出问题就会触发这个报错。下面是一步步的排查和解决方法：

一、先排查硬件与系统层面的问题 #

• 确认设备兼容性：.gravityAndHeading要求设备搭载A9及以上芯片（iPhone 6s/SE及以后，iPad Pro 2017及以后），老设备本身不支持这个模式，强行设置必然报错。
• 校准指南针：打开系统自带的「指南针」APP，如果弹出校准提示，按照提示画8字完成校准——磁力计偏移是触发这个错误的最常见原因。
• 远离磁力干扰源：周围的磁铁、无线充电器、大功率电器都会干扰磁力计，换个空旷无干扰的环境试试。

二、检查代码配置与权限 #

• 添加运动传感器权限：在Info.plist里必须添加NSMotionUsageDescription键，说明你需要访问运动传感器的原因（比如“需要使用传感器来对齐AR虚拟世界”）。没有这个权限，系统会直接禁用传感器访问，导致报错。
• 正确修改session配置：绝对不能在session运行时直接修改worldAlignment，必须先暂停session，重新创建配置再启动：

  // 正确的配置流程
  arView.session.pause()
  
  let newConfig = ARWorldTrackingConfiguration()
  newConfig.worldAlignment = .gravityAndHeading
  
  // 重置跟踪并移除现有锚点，确保配置生效
  arView.session.run(newConfig, options: [.resetTracking, .removeExistingAnchors])
  

• 避免session处于错误状态：如果session已经因为传感器错误失败，必须先重置再重新运行，不能直接复用之前的session实例。

三、添加错误 fallback 方案 #

为了提升用户体验，建议在session的错误代理方法里捕获这个错误，自动切换到仅依赖重力的.gravity模式（不需要磁力计），同时给用户提示：

func session(_ session: ARSession, didFailWithError error: Error) {
    guard let arError = error as? ARError else { return }
    
    if arError.code == .requiredSensorFailed {
        // 切换到 fallback 配置
        let fallbackConfig = ARWorldTrackingConfiguration()
        fallbackConfig.worldAlignment = .gravity
        
        session.run(fallbackConfig, options: [.resetTracking])
        
        // 给用户显示提示，比如用UIAlertController
        let alert = UIAlertController(title: "提示", message: "无法获取设备方向，已切换到仅重力对齐模式", preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "确定", style: .default))
        present(alert, animated: true)
    }
}

四、最后一步：排除硬件故障 #

如果上面的方法都没用，换一台符合要求的设备测试——如果其他设备正常，那大概率是当前设备的磁力计硬件损坏，需要联系苹果售后检修。

内容的提问来源于stack exchange，提问作者Josh