macOS 初始化 Android 开发环境遇到的问题与总结

在 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 来加载新的环境变量。

• 经验总结：

  

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

• 如果遇到 adb: command not found 或其他类似问题，大概率是没有正确配置 SDK 路径。

• 重启终端后再次验证 adb devices 是否可以识别设备，如下：

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

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

• 解决方案：

  

• 在 Android 设备上，确保启用了 开发者模式 和 USB 调试。

• 当设备连接到电脑时，检查设备上是否弹出授权对话框，点击“允许”。

• 如果问题依然存在，可以尝试再次重新连接USB，直到弹出对话框，确保 USB 调试已授权。

• 若在macOS上连接Android 真机设备，还需要安装一个工具：Android File Transfer（可在Mac App Store上查找并安装）

问题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，以下是笔者发文时的官网快照

问题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 -> open -> 打开你的项目下的android目录 -> 选择模拟器版本运行 -> 最后运行yarn android命令，如图：

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

  

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

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

  成功运行起来如下：

  

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

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所在目录如下：

问题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目录，也会导致安装失败

• 解决方案：

• 使用终端命令以管理员权限启动 Android Studio

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

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

  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

• 解决方案：

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

• 增加 Gradle 的内存限制

  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 区别总结：