iOS 18.2 上 Flutter WebView 点击失效的来龙去脉

临时方案与回归

在 iOS 18.2 上，Flutter 团队试过好几种办法：toggle enabled、塞入 dummy recognizer、异步 dispatch、重建 recognizer 实例……最后发现把同一个 delayingRecognizer 实例移除再添加回去，能迫使 UIKit 刷新相关 recognizer 的关联，WebKit 内部识别器就能看到最新状态，点击功能恢复。

这个'移除再添加'的逻辑大概在 Flutter 3.29 里发布了。

但 iOS 18.2 高版本上，这个做法又捅了另一个篓子：Drawer、overlay 等需要阻止手势的场景完全失效了，触摸会穿透到下面的 WebView。

这比点不动还严重，直接导致误触和功能错乱。

于是 Flutter 在代码里加了条件判断，针对 iOS 18.2（@available(iOS 18.2.0, *)）不再执行那个'移除再添加'的绕过。可这样一来，之前靠它修好的'WebView 点不动'就又回来了。

很明显，这就是 iOS 18.2 上 WKWebView 自带的毛病，而且系统升级导致 WebKit 内部 recognizer 缓存行为变了。要彻底修好，还是得 Apple 出手。

怎么踩中这个坑

触发条件挺明确的：只要 WebView 上面出现过需要拦截触摸的 overlay 或 widget，就有可能中招。比如：

• 弹出一个半透明 ModalBarrier
• 打开一个 Drawer
• 显示一个 PopupMenu
• 调用 showDialog()
• 某些动画（Hero）内部也会临时创建 overlay 层

这些操作都会让 Engine 调用 delaying_recognizer.blockGesture(true)，WKWebView 内部的 recognizer 暂停响应。overlay 消失后，Engine 再调 blockGesture(false)，但 UIKit 没把 WKWebView recognizer 的响应恢复过来，问题就出现了。

高版本上那个移除再添加的做法，不仅刷新了依赖关系，还重置了某些全局 recognizer 的 delaysTouchesBegan / requiresFailureOf 配置——这些配置正好是 Flutter Engine 用来防止 overlay 点击穿透的。所以补丁一打，防穿透的逻辑就废了。

社区临时解决办法

目前社区里比较通用的规避方案是用 pointer_interceptor 来隔离 overlay 和 WebView 的事件竞争。核心思路是：在 iOS 上，只要 WebView 上方有视图并且发生过交互，WebView 就可能停止接受点击。所以用 PointerInterceptor 可以防止在和 WebView 上方的视图交互后，WebView 的点击中断。

// 判断当前是否在导航栈顶部
bool get _isTopOfNavigationStack => ModalRoute.of(context)?.isCurrent ?? false;

// 包裹 WebView 的 Widget
Widget buildWebviewWithIOSWorkaround(BuildContext context) {
  return Stack(
    children: [
      buildWebView(context),
      if (Platform.isIOS)
        Positioned.fill(
          child: PointerInterceptor(
            intercepting: !_isTopOfNavigationStack,
            // WebView 不在顶部 → 阻止点击穿透
            debug: false,
            child: const SizedBox.expand(),
          ),
        ),
    ],
  );
}

官方在做什么

一边和 Apple 推修复，一边也在想办法从外部绕过去。其中一个尝试是通过全新的 HitTest 策略来规避。

#176597 这个 PR 的大致想法是：既然大部分用例里平台视图只有一个重叠区域，那如果触摸位置落在 Flutter Widget 和平台视图之间的'重叠'范围里，就阻止平台视图上的所有 UIGestureRecognizer。具体做法：

• 新增一个拦截策略枚举 FlutterPlatformViewGestureRecognizersBlockingPolicyHitTestByOverlay
• 在 platform view 的触摸/hitTest 逻辑里，如果某个点落在 overlay 区域，就让 hitTest: 返回自己（self），而不是继续往底层 WebView 传
• 对于这种策略，blockGesture 方法变成空操作，因为拦截已经在 hitTest 层面做掉了
• 在 controller 更新 overlay 层时，把 overlay 视图引用记录下来，交给内部的 intercepting view，这样拦截逻辑就有 overlay 区域信息可用

也就是说，这套方案不依赖 delaying recognizer 的状态切换，而是用 hitTest 直接屏蔽底层点击。

但有个小缺点：如果多个重叠区域被合并成一个触摸阻挡区域，那个区域会是包含所有重叠的最小包围框。

做了一半，维护人员发现也许完整方案并不复杂，于是决定关掉这个临时 MVP：

完整方案依赖于 FFI 从 Flutter 手势竞技场同步查询来做决策，这又是另一个大改动。

所以现在推进到了 #177859。这个 PR 彻底放弃'延迟识别器'来阻塞 platform view 手势，改为在 iOS 端对触点做同步 hit-test，利用 FFI 从 framework 查询该手势是否应该被接受或阻止。它解决的就是 web_view、admob 这些平台视图点不动的问题，同时新增一个可选的 blocking policy（FlutterPlatformViewGestureRecognizersBlockingPolicyHitTest）。

调整细节：

• 把识别器从 delaying 类型改成直接 hit test 判断是否应阻止手势——根据触点是否落在应该被 platform view 拦截的区域来决定
• 用 FFI 在 native 层同步调用 framework 里的函数（_platformViewShouldAcceptGesture / platformViewShouldAcceptGesture），避免主线程互相等待死锁
• 新增 FlutterPlatformViewGestureRecognizersBlockingPolicyHitTest 策略，逐步采纳，不直接替换旧策略，降低回归风险

PR 涉及 engine 的 UI 层、iOS 平台 view / embedder 相关代码，把 hit-test 入口函数、FFI 绑定和 platform view 手势决策路径都串起来了。

这是个高风险改动，尤其是会动到 iOS 平台视图（platform view）的手势处理路径，影响 web_view、admob 和任何嵌入 UIView 的插件。官方建议插件作者（特别是官方 1P 插件）后续切换到新 policy。

当然 PR 还没合，眼下我们能做的规避还有：

• 别在 WebView 上方放需要拦截手势的复杂 overlay，尽量减少交互型 overlay；能避免覆盖 WebView 就不会触发
• 在 overlay 关闭后重建 WebView（重建 controller / reload），但闪烁体验不好

所以目前看来，路线是先完成 #176597，再实现 FFI 同步查询的完整方案。版本情况大概是：

• iOS 18.2 上因重叠控件导致 WebView 点击失效的问题，需要 3.29 及以上
• 在 3.35.4 之前，会出现触摸穿透；3.35.4 之后由于 cherry-pick revert，又退回点击无效
• 以上两个问题都可以用 pointer_interceptor 尽量规避
• 等官方内置 HitTest + FFI 方案发布

之前那次线程合并为 FFI 提供了基础，也给这次调整指了条新路，只是改动确实需要更谨慎一些。

参考链接

• https://github.com/flutter/flutter/pull/176597
• https://github.com/flutter/flutter/issues/175099
• https://github.com/flutter/flutter/pull/177859