React Native + RNOH：一个 `lazyScreen()` 搞定 48 页面启动懒加载

技术栈： React Native 0.77 + React Navigation v6 + RNOH（React Native OpenHarmony）/ Android

核心文件： src/navigation/rootStackScreenRegistry.tsx

一句话结论： 把 registry 里的 require() 包进一个命名函数 lazyScreen()，48 个业务页面的模块求值就从"启动全量加载"变成"首次导航时才加载"------零依赖、零破坏性改动，实测启动阶段不再执行任何业务屏幕模块。

---

写在前面

我们的项目是一个基于 React Native 0.77 + RNOH（鸿蒙适配）的跨端政务应用，底部有 4 个 Tab，上面挂着 48 个业务详情页。导航用的是 React Navigation 的 Stack Navigator------所有 48 个页面平铺注册在同一个根栈上。

这种"扁平根栈"模式（我们称之为 Flat Root Stack ）带来了一个性能隐患：App 启动时，48 个页面模块全部被同步 require，模块顶层代码在启动阶段一次性执行。虽然 Hermes 引擎有字节码预编译加持，但这仍然不是最优解。

本文记录了我们从架构选型讨论，到最终用一个 3 行的 lazyScreen() 函数实现懒加载优化的完整过程。如果你也在用 React Navigation 且页面数量不少，这篇文章的思路或许可以直接复用。

---

一、分析 Root Stack 结构：一个 Navigator 挂了 48 个页面

RootStackNavigator 的结构很清晰：

RootStack (NavigationContainer)
├── Auth                          登录页，headerShown: false
├── Main                          MainTabs（底部 4 个 Tab），headerShown: false
│   ├── HomeTab
│   ├── MarketRegTab
│   ├── SmartRegTab
│   └── MeTab
├── /Home/FoodCertificate         header: 食品许可证到期
├── /Home/FoodUser                header: 食品从业人员健康证到期
├── ...                           共 12 个首页业务屏
├── /Market/DailyInspection       header: 日常检查
├── /Market/...                   共 34 个市场监管业务屏
└── /Me/PersonalInfo              header: 个人信息
    /Me/DevDemo                   功能演示（嵌套子栈）

关键设计：所有业务详情页都与 Main 并列挂在 Root Stack 上，而不是嵌套在各 Tab 的 Stack 里。

这意味着当你从 HomeTab push /Home/FoodCertificate 时，新页面是 push 到 Root Stack 上的------它覆盖整个 Main ，底部 Tab 栏自然消失。无需任何 tabBarStyle hack。

所有 48 个屏幕在 rootStackScreenRegistry.tsx 中统一注册，按 Tab 分组合并：

// rootStackScreenRegistry.tsx
const ROOT_STACK_SCREEN_REGISTRY = [
  ...ROOT_STACK_SCREENS_HOME_TAB, // 12 个
  ...ROOT_STACK_SCREENS_MARKET_REG_TAB, // 34 个
  ...ROOT_STACK_SCREENS_SMART_REG_TAB, // 0 个（预留）
  ...ROOT_STACK_SCREENS_ME_TAB, // 2 个
];

我们给这种模式起了个名字：Flat Root Stack（扁平根栈）。

---

二、Flat Root Stack 到底好不好？有没有更好的方式？

这是我们讨论最久的部分。我们从 React Navigation 社区常见的几种方案逐一分析。

方案 A：Per-Tab Stack（React Navigation 官方推荐）

每个 Tab 拥有独立的 Stack Navigator：

RootStack
├── Auth
└── Main (Tab Navigator)
    ├── HomeTab → HomeStack (列表 + 详情)
    ├── MarketRegTab → MarketRegStack
    └── MeTab → MeStack

这是 React Navigation 文档里最常见的模式。优点很明显------模块边界清晰，各 Tab 独立管理自己的导航栈。

但有一个致命问题：Tab 内页无法隐藏底部 Tab 栏。

在 Per-Tab Stack 里 push 一个详情页，底部 Tab 仍然显示。要隐藏它，要么：

// 方式 1：静态设置------整个 Tab 永久隐藏
tabBarStyle: { display: 'none' }

