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 區別總結：