React Native app-debug.apk模拟器正常真机白屏问题求助

问题描述 #

通过以下命令生成app-debug.apk：

./gradlew assembleDebug

该调试APK安装到真机后点击仅显示白屏，但Android模拟器中运行正常。

使用的依赖包 #

"@react-native-async-storage/async-storage": "^1.19.1",
"@react-native-picker/picker": "^2.4.10",
"@react-navigation/drawer": "^6.6.3",
"@react-navigation/native": "^6.1.7",
"@react-navigation/native-stack": "^6.9.13",
"axios": "^1.4.0",
"babel-plugin-module-resolver": "^5.0.0",
"formik": "^2.4.2",
"react": "18.2.0",
"react-native": "0.72.3",
"react-native-dotenv": "^3.4.9",
"react-native-gesture-handler": "^2.12.0",
"react-native-keychain": "^8.1.1",
"react-native-paper": "^5.9.1",
"react-native-picker-select": "^8.0.4",
"react-native-reanimated": "^3.3.0",
"react-native-safe-area-context": "^4.7.1",
"react-native-screens": "^3.22.1",
"react-native-vector-icons": "^10.0.0",
"react-redux": "^8.1.1",
"redux": "^4.2.1",
"redux-persist": "^6.0.0",
"redux-thunk": "^2.4.2",
"styled-components": "^6.0.5",
"yup": "^1.2.0"

已完成的配置修改 #

1. android/app/build.gradle：

apply from: "../../node_modules/react-native-vector-icons/fonts.gradle"
implementation project(':react-native-keychain') // 在dependencies块中添加

2. settings.gradle：

rootProject.name = 'projectName'
apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings)
include ':app'
includeBuild('../node_modules/@react-native/gradle-plugin')
include ':react-native-vector-icons'
project(':react-native-vector-icons').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-vector-icons/android')
include ':react-native-keychain'
project(':react-native-keychain').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-keychain/android')

排查与解决步骤 #

1. 查看真机错误日志定位问题 #

连接真机到电脑，执行以下命令捕获错误日志：

adb logcat *:E

白屏通常由JS加载失败、原生模块报错或权限缺失导致，日志会明确显示具体问题（比如模块找不到、语法错误、权限拒绝）。

2. 确保Bundle正确打包到APK中 #

直接运行./gradlew assembleDebug可能未自动包含JS bundle，手动生成后再编译：

npx react-native bundle --platform android --dev true --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res/

执行完后检查android/app/src/main/assets/目录下是否存在index.android.bundle文件，再重新编译APK：

./gradlew assembleDebug

3. 检查React Native Reanimated配置 #

Reanimated 3.x需要特定的babel配置，确保babel.config.js中插件顺序正确：

module.exports = {
  presets: ['module:metro-react-native-babel-preset'],
  plugins: [
    // 其他插件放在前面
    'react-native-reanimated/plugin' // 必须放在最后一位
  ],
};

4. 补充必要的Android权限 #

在AndroidManifest.xml中添加基础权限：

<!-- 网络权限（如果应用依赖网络请求） -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- react-native-keychain所需权限 -->
<uses-permission android:name="android.permission.USE_BIOMETRIC" />
<uses-permission android:name="android.permission.USE_FINGERPRINT" />

5. 清理缓存后重新编译 #

• 清理Node模块与Metro缓存：

rm -rf node_modules && npm install
npx react-native start --reset-cache

• 清理Android构建缓存：

cd android && ./gradlew clean && cd ..

重新生成APK：./gradlew assembleDebug

6. 检查Redux Persist配置 #

若Redux Persist的存储引擎初始化失败，也会导致白屏。确保配置正确：

import AsyncStorage from '@react-native-async-storage/async-storage';
import { persistStore, persistReducer } from 'redux-persist';

const persistConfig = {
  key: 'root',
  storage: AsyncStorage,
};

const persistedReducer = persistReducer(persistConfig, rootReducer);

7. 验证依赖版本兼容性 #

• 确认android/build.gradle中的minSdkVersion≥21（Reanimated 3.x要求）
• 若问题仍存在，尝试升级react-native-keychain到与RN0.72.3兼容的最新版本

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