React Native Navigation 从0.64.1升级到0.74.1的完整指南

背景介绍

React Native Navigation (RNN) 是React Native生态中一个重要的导航库，随着React Native版本的迭代升级，RNN也需要相应更新。从0.64.1升级到0.74.1是一个较大的跨越，涉及多项重大变更，特别是Android平台从Java到Kotlin的转变。

主要变更点

1. 文件类型变更：MainActivity和MainApplication文件从Java(.java)变更为Kotlin(.kt)扩展
2. 继承关系调整：需要修改类继承关系以适应新的导航架构
3. 构建工具更新：Gradle和相关插件版本需要同步更新

详细升级步骤

1. MainApplication.kt文件修改

原Java文件需要转换为Kotlin实现，关键修改点包括：

// 替换原有的React Native导入
import com.reactnativenavigation.NavigationApplication
import com.reactnativenavigation.react.NavigationReactNativeHost

// 修改类继承关系
class MainApplication : NavigationApplication() {
    // 修改ReactNativeHost实现
    override val reactNativeHost = 
        object : NavigationReactNativeHost(this) {
            // 保留原有的getPackages实现
            override fun getPackages(): List<ReactPackage> {
                return PackageList(this@MainApplication).packages
            }
        }
    
    // 移除SoLoader.init调用
}

2. MainActivity.kt文件修改

Activity实现需要简化为继承NavigationActivity：

package com.your.app.package

import com.reactnativenavigation.NavigationActivity

class MainActivity : NavigationActivity()

3. Gradle配置调整

在android/gradle/wrapper/gradle-wrapper.properties中：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-all.zip

在项目级build.gradle中：

ext {
    buildToolsVersion = "34.0.0"
    minSdkVersion = 23
    compileSdkVersion = 34
    targetSdkVersion = 34
    ndkVersion = "26.1.10909125"
    kotlinVersion = "1.9.22"
    RNNKotlinVersion = kotlinVersion
}

4. 应用级build.gradle修改

确保添加RNN依赖：

implementation project(':react-native-navigation')

常见问题解决方案

1. 自动链接工具问题：当运行npx rnn-link时，可能会遇到找不到Java文件的问题。这是因为工具默认查找.java文件，而新版本使用.kt文件。可以临时修改node_modules中的路径匹配逻辑，将**/MainApplication.java改为**/MainApplication.{java,kt}。

2. Kotlin与Java混合问题：虽然MainActivity和MainApplication改为Kotlin实现，但RNN核心仍然是Java编写，这种混合使用是完全可行的。

3. 版本兼容性问题：确保使用JDK 17和匹配的Android SDK版本，避免因工具链不兼容导致的问题。

升级建议

1. 全新项目策略：对于大版本跨越升级，建议创建全新React Native项目，然后逐步迁移业务代码，这比直接升级更可靠。

2. 逐步验证：完成每项修改后，单独验证该部分功能，便于定位问题。

3. 社区资源利用：遇到问题时，参考社区已验证的解决方案，如本文提供的Kotlin实现方案。

通过以上步骤，开发者可以顺利完成React Native Navigation从0.64.1到0.74.1的升级，享受新版本带来的性能改进和功能增强。升级过程中遇到的具体问题可能因项目配置而异，但遵循这些基本原则可以大大降低升级风险。