React Native应用发布至App Store后页面跳转出现白屏问题

• React Native开发的应用已正式发布至App Store，整体功能运行基本正常
• 异常表现：点击按钮通过React Navigation跳转其他页面时，页面先正常显示约0.5秒，随后直接变为空白页
• 复现特征：该问题仅在App Store下载的正式发布版本中出现，本地通过Expo运行的调试版本无法复现，调试全程未捕获到任何报错
• 白屏现象参考：

1. 先补全生产环境错误捕获 #

调试环境下很多错误被框架屏蔽、代码压缩混淆程度低，无法复现生产问题，先在应用入口文件最顶部加入全局错误捕获代码，打TestFlight包复现问题后拉取日志拿到具体错误栈：

// 注意这行必须放在所有导入的最顶部
import 'react-native-gesture-handler';
import { LogBox } from 'react-native';

if (__DEV__) {
  LogBox.ignoreAllLogs();
}

// 捕获全局JS运行错误
ErrorUtils.setGlobalHandler((error, isFatal) => {
  console.log('全局JS错误：', error?.stack, isFatal);
  // 可将错误写入本地存储，后续导出排查
});

// 捕获未处理的Promise异常
global.onunhandledrejection = (event) => {
  console.log('未处理Promise异常：', event.reason?.stack);
};

注意：import 'react-native-gesture-handler'必须放在入口文件第一行，这是React Navigation的硬性要求，很多人开发时漏加，调试环境因为Expo自动注入兼容逻辑不会出问题，生产环境就会触发原生容器渲染失败。

2. 排查导航相关依赖兼容问题 #

• 核对react-native-screens、react-native-gesture-handler、@react-navigation/*系列依赖的版本，必须和当前使用的Expo SDK版本完全匹配，版本不兼容是生产环境导航白屏的高发原因
• 检查跳转目标页面是否使用了动态导入（React.lazy、动态require），生产环境代码混淆后动态导入路径解析失败，会导致首屏加载完成后组件渲染失败白屏，可临时将目标页面改为静态导入验证
• 检查目标页面的副作用逻辑（useEffect、componentDidMount里的执行代码），是否存在仅在__DEV__分支赋值的变量，生产环境下该变量为undefined，调用时触发渲染崩溃

3. 排查构建配置问题 #

• 若项目开启了expo-updates，检查更新地址配置是否正确，首屏渲染完成后应用触发静默更新、热替换失败会直接导致页面白屏，可临时关闭更新功能打TestFlight包验证
• 若项目开启了Hermes引擎，可临时关闭Hermes打release包验证，部分旧版导航依赖和Hermes字节码编译存在兼容问题，会出现渲染后JS执行崩溃
• 本地打和App Store配置完全一致的release包，连接Xcode查看设备原生日志，确认是否是原生层崩溃导致渲染容器被销毁，debug模式下调试器附着会改变原生崩溃触发条件，导致问题无法复现

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