Expo 應用本地打包 APK/AAB 完整教學

背景

EAS Build 免費用戶經常需要排隊數小時才能完成打包，對於開發測試來說效率太低。本教學將指導你如何在本地環境直接打包 APK，5-10 分鐘即可完成。

測試及教學環境

macOS 系統（M1/M2 或 Intel）
已有 Expo 專案
安裝 Homebrew

步驟一：檢查專案類型

首先確認你的專案是否為 Expo 開發版本：

ls -la

如果看到android 和 ios 資料夾，代表已是開發版本，可直接跳到步驟三。

步驟二：轉換為開發版本（如需要）

如果專案是 Expo Managed 版本，需要先轉換：

npx expo run:android

這個指令會自動生成 android 資料夾並安裝相關依賴。

步驟三：安裝 Java 17 (當前是這個版本要求)

Android Gradle Plugin 需要 Java 17 才能運行：

brew install openjdk@17

步驟四：設定 Java 環境

臨時設定（單次使用）

export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home

永久設定（推薦）

echo 'export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home' >> ~/.zshrc
source ~/.zshrc

注意： Intel Mac 使用者路徑為 /usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home

確認設定成功

java -version
echo $JAVA_HOME

應該看到 Java 17 版本資訊。

步驟五：執行打包

進入 android 目錄並執行打包指令：

cd android
./gradlew assembleRelease

AAB (上傳 Play Store)

cd android
./gradlew bundleRelease

第一次執行會下載 Gradle，需要較長時間。後續打包會快很多。

步驟六：取得 APK 檔案

打包成功後，APK 檔案位置：

android/app/build/outputs/apk/release/app-release.apk

確認檔案存在：

ls -la app/build/outputs/apk/release/

打包aab版本將會另外再寫一篇文章

常見問題排解

問題 1：Java 版本錯誤

Android Gradle plugin requires Java 17 to run. You are currently using Java 11.

解決方法： 按照步驟三和四重新設定 Java 17

問題 2：JAVA_HOME 未生效

如果 export 指令無效，可直接在 gradle.properties 中設定：

echo "org.gradle.java.home=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home" >> android/gradle.properties

問題 3：Gradle Daemon 衝突

./gradlew --stop
./gradlew assembleRelease

問題4：Clear 再打包

//清理 Android 緩存
  cd android && ./gradlew clean && cd ..

// 清理 Metro 緩存並重新編譯
  npx expo r -c
  cd android && ./gradlew assembleRelease
 //其他clear 

./gradlew clean  //清理所有 Android 建置檔案
npx expo r -c //清理 Metro 和 Expo 緩存
npm cache clean --force //清理 npm 緩存
rm -rf node_modules && npm install //重裝依賴
./gradlew assembleRelease //重新編譯 Release APK

結語

本地打包雖然初次設定較複雜，但對於頻繁測試的開發流程來說更加高效。建議開發階段使用本地打包，正式發布時再使用 EAS Build 確保環境一致性。