React Native 版本升级指南

　　React Native 版本升级指南

　　觉得文章对你有用的话一定要记得点赞哦 ，谢谢你，这对我来说真的很重要！

　　一、磨刀不误砍柴工

　　这部分知识我认为是最重要的，毕竟版本更新是永恒的，操作流程却是不变的。

　　详细介绍各端构建工具前，我们抛开各种技术细节，从整个项目的生命周期出发，看看大部分产品是怎么做技术规划的：

　　理清一个技术产品的生命周期后，你就会对日常开发中配置文件有了整体的认知：那些又臭又长的配置项，乱七八糟的兼容写法，毫无美感的 DSL，最神奇的是这些七拼八凑的东西还能把项目跑起来，Build 成功的那一刻你一定会对这种人类奇迹发出由衷的敬佩之情——原来这就叫专业啊！

　　收一收澎湃的情绪，牢记上面的指导经验，我们下面开始讨论技术细节。

　　1.【Web 前端】项目配置

　　前端工程化一直是前端里面的热点，虽然一直很热，但是具体实现还是一团糟。个人认为原因主要有两点，一个是前端构建从无到有，相对而言基础薄弱；一个是社区推动，百花齐放的同时又没有统一标准。就拿现在前端的主要配置文件来说：

　　上面只是列出了几个主流配置，不出意外的话，现在你的项目里已经有 5 个配置文件了，在 JavaScript 这个前端万能脚本语言的粘合下，这些配置文件还可以互相引用互相耦合，复杂度搞成这样，开发体验还没有 iOS Android 的一半好。

　　如果你认为我只是单纯的批评前端那你就理解错了，我想表达的是，这么复杂的配置都能搞定，iOS Android 的项目配置还不是手到擒来？

　　2.【iOS】项目配置

　　iOS 项目主要有两个点：project.pbxproj 和 CocoaPods。这两块儿的知识了解后，升级 RN 就完全不虚了。

　　1️⃣project.pbxproj 与 Xcode

　　project.pbxproj 就是一个 iOS 项目的配置文件，从数据结构特点上有些像 JSON，年龄可以追溯到 NeXT，可读性基本为 0，每次 git 合并都是纯黑的噩梦。不信你瞅瞅下图，这是给人看的吗。

　　

　　project.pbxproj 代码

　　可读性这么差的东西能传下来，其实全靠 XCode 这个 IDE 给它续命。我们每次在 XCode 里修改的配置，例如 Build Settings 等选项，最后都会反映到 project.pbxproj 这个配置文件上，也算是一种另类 DSL 了。

　　project.pbxproj 相关的知识我推荐下面几篇文章，阅读后会让你对 iOS 编译打包流程有个更深的了解：

　　2️⃣ CocoaPods

　　CocoaPods 是一个负责管理 iOS 项目中第三方开源库的工具，目前主流 iOS 工程都是用 CocoaPods 管理第三方库的。

　　React Native 在 0.60 里终于用上了 CocoaPods，和 iOS 社区步调一致了起来。这样做的好处就是后续维护和迭代的压力会小很多，鬼知道我以前升级各种 iOS SDK 的日子是怎么熬过来的。

　　相对 project.pbxproj，CocoaPods 无疑简单了不少，写配置脚本的 Ruby 语言也比较清爽，Podfile 的可读性要高很多。

　　platform :ios, '9.0'<br />require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'<br /><br />target '项目名称' do<br />  pod 'React', :path => '../node_modules/react-native/'<br />  pod 'React-Core', :path => '../node_modules/react-native/React'<br /><br />  use_native_modules!<br />end<br />

　　CocoaPods 的学习资料可以参考下文，不够的话自行搜索即可：

　　CocoaPods 使用教程

　　3.【Android】项目配置

　　Android 的项目配置主要是由 gradle 文件控制的，gradle 文件又由 Groovy 这门 JVM 系的脚本语言书写。到这里思路就很明显了，我们只要了解一些 Groovy 的语法和 gradle 的写法，就能读懂和修改 Android 的配置文件了。在这里我推荐一些相关教程，读完后就会有个大致的了解：

　　学习了基础的语法后，再回到 Android 工程上来。Android 的项目配置主要由 3 个文件控制，升级时冲突较多的也是这 3 个文件：