// 方式 2：动态判断------根据当前焦点路由切换
options={({ route }) => {
  const focusedRoute = getFocusedRouteNameFromRoute(route);
  return {
    tabBarStyle: {
      display: focusedRoute === 'SomeFullScreen' ? 'none' : 'flex',
    },
  };
}}

方式 1 太极端（整个 Tab 没 Tab 栏）。方式 2 可以工作，但过渡突兀------Tab 栏没有动画，直接消失/出现。

我们项目中 48 个业务页面几乎都需要全屏无 Tab，所以 Per-Tab Stack 对这个项目不适用。

方案 B：Tab Stack + Root 全屏 Group

混合方案------每个 Tab 有自己的 Stack，同时需要全屏的页面放到 Root Stack：

RootStack
├── Auth
├── Main (Tab Navigator + 各自的 Stack)
└── [全屏业务页]
    ├── InspectionDetail
    └── PersonalInfo

看起来两全其美？但需要判断每个页面属于 Tab Stack 还是 Root Stack，增加决策成本。而且对我们项目来说，绝大部分页面都要全屏------退化后几乎等同于 Flat Root Stack，徒增复杂度。

方案 C：Feature-Based 嵌套 Navigator

按业务域拆分独立 Navigator（检查流程、投诉流程、指令流程......）。适合 100+ 页面的大型项目，对我们 48 个页面来说过度设计。

我们真的去实现了 Per-Tab Stack

光讨论不够，我们实际动手把 PersonalInfo 从 Root Stack 迁移到了 MeTab 的嵌套 Stack 里，完整走了一遍流程：

创建的文件：

• src/navigation/meStack.tsx --- MeTab Stack（native-stack，Android/iOS）
• src/navigation/meStack.harmony.tsx --- MeTab Stack（JS stack，HarmonyOS）

修改的文件：

• types.ts --- 新增 MeStackParamList，从 MeRootParamList 移除 /Me/PersonalInfo
• mainTabs.tsx --- MeTab 的 component 从 MeScreen 改为 MeStackNavigator
• rootStackScreenRegistry.tsx --- 移除 PersonalInfo 条目
• screens/Me/index.tsx --- 导航从 '/Me/PersonalInfo' 改为 'PersonalInfo'
• screens/Me/PersonalInfo/index.tsx --- Props 类型从 RootStackParamList 改为 MeStackParamList

总共 2 个新文件 + 5 个修改文件，只为了迁移一个页面。

然后尝试用 getFocusedRouteNameFromRoute 动态隐藏 Tab 栏：

<Tab.Screen
  name="MeTab"
  component={MeStackNavigator}
  options={({ route }) => {
    const focusedRoute = getFocusedRouteNameFromRoute(route);
    const hideTabBar = focusedRoute === 'PersonalInfo';
    return {
      title: '我的',
      tabBarIcon: ...,
      ...(hideTabBar ? { tabBarStyle: { display: 'none' as const } } : {}),
    };
  }}
/>

结论：能用，但不值得。

维度	Flat Root Stack	嵌套 Tab Stack
添加一个全屏页面	改 2 个文件	改 4-5 个文件
Tab 栏隐藏	✅ 天然覆盖	⚠️ getFocusedRouteNameFromRoute + tabBarStyle
Tab 栏过渡动画	✅ 页面滑入覆盖	❌ Tab 栏突兀消失/出现
类型维护	registry ↔ types	registry ↔ types + stack param list

嵌套 Tab Stack 更适合每个 Tab 有 10+ 内部页面、多个团队各自维护的场景。对我们来说，Flat Root Stack 更简单、更合适。

我们把实验代码提交到了 experiment/metab-nested-stack 分支作为记录，然后 revert 回 Flat Root Stack。

---

三、Flat Root Stack 的真正问题：启动全量 require

架构选定后，剩下一个实际问题------性能。

原始 registry 用的是 eager require()：

{
  name: '/Home/FoodCertificate',
  component: require('@/screens/Home/FoodCertificate').default as RootStackScreen,
  options: { title: '食品许可证到期' },
},

48 个屏幕 = 48 次 require() 在模块加载时同步执行。虽然这些 require() 只是触发模块顶层代码求值（import、函数定义、类声明），不会执行渲染、API 调用或 state 初始化，但在中端 Android 设备上仍然估计增加 100--400ms 启动耗时。

它真的会影响启动速度吗？

