在移动端跨端开发中，每次 iOS 大版本更新带来新的系统级 UI 特性时，往往也是跨端视图层与原生视图层摩擦最剧烈的时候。

近期，开发者 @__oQuery 在 X (Twitter) 上分享 了一个关于 iOS 26 / 27 的典型兼容性问题：在页面使用 scrollEdgeEffects 配合 RNSafeAreaView 时，React Native 视图层盖住了底层的真实原生列表，导致滚动边缘效果失效甚至界面全透明。

本文将对该问题进行完整复盘，并顺着 react-native-screens 和 @react-navigation/native-stack 的源码链路深入剖析其底层根因，最后记录我们在现有 React Native 项目中的实战排查过程与长期防御指南。

一、问题背景：社区遇到了什么 Bug？

1. 现象表现

该问题最初由开发者 @__oQuery 在推文中披露。在 iOS 26 及更高版本中，UIKit 引入了全新的滚动边缘效果（如 Liquid Glass 的柔和边缘模糊穿透效果）：

• 页面配置了 scrollEdgeEffects（soft / hard / automatic），本意是作用在聊天列表或滚动内容上，在滑到边缘时呈现柔和的半透明过渡。
• 但在包含自定义原生列表的混合页面中，效果却严重走样：
  • 系统设置一类界面默认退化变成了 hard（硬切边，没有边缘过渡渐变）；
  • 聊天列表等界面更糟，边缘渐隐直接消失，甚至容器直接变成全透明，列表内容无视边距直接顶到了导航栏或输入栏下方。

2. 为什么 iOS 26 和 27 都会触发？

这是同一套 API 在苹果系统演进过程中的连带表现：

• iOS 26：引入了 UIScrollEdgeEffect（包含 automatic、soft、hard 等样式）；
• iOS 27：进一步收紧了视图安全区和滚动边缘裁剪的默认表现；
• 当 React Native 的视图层级和安全区包裹逻辑与 iOS 26+ 的 edgesForExtendedLayout 叠在一起时，如果找不到真实的滚动视图，系统边缘渲染就会直接错位。

二、源码深剖：为什么 RN 视图层会“盖住”原生列表？

要理解这个 Bug 为何发生，我们需要扒开 react-native-screens 和 @react-navigation/native-stack 的底层源码。

1. RNSScrollViewFinder 的“单链遍历”陷阱

在 react-native-screens 中，负责为当前屏幕寻找滚动视图的核心类是 RNSScrollViewFinder。查看其 iOS 源码实现（ios/helpers/scroll-view/RNSScrollViewFinder.mm）：

+ (UIScrollView *)findScrollViewInFirstDescendantChainFrom:(UIView *)view
{
  UIView *currentView = view;

  while (currentView != nil) {
    if ([currentView isKindOfClass:UIScrollView.class]) {
      return static_cast<UIScrollView *>(currentView);
    } else if ([currentView.subviews count] > 0) {
      // ⚠️ 关键点：永远只取 subviews[0] 第一条链！
      currentView = currentView.subviews[0];
    } else {
      break;
    }
  }

  return nil;
}

请注意这一行：

currentView = currentView.subviews[0];

react-native-screens 为了性能，并没有做全树的广度或深度递归搜索，而是严格沿着当前视图的第一个子视图（subviews[0]）一直往下摸。

一旦你的组件结构如下所示：

<RNSScreen>
  <RNSafeAreaView> {/* subviews[0] */}
    <CustomHeader /> {/* subviews[0] -> 命中这个头部容器，查找在此终止！ */}
    <NativeChatContainer> {/* subviews[1] -> 真实的 UIScrollView 在这里，但完全被忽略 */}
      <ChatCollectionView />
    </NativeChatContainer>
  </RNSafeAreaView>
</RNSScreen>

或者即使 NativeChatContainer 位于 subviews[0]，但它是一个由 React Native 包装的原生 Fabric 组件（RCTViewComponentView），真正的 ChatCollectionView 封装在其内部子视图树中：

