React Native升级compileSdkVersion至31后Android 12设备安装后无法启动

开发者阿泽

2026-8-9

React Native 升级 SDK 31 后 Android 12 真机无法启动的排查方案

以下是你可能遗漏的适配点，按优先级逐一排查：

检查所有组件的android:exported属性
除主Activity外，所有包含<intent-filter>的组件（其他Activity、Service、BroadcastReceiver、ContentProvider）都必须显式设置android:exported="true"或"false"。不少第三方SDK的内置组件（如推送、统计服务的Receiver）可能未适配，需在你的AndroidManifest.xml中手动补充该属性，必要时用tools:replace="android:exported"强制覆盖。
确认 React Native 版本兼容性
React Native 0.66 及以上版本才正式支持 Android 12（SDK 31），如果你的RN版本低于0.66，必须升级RN版本，否则底层适配缺失会导致真机启动失败。
升级 Gradle 插件（AGP）版本
compileSdkVersion 31 要求 Android Gradle Plugin（AGP）版本至少为7.0.0，检查android/build.gradle中com.android.tools.build:gradle的版本，确保升级到7.0.0或更高（如7.2.0），同时Gradle wrapper版本也要匹配（AGP7.0对应Gradle7.0+）。
统一 SDK 相关版本配置
确保android/build.gradle中以下版本统一：
```
compileSdkVersion = 31
targetSdkVersion = 31
buildToolsVersion = "31.0.0"
```
版本不一致极易引发兼容性问题。
替换 WorkManager 为稳定版
你使用的androidx.work:work-runtime:2.7.0-alpha05是测试版本，存在未知兼容性风险，建议替换为稳定版：
```
implementation 'androidx.work:work-runtime:2.7.1'
```
抓取真机启动日志定位问题
连接真机后，运行以下命令抓取启动时的错误日志：
```
adb logcat *:E | grep -i "AndroidRuntime\|你的应用包名"
```
即使控制台无报错，真机系统日志通常会记录启动崩溃的具体原因（如组件导出问题、权限缺失、依赖冲突等）。