iOS WebKit 开发陷阱：主线程阻塞与视频资源管理

在开发基于 Web 技术的 AR（增强现实）游戏时，我们通常依赖 Capacitor 框架在 iOS 的 WKWebView 中运行。这涉及到复杂的 Web 交互：Pixi.js 负责将摄像头画面渲染为 WebGL 纹理，MediaPipe 实时分析人体姿态，而 React 则管理页面的生命周期。

然而，iOS WebKit 环境极其敏感。在开发名为 AURADUEL 的 AR 游戏时，我们在切换相机和加载模型时遭遇了两个严重的“陷阱”，导致游戏画面黑屏。本文将深入剖析这些问题，并提供实用的修复方案。

陷阱一：Watchdog 误报“相机暂停”

问题描述

当你在 iOS 上点击切换相机按钮时，屏幕可能会冻结 8.5 秒，随后显示一个提示卡片：“Camera paused”（相机暂停）。

根本原因

这并非真正的相机暂停，而是主线程阻塞。系统中的 Watchdog（看门狗）机制负责监控摄像头状态，但它依赖于计时器。当主线程被阻塞时，计时器被排队等待执行。当 Watchdog 最终醒来时，它发现的时间戳比预期晚了 5 秒，于是错误地指责是相机导致了延迟。

实用修复方案

为了解决这个问题，我们需要引入更健壮的心跳机制：

• Watchdog 自身心跳：如果 Watchdog 长时间未运行，它不应直接报错，而应标记为“blocked”（阻塞），避免无谓的指责。
• 主线程心跳：设置一个短时器，对比主线程实际唤醒时间与预期时间。两者的差值即为 JS 被阻塞的时长。这能帮助开发者精准定位是哪段代码卡住了线程。

核心价值：对于任何实时性要求高的应用，单纯依赖系统回调是不够的，必须构建自己的心跳检测机制。

陷阱二：Pixi 场景销毁导致视频中断

问题描述

在相机切换过程中，React 组件会经历“卸载-挂载”的短暂生命周期。这导致 Pixi.js 场景被销毁。销毁场景会调用 VideoSource.destroy()，该方法会暂停视频源并清空 src。然而，此时摄像头和 MediaPipe 模型仍在使用同一个视频纹理，导致画面瞬间黑屏。

根本原因

这是一个典型的资源所有权冲突。Pixi.js 试图销毁它认为“拥有”的视频元素，但该元素实际上被摄像头 API 和检测器共享。Pixi 的清理逻辑是正确的（针对独占资源），但应用层的生命周期管理破坏了这种共享。

实用修复方案

我们需要调整 React 的渲染逻辑，而非销毁场景：

1. 保持挂载：让相机相关的场景在切换过程中保持挂载状态，不要卸载。
2. 实时处理：通过实时应用镜像或重帧逻辑来处理相机视角的变化，而不是重建整个场景。

核心价值：在处理共享资源时，任何拥有清理权限的组件，如果它误判了资源所有权，都可能破坏其他组件的运行。生命周期管理必须考虑底层资源的共享状态。

陷阱三：Promise 的假象

另一个陷阱与视频播放有关。在 iOS WebKit 中，play() Promise 的解析行为有时并不像开发者预期的那样直观。当视频流状态尚未完全就绪时，Promise 可能会提前解析，导致逻辑判断错误。这提醒我们在处理异步视频加载时，必须严格检查流状态，而不仅仅是依赖 Promise 的返回值。

总结

在 iOS WebKit 环境下开发 AR 应用，开发者不仅要关注 WebGL 和算法性能，更要深谙 JavaScript 事件循环和 DOM/Canvas 生命周期。通过引入心跳监控和优化资源管理策略，我们可以有效避免这些“黑屏”事故，提升应用的稳定性。