1. RNSScrollViewFinder 走到 RN 中间容器层，发现它不是 UIScrollView，向下又摸不到真实的 CollectionView，遍历提前退出并返回 nil；
2. 随后 RNSScrollEdgeEffectApplicator 找不到列表，或者系统将屏幕边缘效果错误作用到了外层宿主视图上；
3. 外层 RNSScreen 的原生效果层与 <RNSafeAreaView> 产生冲突，把真正的列表盖在下面，最终出现硬切边或全透明穿透。

2. RNSScrollEdgeEffectApplicator 的生效逻辑

当找到了 UIScrollView 时，react-native-screens 会通过 RNSScrollEdgeEffectApplicator.mm 真正操作 UIKit API：

+ (void)configureEffect:(UIScrollEdgeEffect *)edgeEffect
               withEnum:(RNSScrollEdgeEffect)effectEnum API_AVAILABLE(ios(26.0))
{
  if (@available(iOS 26, *)) {
    switch (effectEnum) {
      case RNSScrollEdgeEffectAutomatic:
        edgeEffect.hidden = false;
        edgeEffect.style = UIScrollEdgeEffectStyle.automaticStyle;
        break;
      case RNSScrollEdgeEffectHard:
        edgeEffect.hidden = false;
        edgeEffect.style = UIScrollEdgeEffectStyle.hardStyle;
        break;
      case RNSScrollEdgeEffectSoft:
        edgeEffect.hidden = false;
        edgeEffect.style = UIScrollEdgeEffectStyle.softStyle;
        break;
      case RNSScrollEdgeEffectHidden:
        edgeEffect.hidden = true;
        edgeEffect.style = UIScrollEdgeEffectStyle.automaticStyle;
        break;
    }
  }
}

可以看到，这套逻辑必须作用在真实的 UIScrollView / UICollectionView 实例的 topEdgeEffect / bottomEdgeEffect 上。一旦目标不对，效果立刻崩塌。

三、排查实战：我们的项目有没有用到这套组合？

在获悉社区这个踩坑案例后，我们立刻对当前运行在 React Native 0.86（Fabric 新架构）的应用进行了全方位的排查。

1. 业务代码检索

首先在 src/ 与 ios/ 全局搜索 scrollEdgeEffect / scrollEdgeEffects：

• 结果：0 处显式调用。项目中并没有在任何导航配置中手动开启过这个配置。

2. 发现依赖层的“静默默认值”

然而，在翻阅 @react-navigation/native-stack（7.18.10）源码时，我们发现了一个容易被忽视的细节：在 NativeStackView.native.tsx 中：

// @react-navigation/native-stack 内部源码
scrollEdgeEffects={{
  bottom: scrollEdgeEffects?.bottom ?? 'automatic',
  top: scrollEdgeEffects?.top ?? 'automatic',
  left: scrollEdgeEffects?.left ?? 'automatic',
  right: scrollEdgeEffects?.right ?? 'automatic',
}}

即便开发者在业务层没有显式传递 scrollEdgeEffects，React Navigation 也会默认给所有方向填上 'automatic' 并向下透传给 RNSScreen！

这意味着底层其实一直处于“随时触发”的状态。那为什么我们的应用在 iOS 26+ 上表现完全正常、没有发生视图被盖住或边缘异常呢？

3. 三道天然防线

比对社区案例后，我们梳理出了本项目未中招的三大核心原因：

防线一：统一采用 useSafeAreaInsets，零 <SafeAreaView> 组件

社区出问题的核心诱因之一是使用了 react-native-safe-area-context 的 <RNSafeAreaView>。

• <SafeAreaView> 会在原生视图层插入一个真实的 RNCSafeAreaView 原生容器节点，该节点会在原生层截断延伸布局，并干扰子视图链查找；
• 而我们在项目中全面禁止了 <SafeAreaView> 标签，全站统一使用 useSafeAreaInsets() Hook：

  // 推荐实践：纯 JS 层的尺寸计算，不产生额外的原生中间视图
  const insets = useSafeAreaInsets();
  return (
    <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
      {/* 滚动列表 */}
    </View>
  );

  在顶层仅保留一个 SafeAreaProvider 提供上下文，页面内全部在 JS 侧完成内边距样式计算，原生视图树极其扁平纯净。

