React Native Reusables 项目中 Web 端快速刷新失效问题解析

在 React Native Reusables 项目开发过程中，开发者可能会遇到 Web 端快速刷新（Fast Refresh）功能失效的问题。本文将深入分析这一问题的成因，并提供两种经过验证的解决方案。

问题现象

当开发者使用 Expo 启动 Web 开发服务器后，在浏览器中进行代码修改并保存时，页面无法实现预期的热更新效果。这一问题在 macOS 15.0.1 系统上的 Chrome 和 Arc 浏览器中均有出现。

问题根源

该问题实际上与 Expo 框架本身的一个已知问题相关。在默认配置下，Expo 的 Web 端快速刷新机制可能无法正确初始化，导致代码变更时无法触发页面更新。

解决方案

方案一：显式导入 Metro 运行时

在项目的入口文件（通常是 index.js）顶部添加对 @expo/metro-runtime 的显式导入：

import '@expo/metro-runtime';
import { registerRootComponent } from 'expo';
import { ExpoRoot } from 'expo-router';

export function App() {
  const ctx = require.context('./app');
  return <ExpoRoot context={ctx} />;
}

registerRootComponent(App);

这种方法直接确保了快速刷新所需的运行时环境被正确加载，从而恢复了热更新功能。

方案二：修改 package.json 配置

另一种更推荐的方式是修改 package.json 文件中的 main 字段配置：

{
  "main": "expo-router/entry"
}

这种方案利用了 expo-router 提供的标准入口点，不仅解决了快速刷新问题，还遵循了 expo-router 的最佳实践。

方案对比

两种方案各有优势：

1. 显式导入方案更加直观，便于理解问题本质
2. 修改入口配置方案更加符合 expo-router 的设计理念，是官方推荐的做法

对于大多数项目，特别是使用 expo-router 的项目，建议采用第二种方案，因为它不仅解决了当前问题，还能避免未来可能出现的其他兼容性问题。

实施建议

1. 对于新项目，建议直接采用第二种方案配置 package.json
2. 对于已有项目，可根据具体情况选择迁移方案
3. 修改后需要重新启动开发服务器才能生效

总结

React Native Reusables 项目中的 Web 快速刷新问题本质上是 Expo 框架的一个配置问题。通过理解问题成因并选择合适的解决方案，开发者可以恢复流畅的开发体验。建议开发者优先考虑使用 expo-router 的标准入口配置，这不仅能解决当前问题，还能为项目未来的扩展和维护打下良好基础。