Expo Router v3 iOS应用TestFlight白屏及Hermes报错排查求助

一、在Expo Go外捕获日志的方法 #

1. 模拟器/真机通过Xcode捕获日志 #

• 打开Xcode，点击顶部菜单 Window > Devices and Simulators，选择目标模拟器或已连接的真机。
• 切换到Console标签页，在搜索框输入应用名称或Hermes关键词，过滤出相关日志，实时查看启动过程中的报错信息。
• 也可在终端执行命令：npx react-native log-ios，实时输出iOS设备/模拟器的应用日志。

2. 代码中添加全局错误捕获 #

在应用入口（如app/_layout.tsx或index.js）添加全局错误监听，将错误信息存储或打印：

import { ErrorUtils } from 'react-native';
import AsyncStorage from '@react-native-async-storage/async-storage';

// 捕获未处理的JS错误
ErrorUtils.setGlobalHandler(async (error, isFatal) => {
  const errorInfo = `[${new Date().toISOString()}] ${isFatal ? 'Fatal' : 'Non-fatal'} Error: ${error.stack || error.message}`;
  await AsyncStorage.setItem('lastError', errorInfo);
  console.error(errorInfo);
});

// 启动时检查历史错误
AsyncStorage.getItem('lastError').then(err => {
  if (err) {
    console.log('Previous error:', err);
    AsyncStorage.removeItem('lastError');
  }
});

构建后启动应用，再通过Xcode日志或自定义开发客户端查看错误信息。

3. 使用自定义开发客户端调试 #

用expo-dev-client构建自定义开发客户端，在真机上获取调试日志：

• 执行npx expo install expo-dev-client
• 在eas.json中添加development配置：

{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    }
  }
}

• 执行eas build -p ios --profile development，安装到真机后可查看详细调试日志与错误栈。

二、最佳排查步骤 #

1. 优先解决Xcode本地的Hermes错误
   本地Hermes错误是核心线索，明确错误类型：

   • 语法错误：检查代码是否包含Hermes不支持的ES提案语法，或TypeScript编译产物的兼容性问题。
   • 模块缺失：确认依赖是否正确安装，查看EAS构建日志的依赖安装步骤，排查是否有依赖未被正确拉取。

2. 对比Expo Go与EAS构建的环境差异

   • 环境变量：验证EAS构建时的环境变量是否与本地一致（可在eas.json的profile中配置env字段，或通过eas secret管理）。
   • 依赖版本：执行npm list或yarn list，确认本地依赖与EAS构建使用的lock文件版本一致，避免版本不匹配问题。

3. 检查Expo Router v3路由配置

   • 确认app/目录下的文件命名符合路由规则，无拼写错误（如动态路由[id].tsx的格式是否正确）。
   • 检查_layout.tsx中的导航配置，是否存在错误嵌套、未正确导出的组件，或使用了废弃API。
   • 暂时注释非核心页面，简化路由结构后构建测试，逐步定位路由问题。

4. 禁用Hermes验证问题根源
   在app.json中切换JS引擎为JSC：

   {
     "expo": {
       "jsEngine": "jsc"
     }
   }
   

   重新构建preview版本，若不再白屏，说明问题源于Hermes兼容性：

   • 排查是否有依赖库不支持Hermes，需升级或替换该库。
   • 执行npx expo optimize重新优化Hermes字节码后再构建测试。

5. 逐步排查新增依赖
   回溯最近新增的依赖，逐个移除并构建测试，定位导致白屏的第三方库，重点排查涉及原生模块、字节码编译的库（如加密、图形处理类库）。

6. 检查EAS构建配置与日志细节

   • 查看eas.json中preview/production profile的配置，是否开启过度代码压缩（如minify: true导致代码被错误移除），或自定义Xcode配置与Expo 51不兼容。
   • 重新查看EAS构建日志，过滤warning关键词，白屏问题常源于构建时的未处理警告（如过时API、未解析模块）。

7. 验证启动初始化流程
   在应用最顶部（如index.js）添加console.log('App started')，通过日志确认应用是否正常启动，判断是初始化阶段报错还是路由加载阶段报错。若未打印该日志，说明JS代码未正常执行，需排查原生层问题（如Hermes引擎加载失败）。

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