　　个人认为 Android 的 Gradle 配置还是比较容易入门的，因为 gradle 文件有个好处，可以随意的添加注释。大家可以花点儿时间把每个配置项都加上注释，这样在升级改动过程中就不容易发怵。

　　4.RN 官方升级助手

　　React Native 官方在 2019 年 7 月 0.60 大版本更新时，推出了 Upgrade Helper 这个 Diff 小工具。通过这个工具我们可以方便的看出版本更新时各个配置脚本的改动，非常的方便。

　　

　　React Native Upgrade Helper

　　二、升级流程

　　RN 版本升级时，我的升级流程一般是这样的：

　　在更新过程中，个人建议 git commit 操作要尽量原子化，方便后续复盘和回滚，小心驶得万年船。

　　在我实际升级中，因为 React Native 0.59 到 0.60 有非常大的变动，并且业务较为复杂，升级 0.60 花了两个星期的时间：iOS 一周，Android 一周；0.61 和 0.62 的升级就比较简单了，大概一两个小时就可以升级好。

　　三、React Native 0.60 升级

　　2019 年 7 月 3 日 Facebook 官方发布了 React Native 0.60，这是一次非常大的版本更新，虽然没有添加新的功能，但是在底层上做了很多优化，向主流配置靠齐：

　　0.60 升级时一定要有耐心，不可能一次性成功的，建议参考 Upgrade Helper 和 Upgrade to React Native 0.60 这篇博文，我会对文中没有说明的地方进行补充。

　　升级前先确保相关第三方包已经是最新版本。

　　1.React Native

　　JavaScript 这里相对来说好升级一些，毕竟是前端程序员的主场。根据 Diff 差异升级版本号后，还需要注意以下几点：

　　1️⃣ 部分 RN 内置组件交给社区维护

　　NetInfo、WebView 和 Geolocation 从 React Native 中移除，交给 react-native-community 社区维护。所以我们需要修改 import 时的路径。

　　Slider、AsyncStorage、CameraRoll、Clipboard 等组件也有移除计划，这次升级也可以顺便迁移一下。

　　值得注意的是，react-native-webview 在一次更新中为了响应 App Store 政策，已经移除了 UIWebView，只支持 WKWebView。如果你做过移动端的适配，你肯定明白 WKWebview 对 cookie 支持不太友好，这里需要重点回归测试一下；另外一点是如果 RN 和 H5 网页是通过 postMessage 的方式交互，相关 API 也有一些不兼容更新，这里需要重点适配一下，具体细节可以看文档。

　　2️⃣ SwipeableFlatList 移除

　　SwipeableFlatList 是 React Native 在 0.5X 某个版本提供的侧滑删除列表组件，虽然一直没有官方文档中放出来，但是社区上已经有很多人在使用了。可能对这个组件的实现不太满意，官方在 0.60 里删除了这个组件。为了不让项目报错，我们可能需要把 SwipeableFlatList 相关的源码拿出来自己手动维护一下，有人把相关代码提出来维护了一个 npm 包——react-native-swipeable-lists，大家可以引入暂时过度一下。

　　2.iOS

　　0.60 版本的 React Native 支持 CocoaPods，2020 年了，RN 终于支持 CocoaPods 了，没有 CocoaPods 的时代，为了使用一些 iOS 第三方库，我们必须手动把库文件拖到主工程里，升级和维护非常不方便。因为 0.61 版本 CocoaPods 是唯一可选包管理方案，所以强烈建议直接升级使用。

　　1️⃣ 迁移到 CocoaPods & Autolinking 支持

　　迁移 CocoaPods 前，先在 CLI 里输入一下命令 unlink Native Modules：

　　react-native unlink<br />

　　unlink 后就要迁移到 CocoaPods 了。迁移前确保 Ruby 和 CocoaPods 已经安装成功，具体的安装过程不是本文重点就不展开了，没有安装的同学自行 Google 搜索。

　　我们在 ios 目录里新建一个文件 Podfile，在里面输入以下代码：

