执行react-native link react-native-gesture-handler命令报错怎么办

• React Native项目开发阶段，需完成react-native-gesture-handler的原生依赖关联，执行关联命令时直接抛出异常，该问题是修复其余开发异常的前置阻塞项，已尝试多种常规排查手段均未解决。
• 执行的关联命令如下：

react-native link react-native-gesture-handler

• 异常触发时机为命令运行后即时抛出，当前项目React全链路环境版本信息已做本地留存。

先讲最常见的报错原因：react-native link是RN 0.60版本之前的手动关联指令，0.60及以上版本已经默认带原生依赖自动关联（Autolinking）能力，手动执行link大概率会写入重复配置、触发版本不兼容报错，对着自己项目的RN版本选对应方案处理就行，不用瞎试重装环境的玄学操作。

项目RN版本 ≥ 0.60（绝大多数现有项目场景） #

• 第一步先清除错误link写入的冗余配置，执行反关联操作：

react-native unlink react-native-gesture-handler

• iOS端进入ios目录执行pod install完成原生依赖拉取，禁止加sudo执行pod指令，避免后续出现目录权限问题。
• 安卓端依次检查三个配置文件：android/settings.gradle、android/app/build.gradle、android/app/src/main/java/对应包名/MainApplication.java，如果存在手动写入的react-native-gesture-handler关联配置，全部删除，自动关联机制会完成依赖注入，无需手动写配置。
• 执行全量缓存清理后重启项目：

watchman watch-del-all
rm -rf node_modules
# 用yarn就执行yarn install，用npm就执行npm install
yarn install
# 清理安卓构建缓存
cd android && ./gradlew clean && cd ..
# 清理iOS构建缓存
rm -rf ios/build
rm -rf ~/Library/Developer/Xcode/DerivedData/*
# 按需启动对应端
npx react-native run-android
npx react-native run-ios

项目RN版本 < 0.60（需手动关联的老项目） #

• 先校验依赖完整性：如果node_modules目录下不存在完整的react-native-gesture-handler包文件，先重新安装对应依赖，注意版本要和当前老版本RN兼容：

# yarn用户执行
yarn add react-native-gesture-handler@1.10.3
# npm用户执行
npm install react-native-gesture-handler@1.10.3 --save

注：1.10.3是最后一个兼容RN 0.59及以下版本的稳定版，更高版本不支持老版RN的手动link逻辑。

• 不要用全局安装的老旧react-native-cli执行link指令，全局cli和项目内RN版本不兼容是link报错的高频诱因，改用项目本地的cli执行：

npx react-native link react-native-gesture-handler

• 如果上述命令依然报错，直接走纯手动关联，跳过link指令：
  • 安卓端配置：
    1. 打开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')
    

    2. 打开android/app/build.gradle，在dependencies代码块中追加：

    implementation project(':react-native-gesture-handler')
    

    3. 打开MainApplication.java，头部导入包：import com.swmansion.gesturehandler.react.RNGestureHandlerPackage;，在getPackages()方法返回的包列表中添加new RNGestureHandlerPackage()
  • iOS端配置：
    1. 用Xcode打开项目工程，右键Libraries目录选择「Add Files to 你的项目名」，选中node_modules/react-native-gesture-handler/ios/RNGestureHandler.xcodeproj添加到项目中
    2. 进入项目Build Phases配置页，在Link Binary With Libraries列表中添加libRNGestureHandler.a
    3. 终端进入ios目录执行pod install完成依赖拉取
• 所有配置完成后，同样执行前面提到的全量缓存清理操作，再重启项目即可。

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