React Native：macOS 初始化 Android 开发环境遇到的坑与总结

九幽归墟
862 阅读3分钟

在 macOS 上为 React Native (RN) 项目初始化 Android 开发环境是一项复杂的任务，涉及到多个工具和依赖的安装与配置。由于这种模式最复杂，许多开发者在这一过程中会遇到很多的坑。本文将分享我在 macOS 上进行 RN Android 开发环境搭建时遇到的常见问题及其解决方案，帮助其他开发者避免踩坑。

重要提示

Mac配置React Native开发环境，其实也没什么好说的，请先严格按照官网进行环境配置，地址：reactnative.cn/docs/enviro…，本文重点介绍遇到的坑。

1. adb相关的坑

问题 1：adb: command not found

在安装 Android Studio 和相关 SDK 之后，很多开发者发现 adb 等 Android 工具在命令行中无法识别。这通常是因为 Android SDK 的路径没有正确配置到环境变量中。

  • 解决方案：

    • Android SDK 安装在 macOS 的 ~/Library/Android/sdk 目录中。你需要将以下内容添加到 ~/.zshrc（或 ~/.bash_profile）中： 
      export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
    • 然后运行 source ~/.zshrc 来加载新的环境变量。

  • 经验总结：

    • 如果遇到 adb: command not found 或其他类似问题，大概率是没有正确配置 SDK 路径。
    • 重启终端后再次验证 adb devices 是否可以识别设备，如下：

    image.png

    上图说明识别到模拟器设备，注意：若只有前2行，没有第3行device，说明还是没有识别到任何设备。

问题2: adb devices 显示设备为 unauthorized

当你通过 USB 连接 Android 设备并运行 adb devices 时，设备状态显示为 unauthorized。这通常意味着设备没有正确授权 USB 调试。

  • 解决方案：

    • 在 Android 设备上，确保启用了 开发者模式 和 USB 调试。
    • 当设备连接到电脑时，检查设备上是否弹出授权对话框，点击“允许”。
    • 如果问题依然存在，可以尝试再次重新连接USB，直到弹出对话框，确保 USB 调试已授权。
    • 若在macOS上连接Android 真机设备，还需要安装一个工具：Android File Transfer（可在Mac App Store上查找并安装）

    image.png

问题3: adb connect连接失败

你在运行 Android 项目时遇到的 failed to connect to 192.168.1.3:38431 错误，通常表示设备或模拟器未能与开发服务器成功连接。

  • 原因：

    • 网络配置问题
    • IP地址，端口是否正确

  • 解决方案：

    • 如果你使用的是物理设备，通过 USB 连接，进入 开发者选项，开启 USB 调试
    • 如果你使用的是 Wi-Fi 连接，检查设备和电脑是否都连接到同一个 Wi-Fi 网络。
    • 查看手机上的无线调试地址和端口，确保你的无线调试是打开的状态，端口号38431是否正确，连接是否超时，若超时重新点击连接，端口会发生变化，需要修改成新的端口

2. Android SDK 相关问题

问题1：No installed build tools found

在安装 Android Studio 时，有时开发者会跳过某些 SDK 工具的安装，导致运行 npx react-native run-android 时出现 SDK location not found 或 No installed build tools found 的错误。

  • 解决方案：
    • 打开 Android Studio -> SDK Manager，确保安装了以下 SDK 工具：
    • 具体按照RN官网安装 Android SDK，以下是笔者发文时的官网快照 image.png
问题2：error Failed to install the app

在安装 Android Studio 时，会默认安装最新的Android SDK，导致运行 npx react-native run-android 时出现error Failed to install the app. Command failed with exit code 1: ./gradlew app:installDebug -PreactNativeDevServerPort=8081 The me……

  • 原因：
    • Android Studio模拟器没有打开，也没有成功连接真机，就启动npx react-native run-android或yarn android命令
    • 其次，如果已经打开模拟器，遇到 error Failed to install the app 出现在编译阶段，大概率是模拟器SDK版本与项目代码SDK版本不一致引起的。
  • 解决方案：

    • 首先，确保Android Studio模拟器Device版本与代码SDK版本，两者保持一致

      • 如果模拟器Device版本是34，代码中的SDK也要是34，如图 image.png image.png

    • 其次，请确保已成功打开Android Studio模拟器，执行步骤如下：

      • 打开Android Studio -> open -> 打开你的项目下的android目录 -> 选择模拟器版本运行 -> 最后运行yarn android命令，如图：

      image.png 成功运行起来如下：

      image.png

      最后执行yarn android命令，才能正常编译andriod项目，并安装在模拟器中，如下： image.png