　　platform :ios, '9.0'<br />require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'<br /><br />target '项目名称' do<br />  pod 'React', :path => '../node_modules/react-native/'<br />  pod 'React-Core', :path => '../node_modules/react-native/React'<br />  pod 'React-DevSupport', :path => '../node_modules/react-native/React'<br />  pod 'React-RCTActionSheet', :path => '../node_modules/react-native/Libraries/ActionSheetIOS'<br />  pod 'React-RCTAnimation', :path => '../node_modules/react-native/Libraries/NativeAnimation'<br />  pod 'React-RCTBlob', :path => '../node_modules/react-native/Libraries/Blob'<br />  pod 'React-RCTImage', :path => '../node_modules/react-native/Libraries/Image'<br />  pod 'React-RCTLinking', :path => '../node_modules/react-native/Libraries/LinkingIOS'<br />  pod 'React-RCTNetwork', :path => '../node_modules/react-native/Libraries/Network'<br />  pod 'React-RCTSettings', :path => '../node_modules/react-native/Libraries/Settings'<br />  pod 'React-RCTText', :path => '../node_modules/react-native/Libraries/Text'<br />  pod 'React-RCTVibration', :path => '../node_modules/react-native/Libraries/Vibration'<br />  pod 'React-RCTWebSocket', :path => '../node_modules/react-native/Libraries/WebSocket'<br /><br />  pod 'React-cxxreact', :path => '../node_modules/react-native/ReactCommon/cxxreact'<br />  pod 'React-jsi', :path => '../node_modules/react-native/ReactCommon/jsi'<br />  pod 'React-jsiexecutor', :path => '../node_modules/react-native/ReactCommon/jsiexecutor'<br />  pod 'React-jsinspector', :path => '../node_modules/react-native/ReactCommon/jsinspector'<br />  pod 'yoga', :path => '../node_modules/react-native/ReactCommon/yoga'<br /><br />  pod 'DoubleConversion', :podspec => '../node_modules/react-native/third-party-podspecs/DoubleConversion.podspec'<br />  pod 'glog', :podspec => '../node_modules/react-native/third-party-podspecs/glog.podspec'<br />  pod 'Folly', :podspec => '../node_modules/react-native/third-party-podspecs/Folly.podspec'<br /><br />  target '项目名称Tests' do<br />    inherit! :search_paths<br />    # Pods for testing<br />  end<br /><br />  use_native_modules!<br />end<br />

　　上面这段代码，pod 开头的都是从 node_modules 目录导入 react-native 相关的官方代码。下面两行代码是实现 autolink 的功能：

　　require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'<br /><br />target '项目名称' do<br />  ...<br />  use_native_modules!<br />end<br />

　　Podfile 配置好后，就在 ios 文件夹下运行 pod install，安装相关依赖。

　　安装成功后会生成一个 xcworkspace 空间，这时候你需要退出当前的 xcodeproj 项目，打开 xcworkspace。

　　在 xcworkspace 里，首先有两个顶层文件夹，一个是你的 xcodeproj 项目，一个是 Pods 文件夹（左图）：前者包含着你的业务代码，后者管理者安装的第三方库文件。这时候需要手动把 你的项目/Libraries 目录下的 *.xcodeproj 文件手动删除（右图红框 ➊），因为他们已经存在于 Pods 文件夹里了（右图红框 ➋）。

　　

　　iOS目录变化2️⃣ 修改 Header Search Path

　　上一步修改了 React Native 项目的引用方式，但还有一个问题，那就是寻址的头文件路径并没有修改过来，我们可以观察下面两张图：

　　当时这个变化卡了我一天，而且这个变化是在 project.pbxproj 中的，非常难以阅读就忽略掉了。后来通过新建一个 RN 新项目发现了问题。解决方法是删除原来的 Header Search Path 内容，手动把新的路径添加进去。

　　

　　迁移前

　　

　　迁移后

　　上面两步做完后可以尝试 build 一下项目，大概率你会发现还是 build 不起来。因为错误原因千奇百怪我也无法一一覆盖，这里还是问 Google 比较方便。

　　3️⃣ 新增 Start Packager 脚本

　　到这一步假设你已经 Build 起来 iOS 项目了，这时候你会发现一个问题，之前 iOS build 成功后，会自动启动一个 node 服务器编译 javascript 文件，更新后并没有自动启动 node 服务器，需要我们手动 npm run start 启动 node 服务器，非常的不方便。

　　问题出在哪里呢？原因是在原来的构建方式里，Libraries 下的 React.xcodeproj 有个 Start Packager 脚本，这个脚本会在项目 build 成功后自动启动一个 node 服务器：

　　

　　原 StartPackager 位置

