AR.js在iPhone端运行异常的原因及解决方案咨询

以下是iOS端（含Safari、微信/各App内置WebView环境）AR.js相关故障的高频踩坑点和对应解决方式，都是实际开发中反复验证过的场景：

一、权限申请流程无法唤起、用户无法完成授权 #

• iOS对摄像头、运动传感器这类敏感权限有严格的触发限制：所有权限申请必须由用户的显式点击事件直接触发，页面加载自动调用、接口请求/setTimeout异步回调里触发权限申请，都会被系统静默拦截，不会弹出任何授权提示。别搞页面加载完自动初始化AR那套，必须把权限申请、AR初始化逻辑直接绑在用户手动点击的按钮回调上，点击事件和权限调用之间不要插任何异步等待逻辑，否则100%被拦。
• iOS 13及以上版本的设备方向、运动权限需要单独申请，不是开了摄像头权限就够。缺这步的话AR场景根本无法启动，也不会有报错提示，初始化前需要补权限判断逻辑：

if (typeof DeviceOrientationEvent !== 'undefined' && typeof DeviceOrientationEvent.requestPermission === 'function') {
  DeviceOrientationEvent.requestPermission()
    .then(state => {
      if (state === 'granted') {
        // 权限通过后再执行AR.js初始化
      }
    })
    .catch(err => console.log('运动权限申请失败', err))
}

• 检查环境协议：iOS只在HTTPS环境（或localhost本地调试环境）下允许唤起敏感权限，HTTP环境下会直接拦截所有权限申请，没有任何提示，测试前先把HTTPS证书配好。

二、页面AR按钮不显示 #

• 先查版本问题：AR.js 2.0之后的版本对iOS Safari存在已知的UI渲染兼容bug，很多人直接引latest版本会遇到按钮不渲染的问题，先把版本固定到1.7.8稳定版测试，80%的按钮不显示问题降版本就能直接解决。
• 检查视口配置：如果页面没加适配iOS的视口meta标签，AR.js生成的按钮会因为定位偏移跑到可视区域外面，看起来就像没显示。在页面head里补上：

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">

• 检查全局CSS冲突：如果项目里给button、div、canvas这类通用标签设了全局的display: none、opacity: 0、负z-index，会直接覆盖AR.js默认的按钮样式，把冲突的全局样式去掉，或者给AR生成的UI元素加更高优先级的样式修正即可。

三、点击VR按钮后页面阻塞卡死 #

• 这是iOS端最常见的兼容坑：AR.js默认优先走WebXR标准进入VR模式，但iOS Safari到现在都没做完整的WebXR支持，调用后会卡在实例初始化的死循环里直接锁死主线程。初始化的时候直接把WebXR关掉，强制走兼容模式就行：

const arSession = new ARjs.Session({
  sourceType: 'webcam',
  detectionMode: 'mono',
  webXR: false, // 关键配置：禁用WebXR，走兼容渲染模式
  vrMode: 'css3d', // VR模式强制用CSS3D渲染，避免WebGL上下文锁死
  canvasWidth: 640,
  canvasHeight: 480
})

• 额外排查点：iOS Safari对同时存在的WebGL上下文有数量限制（最多8个），如果页面上同时跑了其他WebGL实例（比如其他Three.js场景、粒子特效组件），切换VR模式的时候会触发上下文上限直接卡死，进入VR前先把其他无用的WebGL实例销毁即可。

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