React Native升级后Metro无法解析模块问题求助

问题情况 #

将React Native从0.69.10升级到0.70.9，同步把Metro更新到v0.72.3后，运行应用时多个模块出现解析失败错误，涉及react-native-gesture-handler、react-native-screens、redux-form等。错误提示称找不到这些模块，但node_modules目录中确实存在对应模块，且升级前一切运行正常。错误信息如下：

error: Error: Unable to resolve module react-native-gesture-handler from /path-to-project/index.js: react-native-gesture-handler could not be found within the project or in these directories:
  node_modules
  ../node_modules
  ../../../../node_modules

已尝试但无效的方法 #

• 执行react-native start --reset-cache重置缓存
• 禁用Hermes引擎
• 清理iOS/Android缓存、删除node_modules后重新安装依赖
• 确认所有Metro相关包均为v0.72.3版本
• 执行rm -rf ${TMPDIR:-/tmp}/metro-*清理Metro临时缓存
• 通过resolutions字段将Metro强制升级至v0.76.4

可行解决办法 #

1. 修正Metro配置文件 #

打开项目根目录的metro.config.js，确保配置中的watchFolders和resolver设置正确，让Metro能正确识别本地node_modules路径：

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const path = require('path');

module.exports = mergeConfig(getDefaultConfig(__dirname), {
  watchFolders: [__dirname],
  resolver: {
    nodeModulesPaths: [path.resolve(__dirname, 'node_modules')],
    disableHierarchicalLookup: false,
  },
});

如果是单项目结构，以上配置即可；若为monorepo，需将所有依赖所在目录添加到watchFolders中。

2. 对齐依赖版本兼容性 #

React Native 0.70.x官方适配的Metro版本为0.72.x，随意跨版本升级到0.76.x易引发兼容性问题。先移除package.json中的Metroresolutions配置，再重新安装适配版本：

npm uninstall metro && npm install metro@0.72.3 --save-dev

同时检查react-native-gesture-handler等依赖是否适配RN 0.70.x，直接升级到最新兼容版本：

npm install react-native-gesture-handler@latest

3. 手动映射模块入口（针对个别模块） #

部分模块如redux-form可能因入口文件配置问题导致Metro无法识别，可在Metro配置中手动映射模块路径：

resolver: {
  extraNodeModules: {
    'redux-form': path.resolve(__dirname, 'node_modules/redux-form'),
  },
}

4. 清理全局依赖缓存 #

本地缓存残留可能引发问题，执行全局缓存清理后重新安装依赖：

• npm用户：npm cache clean --force && rm -rf node_modules package-lock.json && npm install
• yarn用户：yarn cache clean && rm -rf node_modules yarn.lock && yarn install

5. 检查原生端构建配置 #

• iOS：确认Podfile中已引入相关模块，执行cd ios && pod install后重新构建项目
• Android：检查settings.gradle中是否包含依赖的项目路径，例如：

include ':react-native-gesture-handler'
project(':react-native-gesture-handler').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-gesture-handler/android')

内容的提问来源于stack exchange，提问作者Le Thanh An