　　迁移到 Pods 后，这个脚本就没有了，需要我们在主工程里手动添加一下。添加方式也很简单，我在下图也标注好了，点击项目文件夹，在 TARGETS 的 Build Phases 里点击 ➕，再点击 New Run Script Phase 新增一个脚本区域，然后把下面的代码填写进去：

　　

　　新建 StartPackager

　　export RCT_METRO_PORT="${RCT_METRO_PORT:=8081}"<br />echo "export RCT_METRO_PORT=${RCT_METRO_PORT}" > "${SRCROOT}/../node_modules/react-native/scripts/.packager.env"<br />if [ -z "${RCT_NO_LAUNCH_PACKAGER+xxx}" ] ; then<br />  if nc -w 5 -z localhost ${RCT_METRO_PORT} ; then<br />    if ! curl -s "http://localhost:${RCT_METRO_PORT}/status" | grep -q "packager-status:running" ; then<br />      echo "Port ${RCT_METRO_PORT} already in use, packager is either not running or not running correctly"<br />      exit 2<br />    fi<br />  else<br />    open "$SRCROOT/../node_modules/react-native/scripts/launchPackager.command" || echo "Can't start packager automatically"<br />  fi<br />fi<br />

　　这个 Start Packager 脚本的位置也有些讲究，最好放在 Check Pods Manifest.lock 和 Compile Sources 之间，要不然启动 node 服务器时会导致报错。

　　4️⃣ 新增 LaunchScreen.storyboard

　　随着 iPhone 产品线的增多，iPhone手机的尺寸也多了起来，原来一个尺寸配一个 LaunchImage 的方式逐渐变的不再适用，这时候  官方建议用 LaunchScreen.storyboard 来制作启动屏，并且要求 2021 年所有 APP 都得改为此方案。

　　具体的配置网上有很多教程了，大家搜索参考配置就好。我个人参考了以下教程：

　　5️⃣ 修改 xcodebuild 脚本

　　如果项目之前有配置过自动打包脚本，因为这次升级迁移到 workspace，所以也得对原来的打包脚本做一些修改：

　　xcodebuild archive -project 项目名称.xcodeproj<br />

　　⬇️

　　xcodebuild archive -workspace 项目名称.xcworkspace<br />

　　关于 xcodebuild 可以参考这两篇文章：

　　3.Android

　　0.60 的 Android 更新主要是 3 点：

　　升级前先需要升级 Gradle 和 Groovy 的版本。具体细节参考 Upgrade Helper。

　　1️⃣ 升级到 AndroidX

　　AndroidX 的推进主要是 Google 官方受够了 Android 目前混乱不堪的 android.support ，用一个统一的 androidx 来代替。升级跟着 Android 官方文档走就行，我主要参考了以下文档：

　　迁移工作主要是修改 import 路径，工作量可能有些大，但心理负担较小，本质上就是改了个名字，问题不大。

　　2️⃣ Autolinking 支持

　　Autolinking 功能集成前先试试运行 react-native unlink，看看能不能自动取消链接。如果取消失败，就要自己手动删除旧的 link 代码，加入新的 Autolinking 代码。下面我以 react-native-svg 这个第三方库为例进行说明：

　　1.检查 android/settings.gradle，删除旧的 include 配置，加入下面新的代码：

　　rootProject.name = '你的项目'<br /><br />- include ':react-native-svg'<br />- project(':react-native-svg').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-svg/android')<br /><br />+ apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings)<br />include ':app'<br />

　　2.检查 android/app/build.gradle，删除旧的配置，文件的最后一行加入一行配置：

　　dependencies {<br />-   implementation project(':react-native-svg')<br />}<br /><br />+ apply from: file("../../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesAppBuildGradle(project)<br />

　　3.检查 MainApplication.java，删除旧的引用：

　　- @Override<br />- protected List getPackages() {<br />-   return Arrays.asList(<br />-     new MainReactPackage(),<br />-     new SvgPackage()<br />-   );<br /><br />+   @SuppressWarnings("UnnecessaryLocalVariable")<br />+   List packages = new PackageList(this).getPackages();<br />+   return packages;<br />- }<br />

　　值得注意的是，我们业务中很有可能会自己封装一些 Native Module，经过上面的修改后，导入 Native Module 的方式也要做相应的修改，这里可以参考官方文档 Android Register the Module： <p>+ import com.your-app-name.CustomToastPackage; //