3. Android Studio模拟器问题

问题1：无法启动Android Studio模拟器

启动Android Studio，开发者常常遇到 Unable to launch Pixel Fold API 35 - The emulator process for AVD Pixel_Fold_API_35 has terminated. 错误。

  • 原因：

    • 1）SDK相关的依赖没有安装完整
    • 2）模拟器所在空间内存不足

  • 解决方案：

    • 首先，确保你的SDK相关的依赖已完整安装，具体参照RN官网安装 Android SDK
    • 其次，请确保你的模拟器所在目录的内存空间是充足的（至少 8GB 内存，推荐更多），macOS所在目录如下：

    image.png

问题2：无法安装Android Studio对应的SDK依赖包

安装Android Studio对应的依赖包，开发者常常遇到错误 requested actions did not complete successfully，Failed packages: - Sources for Android 34 (sources;android-34) - Android SDK Platform 34 (platforms;android-34)

  • 原因：
    • 1）网络不稳定
    • 2）SDK目录权限问题，如果Android Studio没有足够的权限访问或写入SDK目录，也会导致安装失败
  • 解决方案：

    • 确保你的网络连接是稳定的，使用稳定的使用VPN，尝试更换网络环境（如切换到更稳定的Wi-Fi或有线连接）。

    • 以管理员权限运行Android Studio，如果在 macOS 上，可以使用以下步骤

      • 使用终端命令以管理员权限启动 Android Studio
      sudo open /Applications/Android\ Studio.app

      输入密码后，Android Studio 将以管理员权限运行，然后以root的权限下载对应的SDK，下载完成后，再将对应的sdk复制到用户的目录下

      sudo mv /var/root/Library/Android/sdk/ /Users/xxx/Library/Android/sdk/

sudo chown -R $(whoami) /Users/xxx/Library/Android/sdk

      上述xxx需要替换你mac的名称

4. Gradle 构建问题

问题1：Gradle 守护进程崩溃问题

执行npx react-native run-android，开发者常常遇到错误 FAILURE: Build failed with an exception. * What went wrong: Gradle build daemon disappeared unexpectedly (it may have been killed or may have crashed)

  • 原因：
    • Gradle 守护进程不稳定引起的
    • 背后原因有很多，通常与系统版本、资源、Gradle 配置或 JVM 参数有关
    • 具体原因要认真分析日志hs_err_pidXXXX.log
  • 解决方案：

    • 增加 Gradle 的内存限制

      • 打开 android/gradle.properties 文件，修改或添加以下内容：
      org.gradle.jvmargs=-Xmx2048m

    • 清理 Gradle 缓存和构建

      cd android
./gradlew clean
cd ..
npx react-native run-android

    • 修改android/gradle.properties配置

    • Gradle 版本，确保你的 Gradle 版本和 Android Gradle 插件版本兼容

    • 笔者遇到这个问题，试过网上各种办法，依旧没有解决。

  • 最终解决方案：
    • 最终在stack overflow中发现一种解决办法，macOS的版本是有要求的，macOS 11+，而笔者检查了一下自己的mac版本，发现是macOS 10，于是升级macOS到14版本，最终解决了这个问题。

5. 沙盒环境expo-cli

问题1：expo预览问题

若开发者觉得Android Studio复杂，也可选择使用沙箱expo运行预览页面，具体可看RN官网指南，选择简易沙盒环境。安装完成后，执行expo start指令，如何扫描终端中的二维码？

  • 解决方案：
    • 前提条件：需要翻墙
    • 首先在手机上安装expo go
    • 使用expo go扫描二维码，即可进行预览
  • 建议：
    • 对于轻应用，不涉及修改原生组件，可使用该模式

react-native-cli vs expo-cli 区别总结：

特性react-native-cliexpo-cli
原生代码访问完全控制，能够自由修改和添加原生模块受限制，不能直接访问原生代码
第三方原生库支持完全支持，能够集成任意原生库仅支持Expo SDK提供的库，集成原生库需eject
打包方式手动配置签名和构建流程，复杂度较高提供Expo云打包服务，简单快速
构建速度较慢，需依赖本地环境的配置和资源构建速度快，Expo云服务可以快速打包
项目体积较大，包含完整的iOS和Android原生代码较小，依赖Expo SDK
适用场景适合复杂项目或需要使用大量原生功能的项目适合初学者或无需修改原生代码的简单项目
avatar
文章
阅读
粉丝