这是我们反复讨论的问题。几个关键事实：

1. Metro 打包机制 ：所有模块已经被打包进单个 JS 文件，require() 只是同步模块查找，不涉及网络 I/O
2. Hermes 字节码预编译 ：Hermes 在构建时将 JS 预编译为字节码，跳过运行时解析，减少 50-70% 的 JS 解析时间
3. 模块求值 ≠ 渲染 ：require() 触发的是函数定义和类声明，不涉及 JSX 渲染、useEffect 执行或 useState 初始化
4. 真正的启动瓶颈可能在别处：Redux PersistGate 恢复、NavigationContainer 初始化、原生模块加载

结论 ：对当前 48 个页面 + Hermes 的场景，eager require 的影响大概在 50-200ms 量级。不是致命问题，但会随着页面增长持续恶化。值得优化，但不紧急。

---

四、第一反应：包个箭头函数？

最直觉的做法------把 require() 包进箭头函数，延迟到首次导航时才执行：

component: () =>
  require('@/screens/Home/FoodCertificate').default as RootStackScreen,

运行时确实有效------模块延迟到 React 首次渲染该屏幕时才加载。

但 React Navigation 不答应：

⚠️ Looks like you're passing an inline function for 'component' prop
for the screen '/Home/FoodCertificate' (e.g. component={() => <SomeComponent />}).
Passing an inline function will cause the component state to be lost on re-render
and cause perf issues since it's re-created every render.

React Navigation 在 useNavigationBuilder.js 里有一段检测逻辑：

// React Navigation 源码（简化）
if (typeof component === 'function') {
  if (/^[a-z]/.test(component.name)) {
    console.warn("Looks like you're passing an inline function...");
  }
}

它检查 component.name------如果首字母是小写（匿名箭头函数的 name 是 ''），就输出警告。

虽然我们的 getter 函数是定义在模块级数组里的稳定引用 （不存在"每次渲染重新创建"的问题），但 React Navigation 不区分这个------只要是匿名箭头函数就警告。

48 个屏幕 = 48 条警告。不行。

---

五、最终方案：lazyScreen() 命名包装器

解决方案呼之欲出：返回一个大写开头的命名函数，让 React Navigation 的检测通过。

/**
 * 懒加载屏幕包装器：
 * 将 require 延迟到首次导航时才执行，减少启动开销。
 * 返回大写开头的命名函数，避免 React Navigation inline-function 警告。
 */
function lazyScreen(getter: () => RootStackScreen): RootStackScreen {
  function LazyScreen(props: Record<string, unknown>) {
    const Cmp = getter();
    return (Cmp as Function)(props) as React.ReactElement;
  }
  return LazyScreen as unknown as RootStackScreen;
}

为什么有效

四个关键点：

1. 延迟求值

require() 包裹在 getter 闭包里，只有当 React 首次渲染 LazyScreen 组件时才调用 getter()，触发模块加载。在那之前，LazyScreen 只是一个空壳函数。

2. Metro 缓存

Metro 的模块系统会缓存 require() 的结果。第一次调用执行模块顶层代码，后续调用瞬间返回缓存的 module.exports。所以 getter() 的开销只发生一次。

3. 命名函数绕过检测

LazyScreen 首字母大写。React Navigation 检测 component.name 时，/^[a-z]/.test('LazyScreen') 为 false，不触发警告。

4. 稳定引用，不丢 state

lazyScreen() 在 registry 数组定义时调用一次（模块加载阶段），返回的 LazyScreen 函数引用 thereafter 不变。React Navigation 拿到的始终是同一个组件引用，不存在"每次渲染创建新组件导致 state 丢失"的问题。

使用方式

改动极其机械------把每个 require() 包进 lazyScreen()：

// Before
component: require('@/screens/Home/FoodCertificate').default as RootStackScreen,

// After
component: lazyScreen(() =>
  require('@/screens/Home/FoodCertificate').default as RootStackScreen),

48 处同样的替换，无脑操作。

那 React.lazy 呢？

我们讨论过 React.lazy 是否更好。结论是：在 Metro + React Navigation 的场景下，React.lazy 没有优势：