防线二：全量基于标准 RN 列表，无内嵌的原生 CollectionView

• 出问题的项目是“混合列表”——外层是 RN，内层是自写的原生 UICollectionView 插件（如聊天气泡流），导致 RNSScrollViewFinder 顺着单链摸不到真正的滚动视图。
• 而我们项目中的书架、首页、书籍详情、搜索等模块，全部采用 React Native 官方标准的 FlatList / Animated.FlatList / ScrollView。在 Fabric 架构下，它们直接对应 RCTScrollViewComponentView，属于官方原生支持的标准对象，不存在“深层藏着原生列表”的情况。
• 另外，项目唯一的自定义 Fabric 原生组件是仿真翻页（ReaderPageCurlNativeView），其底层封装的是 UIPageViewController，基于手势页面切换控制器实现，本身不涉及滚动列表逻辑。

防线三：全站关闭原生 Header（headerShown: false）

• 本项目在 RootStack 和 MainTabs 中统一配置了 headerShown: false，全站使用统一风格的自定义 React 导航栏。
• 这从根本上切断了 UIKit 原生 UINavigationBar、edgesForExtendedLayout 与屏幕滚动视图之间的边缘拉伸交互，彻底避开了系统级 Liquid Glass 穿透计算异常的土壤。

四、经验总结与长期技术避坑清单

为了防止未来项目迭代或其他项目遇到类似问题，我们沉淀了以下几点关键原则：

1. 优先使用 useSafeAreaInsets 替代 <SafeAreaView>

• 原因：<SafeAreaView> 会向原生 View 树注入 RNCSafeAreaView 容器。在现代 iOS（尤其是 iOS 26+）收紧安全区和全屏手势的背景下，原生的嵌套安全区极易与导航器控制器产生布局冲突。
• 准则：用 useSafeAreaInsets() 获取状态栏和底部操作条高度，直接通过 padding / margin 应用在 React 样式中，保持原生层级干净。

2. 封装原生滚动列表组件时，必须主动绑定

如果你需要在 React Native 中封装复杂的高性能原生列表（如基于 UICollectionView 的复杂瀑布流或富文本聊天组件）：

• 不要指望 react-native-screens 能自动找到你的列表：因为它的 RNSScrollViewFinder 只能查到 subviews[0]。
• 正确姿势：在 Swift / Objective-C 侧，通过所属的宿主控制器主动将真实列表绑定给系统：

  // Swift 侧主动绑定当前控制器的内容滚动视图
  self.setContentScrollView(chatCollectionView)

  或者让封装的视图遵循 RNSContentScrollViewProviding 协议，显式暴露内部的 UIScrollView。

3. 注意 React Navigation 的默认透传行为

• 在升级 @react-navigation/native-stack 或 react-native-screens 时，务必了解依赖包对系统新特性的默认行为（如上文提到的默认传递 'automatic'）。
• 若未来业务需要开启原生导航栏（headerShown: true），且发现页面滚动到顶部时出现遮罩消失、边缘变黑等异常，可以在页面选项中显式关闭边缘效果：

  <Stack.Screen
    name="Detail"
    component={DetailScreen}
    options={{
      scrollEdgeEffects: {
        top: 'hidden',
        bottom: 'hidden',
      },
    }}
  />

五、结语

React Native 赋予了我们优秀的跨端开发效率，但其核心基石依然是底层的 UIKit / Android View。每逢苹果系统大版本迭代，新的视觉效果与安全区策略往往会在两者的“缝隙”中暴露出隐蔽的层级 Bug。

保持对底层视图树层级的敏感度、深入排查类库的默认实现细节，并在日常编码中坚守扁平化、无侵入的布局原则，才是保障大型移动应用在系统大版本跨越中平稳前行的最佳路径。

六、参考与延伸阅读

• X / Twitter: @__oQuery 关于 iOS 26/27 滚动边缘效果与 RNSafeAreaView 冲突的原帖
• Apple Developer Documentation: UIScrollEdgeEffect
• GitHub: software-mansion/react-native-screens (RNSScrollEdgeEffectApplicator 实现)
• React Navigation: Native Stack Navigator scrollEdgeEffects API 说明