React Native Expo恢复应用时出现‘Rendered fewer hooks than expected’错误

错误信息 #

Error: Rendered fewer hooks than expected. This may be caused by an accidental early return statement.

This error is located at:
    in ContextNavigator (created by ExpoRoot)
    in ExpoRoot (created by App)
    in App (created by withDevTools(App))
    in withDevTools(App) (created by ErrorOverlay)
    in ErrorToastContainer (created by ErrorOverlay)
    in ErrorOverlay
    in RCTView (created by View)
    in View (created by AppContainer)
    in RCTView (created by View)
    in View (created by AppContainer)
    in AppContainer
    in main(RootComponent), js engine: hermes

问题场景 #

• 错误在关闭/挂起（未退出）Expo Go应用并重新打开时触发，堆栈跟踪信息有限，难以定位。
• 推测原生IPA包中也存在同类问题（关闭应用后部分功能失效），暂未确认。
• 全局搜索项目（含node_modules）后，仅在./node_modules/expo-router/src/ExpoRoot.tsx中找到ContextNavigator和ExpoRoot相关内容。
• package.json中expo-router版本设置为latest，所有团队成员在不同开发机器和iOS测试设备上均遇到该问题，非设备特定问题。

已尝试的解决方案 #

• 在多台iPhone及iPhone模拟器上测试，问题复现
• Windows和Mac系统均存在该问题
• 删除node_modules并执行yarn install
• 删除.expo文件夹
• 运行npx expo start --clean

版本信息 #

$ npx react-native -v
11.3.6
$ npx expo --version
0.10.12
$ node --version
v18.17.0

排查与解决方案建议 #

1. 锁定expo-router稳定版本
   避免使用latest标签，其可能包含未修复的beta版bug，指定具体稳定版本（如"expo-router": "2.0.0"，请根据官方最新稳定版调整），然后执行yarn install重新安装依赖。

2. 检查组件中Hook的调用规范
   遍历项目中所有自定义Hook和组件，尤其是App组件、路由相关组件，确保：

   • 所有Hook都在组件最顶层调用，不嵌套在条件判断、循环或嵌套函数中
   • 不存在提前return导致部分Hook未执行的情况，比如：

     // 错误示例
     function HomeScreen() {
       if (!user) {
         return <Login />;
       }
       const [data, setData] = useState(null); // 该Hook在return之后，会导致Hook执行数量不一致
     }
     

3. 验证expo-router配置合规性
   检查_layout.tsx等路由配置文件是否符合官方规范，确保：

   • 路由组件中未在动态路由的条件分支中调用Hook
   • 未在路由上下文的条件渲染中错误使用Hook

4. 切换JS引擎测试
   在app.json中临时修改JS引擎为JSC，排除Hermes兼容性问题：

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

   修改后重新启动项目测试。

5. 升级Expo CLI版本
   当前使用的Expo CLI 0.10.12版本较旧，升级到最新稳定版：

   yarn global add expo-cli@latest
   # 或 npm
   npm install -g expo-cli@latest
   

   之后重新执行npx expo start --clean。

6. 检查AppState监听逻辑
   如果应用中监听了AppState（如后台恢复时的操作），检查相关逻辑是否在应用恢复时错误地触发了Hook的异常调用，比如在回调函数中调用Hook（违反Hook规则）。

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