React Native已安装react-native-gesture-handler仍提示模块未找到

问题场景 #

在React Native裸项目中安装@gorhom/bottom-sheet时，已按要求安装react-native-gesture-handler和react-native-reanimated，但在iPhone14 iOS模拟器运行App时出现以下错误：

react-native-gesture-handler module was not found. Make sure you're running your app on the native platform and your code is linked properly (cd ios && pod install && cd ..)

已执行的操作：

• 执行npm install react-native-gesture-handler
• 在根目录index.js中添加导入语句（确保是首行）：

// index.js
import 'react-native-gesture-handler';
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';

AppRegistry.registerComponent(appName, () => App);

• 在ios目录执行pod install
• 尝试过：
  • 按官方指引操作
  • 删除重装node_modules和ios/Pods
  • Xcode清理构建文件夹
  • 执行npx react-native link react-native-gesture-handler，但提示命令已移除（RN版本0.71.8）

版本信息：

{
  "@gorhom/bottom-sheet": "^4.4.6",
  "react": "18.2.0",
  "react-native": "0.71.8",
  "react-native-gesture-handler": "^2.10.2"
}

排查与解决步骤 #

1. 检查Podfile配置 #

打开ios/Podfile，确认target '你的App名称' do代码块内包含以下引用：

pod 'RNGestureHandler', :path => '../node_modules/react-native-gesture-handler'

若缺失则添加，之后重新执行cd ios && pod install && cd ..，并重启Xcode。

2. 验证Xcode项目依赖链接 #

打开ios/你的App名称.xcworkspace：

• 进入项目的Build Phases -> Link Binary With Libraries
• 确认存在libRNGestureHandler.a，若没有则点击+按钮搜索添加该库

3. 严格保证导入顺序 #

react-native-gesture-handler的导入必须是根文件的第一行，确保index.js中没有任何代码（如console.log、其他模块导入）在它之前。

4. 彻底清除缓存 #

执行以下命令清理所有缓存后，重启Metro服务和模拟器：

# 清除Node缓存
npm cache clean --force
# 清除Metro缓存
npx react-native start --reset-cache
# iOS端深度清理
cd ios
rm -rf Pods Podfile.lock
pod deintegrate
pod install
cd ..

5. 验证模块完整性 #

检查node_modules/react-native-gesture-handler目录是否完整，若目录缺失或文件损坏，执行以下命令重装依赖：

rm -rf node_modules package-lock.json
npm install

6. 尝试版本降级 #

RN 0.71.x与react-native-gesture-handler@2.9.x兼容性更稳定，可尝试降级测试：

npm install react-native-gesture-handler@2.9.0
cd ios && pod install && cd ..

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