React Native应用从API Level 30迁移至31的技术问询

一、具体迁移步骤 #

• 升级React Native版本到0.68及以上：API Level 31需要RN 0.68+的支持，可通过npx react-native upgrade命令升级，或手动修改项目配置文件对齐RN新版本的gradle设置。
• 更新Android项目API配置：
  • 在项目根目录的build.gradle中，将compileSdkVersion和targetSdkVersion改为31；
  • 模块级app/build.gradle中同步修改targetSdkVersion，同时确保minSdkVersion不低于RN要求的最低版本（一般为21）。
• 适配Android 12权限规则：
  • 添加POST_NOTIFICATIONS权限到AndroidManifest.xml，并在代码中主动申请该权限；
  • 调整位置权限逻辑，后台获取精确位置需配合前台服务权限。
• 修复Intent与PendingIntent问题：
  • 将隐式Intent替换为显式Intent（指定目标包名），避免被Android 12拦截；
  • 为所有PendingIntent添加FLAG_IMMUTABLE或FLAG_MUTABLE标记（根据是否需要修改Intent内容选择）。
• 全量测试：覆盖所有功能模块，重点验证原生依赖相关的功能是否正常运行。

二、迁移核心注意事项 #

• 权限行为变化：Android 12强制要求单独申请通知权限，未申请的话应用无法发送通知；后台获取位置的限制更严格，需结合前台服务使用。
• 后台启动限制：Android 12禁止应用从后台随意启动Activity，仅允许通知点击、用户交互触发等场景，需检查项目中是否有违规逻辑。
• 工具链兼容：API Level 31要求Android Gradle Plugin（AGP）版本≥7.0，Gradle版本≥7.0，需同步升级这两个工具，避免编译报错。
• 第三方依赖兼容性：优先排查带原生代码的依赖，确认其版本是否支持API 31，未适配的库可能导致编译或运行时异常。

三、是否需要更新所有依赖？ #

不需要全量更新，重点关注带原生Android代码的依赖（比如react-native-camera、react-native-fs这类）：

• 纯JS依赖无需刻意更新，除非其内部依赖了未适配API 31的原生库；
• 原生依赖需逐个核对版本日志，优先升级到官方标注支持API 31的版本，未维护的库可能需要自行修改源码适配。

四、原生依赖常见问题 #

• 废弃API报错：部分旧库使用了Android 12废弃的API（如旧版位置权限方法），会导致编译失败，需替换为新API。
• PendingIntent崩溃：未添加FLAG_IMMUTABLE/FLAG_MUTABLE标记的PendingIntent在Android 12上会触发运行时异常，需修改依赖源码添加对应标记。
• 权限缺失：依赖未适配POST_NOTIFICATIONS权限，导致通知功能失效，需在依赖的AndroidManifest.xml中添加权限，并在调用逻辑中补充申请代码。
• 后台行为被拦截：依赖尝试从后台启动Activity，被Android 12限制，导致功能异常，需调整逻辑为前台触发或通过通知跳转。

五、迁移难度评估 #

整体属于中等难度：

• 若项目使用RN 0.68+版本，且大部分原生依赖已适配API 31，仅需修改配置和少量权限适配，迁移流程顺畅；
• 若项目基于旧版RN，或存在大量未维护的原生依赖，需先升级RN版本，甚至手动修改依赖源码适配，难度会显著提升。

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