维度	lazyScreen()	React.lazy
代码分割	❌ Metro 不做 code splitting	❌ Metro 同样不做（import() 被转为 require()）
需要 Suspense	❌ 不需要	✅ 必须包裹
React Navigation 兼容	✅ 返回 ComponentType	⚠️ 返回 LazyExoticComponent，类型不匹配
实现复杂度	3 行函数	需要额外 wrapper

Metro bundler 把所有模块打包进单个 JS 文件------import() 在 Metro 中会被 babel 转换为 require()，没有真正的 code splitting 。React.lazy 的核心优势（按需加载 JS chunk）在这里并不存在。

---

六、验证：在 RNOH（鸿蒙）上怎么确认生效

RNOH 平台没有 Chrome DevTools、没有 Reactotron、Metro 控制台看不到 console.log。怎么验证模块确实是延迟加载的？

我们用了一个简单粗暴但有效的办法------在目标屏幕模块的顶层放 Alert.alert()：

// src/screens/Me/PersonalInfo/index.tsx
import {Alert} from 'react-native';

// 这行代码在模块被 require() 时立即执行
Alert.alert('[TEST]', 'PersonalInfo module evaluated');

模块求值 = Alert.alert 执行。所以我们只需要观察 Alert 弹出的时机：

版本	Alert 弹出时机	说明
原始 eager require	App 启动后立即弹出	模块在启动时就被求值了 ❌
lazyScreen 版本	仅在首次导航到「个人信息」时弹出	模块延迟到首次导航才求值 ✅

实测结果：

• eager require 版本：登录进入首页的瞬间，Alert 立刻弹出------说明 PersonalInfo 模块在启动时就被加载了，用户根本还没点"个人信息"。
• lazyScreen 版本：启动、登录、浏览首页、切换到其他 Tab------全程无 Alert。直到点击「我的」→「个人信息」，Alert 才弹出。

lazyScreen 方案确实将模块求值延迟到了首次导航时，启动阶段不再执行任何业务屏幕模块。

---

七、完整改动清单

文件	改动	行数
src/navigation/rootStackScreenRegistry.tsx	添加 lazyScreen() 函数；48 个屏幕全部改用 lazyScreen(() => require(...))	+102 -99
src/navigation/rootStack.tsx	component prop 添加 as any 类型断言	+1 -1
src/navigation/rootStack.harmony.tsx	同上	+1 -1

as any 是因为 lazyScreen 返回的 LazyScreen 函数签名（(props) => ReactElement）与 React Navigation 期望的 ComponentType 不完全匹配------但运行时行为完全正确。

总共改动 3 个文件，业务代码零改动。

---

八、回顾：一个有趣的发现

讨论过程中我们一度认为 Flat Root Stack 存在"跨 Tab 回退异常"------从 HomeTab push 了一个 Market 页面，back 回到 HomeTab 而不是 MarketRegTab，用户可能困惑。

但仔细一想，这个问题在 Flat Root Stack 中物理上不可能发生：

1. HomeTab → push FoodCertificate → 底部 Tab 被覆盖
2. 此时用户看不到 Tab 栏，无法切换到 MarketRegTab
3. 用户只能：
   a. 按 back → 回到 HomeTab ✅
   b. 继续 push 另一个页面 → Tab 栏仍被覆盖

push 页面覆盖整个 Main（包括 Tab 栏），这既是 Flat Root Stack 的优点（天然全屏），也是它的天然保护机制------用户无法在详情页切换 Tab，因此不可能产生跨 Tab 的栈污染。

这个架构比它表面上看起来更优雅。

---

九、总结

我们做了什么：
  1. 分析了 Flat Root Stack 架构的优缺点
  2. 实际尝试了嵌套 Tab Stack 方案------结论：不值得
  3. 决定保持 Flat Root Stack，只优化启动性能
  4. 从 getter 函数 → 箭头函数警告 → lazyScreen() 命名包装器
  5. 在 RNOH 上用 Alert.alert 实测验证生效

最终方案：
  ✅ 3 行 lazyScreen() 函数
  ✅ 48 处机械替换
  ✅ 3 个文件改动，零业务代码改动
  ✅ 实测启动阶段零业务模块执行

Flat Root Stack + lazyScreen()------保持简单架构的同时解决了唯一的性能痛点。这可能是 React Navigation 项目中成本最低的启动优化之一。